Métadonnées de changement (.openspec.yaml)

Les champs pris en charge et les règles de validation pour les métadonnées stockées avec chaque changement.

Emplacement

Chaque changement conserve ses métadonnées dans openspec/changes/<change-name>/.openspec.yaml, à côté de ses artefacts. La création d'un changement écrit le fichier avec schema et created renseignés.

Champs

Clé	Type	Requis	Effet
schema	chaîne	Oui	Le schéma de workflow suivi par ce changement
created	chaîne, YYYY-MM-DD	Non	Enregistre la date de création du changement
goal	chaîne	Non	Enregistre l'objectif du changement
affected_areas	liste de chaînes	Non	Enregistre les zones que le changement est susceptible de modifier
initiative	map : store et id	Non	Enregistre l'initiative à laquelle appartient ce changement
skip_specs	booléen	Non	Déclare que le changement ne produit aucune modification de spec, de sorte que zéro modification est valide
retire_capabilities	booléen	Non	Autorise archive à supprimer une capacité que ce changement vide

schema

Le schéma de workflow suivi par ce changement. Il est défini lors de la création du changement et prime sur la configuration du projet, de sorte qu'un changement conserve son schéma même si openspec/config.yaml change par la suite. Exécutez openspec schemas pour lister les noms de schémas disponibles.

initiative

L'initiative à laquelle appartient ce changement, sous la forme d'un identifiant de store et d'un identifiant d'initiative, tous deux en kebab-case :

initiative:
  store: platform-specs
  id: unify-billing

Les clés autres que store et id sont rejetées. Aucune commande ne lit ce lien aujourd'hui.

skip_specs

Déclare que le changement ne produit intentionnellement aucune modification de spec : un refactoring pur, un changement d'outillage ou de documentation. Lorsqu'il est défini, la validation accepte zéro modification, et les artefacts qui généreraient des fichiers de spec sont considérés comme complets. Le définir alors que des fichiers de spec existent sous specs/ est une erreur de validation.

retire_capabilities

Autorise archive à retirer une capacité. Lorsque les deltas REMOVED de ce changement suppriment la dernière exigence d'une capacité, archive supprime la spec principale de cette capacité au lieu de s'arrêter. Ce drapeau existe car la suppression n'est récupérable que depuis git ; elle reste donc à la discrétion de l'auteur.

Clés d'extension

Une clé de premier niveau qui commence par un x- minuscule vous appartient, pour des données qu'un autre outil ou votre équipe conserve à côté du changement, comme un identifiant de suivi ou un propriétaire :

schema: spec-driven
x-tracker: SB-5497
x-jiraKey: ABC-1
x-owner:
  team: payments

• Nom : le préfixe x- minuscule suivi d'au moins un caractère, sans espace nulle part. Toutes les casses ou orthographes sont acceptées après le préfixe, donc x-jiraKey et x-trackerID sont valides. X-Tracker, un x- nu et x- tracker ne le sont pas, et sont signalés comme des clés inconnues.
• Valeur : toute valeur YAML. OpenSpec ne la lit pas et ne la valide pas, et elle ne modifie aucun comportement.
• Portée : uniquement au niveau supérieur. Une clé x- à l'intérieur de initiative est toujours rejetée, comme toute autre clé à cet endroit.
• Validation : les clés d'extension ne sont jamais signalées comme inconnues, donc openspec validate --strict passe pour un changement qui les porte.
• Archive : le fichier se déplace avec le changement sans modification, clés d'extension incluses.

Exemple

Un fichier .openspec.yaml renseigné :

schema: spec-driven
created: 2026-08-14
goal: Add magic-link login to the API
affected_areas:
  - auth
  - api

Validation

Le fichier est validé chaque fois qu'une commande l'écrit ou le lit. Une écriture qui échoue à la validation lève une exception et n'écrit rien. La lecture d'un fichier existant échoue en cas de YAML invalide, d'un champ qui enfreint son contrat ou d'un nom de schéma indisponible. Un fichier manquant n'est pas une erreur, et le changement est traité comme n'ayant pas de métadonnées.

Contrairement à config.yaml, les mauvaises valeurs ne sont jamais ignorées avec un avertissement. Une erreur de métadonnées arrête la commande.

• Clés de niveau supérieur inconnues : OpenSpec les ignore. status, instructions, validate et archive signalent qu'elles n'ont aucun effet. La sortie JSON porte l'avertissement dans son résultat structuré. Les clés d'extension ne sont pas inconnues et ne sont jamais signalées.
• Validation stricte : openspec validate --strict traite un avertissement de clé inconnue comme un échec. Un changement dont les seules clés supplémentaires sont des clés d'extension passe.