Extensions UCP : noms, parents et versions

Déclarer une extension UCP : noms, parents, versions et schémas. Voir pourquoi Discount reste négociable avec Checkout seul, sous conditions.

Publiée le 20 septembre 2026 , révisée le 22 septembre 2026 . Rattachée à le framework UCP.

Une extension UCP ajoute un comportement à une capacité existante. Son nom ne suffit pas à l’activer : marchand et plateforme doivent partager une version, puis disposer d’un parent encore présent dans l’intersection. Pour une extension multi-parent, au moins un parent doit rester dans l’intersection, et non tous ses parents.

Cette note décrit la spécification UCP 2026-08-25, dans son état consulté le 22 septembre 2026. Elle distingue les extensions définies par UCP des extensions tierces, dont les auteurs gèrent les versions séparément.

Nommer une extension et identifier son auteur

Les noms de capacités suivent le format {domaine-inversé}.{service}.{capacité}. Ainsi, dev.ucp.shopping.checkout désigne Checkout dans l’espace de noms UCP. Un éditeur qui contrôle example.com pourrait nommer une extension de paiement com.example.payments.installments; ce nom sert ici d’illustration, sans désigner un produit disponible.

L’espace dev.ucp.* est réservé aux capacités approuvées par la gouvernance UCP. Une extension personnalisée utilise l’espace de noms de son auteur. Le champ schema indique son schéma machine; spec, facultatif, renvoie vers sa documentation humaine. Ce nom n’est donc pas une route d’API.

La plateforme doit vérifier la correspondance entre le nom et le domaine qui sert le schéma avant de le récupérer. Cette vérification établit une provenance, pas une garantie de qualité ou de confiance. Les règles détaillées figurent dans Namespace Governance.

Déclarer un ou plusieurs parents

Le champ extends prend une chaîne pour un parent unique, par exemple dev.ucp.shopping.checkout, ou un tableau pour plusieurs parents.

L’extension officielle Discount peut étendre Cart, Checkout ou les deux. Voici un extrait de déclaration à placer dans ucp.capabilities. Il illustre le cas multi-parent; ce n’est ni un profil complet ni une transaction à envoyer telle quelle.

{
  "dev.ucp.shopping.discount": [
    {
      "version": "2026-08-25",
      "extends": [
        "dev.ucp.shopping.cart",
        "dev.ucp.shopping.checkout"
      ],
      "spec": "https://ucp.dev/2026-08-25/specification/shopping/extensions/discount/",
      "schema": "https://ucp.dev/2026-08-25/schemas/shopping/discount.json"
    }
  ]
}

Déclarer les deux parents ne rend pas leur présence simultanée obligatoire pour conserver l’extension. Cela ne permet pas non plus d’utiliser Cart lorsqu’il n’a pas été négocié : il faut vérifier la ressource effectivement étendue avant d’y appliquer Discount.

Négocier : une version commune, puis des parents présents

L’algorithme d’intersection procède dans cet ordre :

Retenir les capacités dont le nom figure dans les deux profils.
Pour chacune, chercher des versions exactement identiques dans les deux déclarations. Sans version commune, l’exclure. S’il existe plusieurs versions communes, retenir la plus récente parmi celles-ci.
Retirer une extension si aucun de ses parents n’est encore présent.
Répéter ce retrait jusqu’à stabilisation, car supprimer une extension peut en rendre une autre orpheline.

Une date plus récente ne prouve donc pas à elle seule la compatibilité. Le nom, la version partagée et les dépendances comptent séparément.

Exemple : Discount avec Checkout seul

Dans cette matrice, les deux profils ont sélectionné ucp.version = 2026-08-25. Ils déclarent Discount à cette même version, avec Cart et Checkout comme parents, et les autres vérifications de déclaration sont supposées satisfaites. Le tableau isole le contrôle des parents après intersection :

Checkout présent	Cart présent	Décision sur Discount à cette étape
Oui	Non	Conservé : Checkout suffit
Non	Oui	Conservé : Cart suffit
Oui	Oui	Conservé : les deux parents sont présents
Non	Non	Retiré : aucun parent ne subsiste

Si Discount n’était déclaré que par une partie, il serait déjà exclu avant ce contrôle. Un résultat « conservé » dans ce tableau ne certifie ni la validité finale des schémas ni le fonctionnement d’une intégration.

Distinguer la version UCP de celle d’une extension tierce

Pour une release UCP notée D, le profil sélectionne ucp.version = D. Les services, capacités et extensions définis par UCP doivent alors déclarer cette même version D. Dans l’exemple précédent, Checkout et Discount déclarent donc 2026-08-25.

Une plateforme doit rejeter une entrée dev.ucp.* dont la version diffère de celle du profil. Une ancienne release UCP se sélectionne par un profil séparé annoncé dans supported_versions, et non en ajoutant d’anciennes versions dev.ucp.* au profil courant.

Les extensions tierces suivent une autre règle : leur auteur choisit leur version et leur cadence de publication. Cette indépendance ne dispense ni d’une version commune entre marchand et plateforme, ni de la vérification des versions UCP dont elles dépendent. Les versions des payment handlers sont également contrôlées par leurs auteurs. Voir Component Versioning and Release Snapshots.

La date d’une release identifie une ligne de compatibilité dont les documents peuvent recevoir des correctifs rétroportés. Pour documenter une intégration, conserver aussi la date de consultation et la copie des schémas utilisés évite de confondre deux états successifs d’une même release. Cette trace documentaire ne remplace pas les règles de cache et de récupération des schémas.

Composer les schémas sans perdre leurs contraintes

UCP demande aux définitions de transport OpenAPI ou OpenRPC de référencer les schémas de base. Les schémas d’extension décrivent leurs ajouts et leur composition avec ces bases via allOf.

Chaque parent déclaré dans extends doit avoir une entrée correspondante dans $defs, nommée exactement avec son identifiant complet. Pour une opération Checkout, la résolution utilise l’entrée dev.ucp.shopping.checkout; la présence d’une extension multi-parent ne signifie pas qu’il faut appliquer à cette opération le schéma de Cart. Voir Extension Schema Pattern.

En JSON Schema, allOf impose de satisfaire tous les sous-schémas. Ce n’est pas une fusion qui efface les contraintes du parent. Par exemple, combiner un type entier avec un minimum de zéro accepte 3, mais refuse -1 et 1.5. Cette distinction est expliquée dans la documentation JSON Schema.

La spécification recommande aux auteurs de déclarer un objet requires dans le schéma pour préciser les versions de protocole et de capacités requises. Ces bornes vérifient les versions déjà sélectionnées; elles ne remplacent pas la négociation. Lorsqu’elles sont présentes, leur contrôle est obligatoire pendant la résolution. Une extension incompatible est exclue, puis les extensions orphelines sont à nouveau retirées. Voir Version Requirements.

Préparer les vérifications d’intégration

Avant de compter sur une extension, documenter et vérifier :

son auteur, son nom, son schéma et la sémantique des champs ajoutés;
la cohérence des versions UCP et les versions tierces réellement partagées;
le résultat avec un parent présent, avec tous les parents absents et avec une chaîne de dépendances;
les contraintes requires, puis les requêtes et réponses face aux schémas composés;
le comportement prévu lorsque l’extension facultative n’est pas négociée.

Ces vérifications portent sur les capacités réellement déclarées par les deux parties. Elles ne permettent pas de supposer qu’un produit ou un prestataire prend en charge une extension donnée. Pour replacer la déclaration dans son contexte, consulter la note sur le manifeste UCP et la grille de décision du framework UCP.

Sources

Revenir à le framework UCP · Toutes les notes · Read in English