schema.yaml

Chaque champ d'une définition de schéma, pour la lecture ou l'écriture.

schema.yaml répertorie les fichiers de planification qu'un workflow crée. Il définit également leur ordre et le passage à l'implémentation.

Emplacement

Un schéma de projet se trouve sous openspec/schemas/<nom>/ :

openspec/schemas/review-first/
├── schema.yaml
└── templates/
    ├── proposal.md
    └── tasks.md

OpenSpec vérifie trois emplacements pour ce répertoire. La première correspondance l'emporte.

Copie	Répertoire
1. Projet	<projet>/openspec/schemas/<nom>/
2. Utilisateur, macOS et Linux	~/.local/share/openspec/schemas/<nom>/
2. Utilisateur, Windows	%LOCALAPPDATA%\openspec\schemas\<nom>\
3. Package	Les schémas installés avec la CLI

Si XDG_DATA_HOME est défini, le répertoire utilisateur se déplace vers $XDG_DATA_HOME/openspec/schemas/<nom>/ sur toutes les plateformes.

Le nom du répertoire est la clé de recherche utilisée par --schema, config.yaml et .openspec.yaml. Si le champ name diffère du nom du répertoire, OpenSpec utilise quand même le nom du répertoire pour la recherche.

openspec schema which <nom> affiche le répertoire actif et les copies de priorité inférieure qu'il masque.

Champs de premier niveau

Champ	Contrat
name	Obligatoire. Une chaîne non vide stockée comme nom du schéma. La recherche utilise toujours le nom du répertoire.
version	Obligatoire. Un entier positif stocké comme révision du schéma. La valeur ne modifie pas le comportement d'OpenSpec.
description	Une chaîne facultative affichée par openspec schemas. Sans valeur, le schéma n'a pas de description.
artifacts	Obligatoire. Une liste non vide d'entrées d'artefact.
apply	Paramètres apply facultatifs. Sans bloc, OpenSpec utilise les valeurs par défaut d'apply.

Champs d'artefact

Chaque entrée sous artifacts définit un fichier de planification ou un ensemble de fichiers.

Champ	Contrat
id	Obligatoire. Une chaîne unique et non vide utilisée dans les dépendances, les règles de projet, les commandes et les paramètres d'apply.
generates	Obligatoire. Un chemin relatif ou un glob indiquant à l'agent où écrire l'artefact dans le dossier de changement.
description	Obligatoire. Une chaîne qui étiquette l'artefact dans les instructions envoyées à l'agent.
template	Obligatoire. Un chemin relatif vers le format de l'artefact dans le dossier templates/ du schéma.
instruction	Conseils facultatifs indiquant à l'agent quel contenu produire.
requires	Une liste d'ID d'artefacts qui doivent être terminés au préalable. Défaut : [].

generates

Le chemin part du dossier de changement. Pour un changement nommé add-auth :

generates: proposal.md

L'artefact se place ici :

openspec/changes/add-auth/proposal.md

Un glob peut correspondre à plusieurs fichiers :

generates: specs/**/*.md

Cela correspond aux fichiers Markdown sous openspec/changes/add-auth/specs/.

OpenSpec reconnaît ces formes de glob dans generates :

• Jokers et classes de caractères : valeurs contenant *, ? ou [, telles que specs/**/*.md et review-[ab].md.
• Expansions d'accolades : alternatives telles que review-{api,ui}.md et plages telles que file-{1..3}.md.
• Extglobs : motifs tels que @(proposal|design).md, +(proposal|design).md et !(proposal|design).md.

Noms de fichiers littéraux : un ! initial seul ne constitue pas un glob. Utilisez generates: '!review.md' pour nommer ce fichier. Les parenthèses simples telles que (proposal|design).md et les accolades à un seul élément telles que review-{api}.md restent également littérales.

OpenSpec rejette les chemins absolus, les chemins contenant un segment .. et les globs qui imbriquent des accolades ou des parenthèses sur plus de 16 niveaux, comme {a,{b,{c,...}}}. Les motifs réels nécessitent un ou deux niveaux. Il rejette également un glob dont les accolades se développent en plus de 1 024 motifs, comme {a,b} répété onze fois ou une plage comme file-{1..5000}.md. L'erreur indique Artifact output pattern expands to more than 1024 patterns. Les motifs réels se développent en une poignée.

Achèvement

OpenSpec vérifie si la sortie existe. Il ne lit pas le fichier pour décider si l'artefact est terminé.

Valeur de generates	Terminé quand
proposal.md	Ce fichier existe.
specs/**/*.md	Le glob correspond à au moins un fichier.

template

Le chemin part du dossier templates/ du schéma. Dans le schéma review-first :

template: proposal.md

OpenSpec lit ce fichier :

openspec/schemas/review-first/templates/proposal.md

OpenSpec remet le contenu du modèle à l'agent comme format de sortie. Il ne copie pas le modèle dans le dossier de changement.

OpenSpec rejette les chemins absolus et les chemins contenant un segment ...

requires

• Dépendances : chaque ID dans requires doit désigner un autre artefact du même schéma.
• État prêt : un artefact devient prêt une fois que toutes ses dépendances sont terminées.
• Graphes invalides : les ID manquants, les ID en double et les cycles de dépendance font échouer la validation.
• Égalités : lorsque plusieurs artefacts sont prêts, leur ordre dans artifacts détermine celui qu'OpenSpec renvoie en premier.

Champs d'apply

apply définit ce qui doit exister avant le démarrage de l'implémentation.

Champ	Contrat
requires	Obligatoire. Une liste non vide d'artefacts qui doivent exister avant que les instructions d'apply deviennent prêtes.
tracks	Un chemin relatif ou un glob facultatif pour les fichiers de tâches Markdown dans le dossier de changement. Défaut : null.
instruction	Conseils facultatifs envoyés à l'agent lorsque apply est prêt. OpenSpec utilise des conseils intégrés par défaut.

Les requires d'artefact contrôlent l'ordre de planification. apply.requires contrôle le moment où les instructions d'apply deviennent prêtes.

tracks

Le chemin part du dossier de changement. Pour un changement nommé add-auth, tracks: tasks.md lit :

openspec/changes/add-auth/tasks.md

Un glob tel que tracks: "**/tasks.md" lit chaque fichier correspondant, comme backend/tasks.md et frontend/tasks.md. OpenSpec combine leurs tâches et leur progression. Utilisez la même valeur pour le champ generates d'un artefact afin que le statut et la liste suivent les mêmes fichiers. Les limites d'accolades de generates (16 niveaux de profondeur, 1 024 motifs développés) s'appliquent ici aussi.

Apply reste bloqué si aucun fichier ne correspond ou si les fichiers correspondants ne contiennent aucune case à cocher avec du texte de tâche. OpenSpec compte ces formes de cases à cocher :

- [ ] Tâche en attente
- [x] Tâche terminée
* [X] Tâche terminée
+ [ ] Tâche en attente
1. [ ] Tâche en attente
2) [x] Tâche terminée

N'importe quel marqueur de liste Markdown fonctionne : -, *, + ou un nombre de neuf chiffres maximum suivi de . ou ). Les espaces initiaux sont autorisés. La section tasks.md de la page spec-driven définit le format plus strict produit par le schéma par défaut.

Les fichiers suivis déterminent l'état d'apply :

• blocked : aucun fichier ne correspond, ou aucun fichier lisible ne contient de case à cocher avec du texte de tâche.
• ready : au moins une tâche est en attente, ou un fichier correspondant n'a pas pu être lu pendant qu'un autre fournit des tâches.
• all_done : chaque tâche suivie est cochée et chaque fichier correspondant a été lu.

Si un fichier correspondant ne peut pas être lu, apply conserve les tâches et la progression des fichiers lisibles mais ne marque pas le changement comme all_done. La sortie JSON d'apply identifie chaque fichier indisponible et la raison.

OpenSpec rejette les chemins absolus et les chemins contenant un segment ...

Valeurs par défaut d'apply

Comportement	Défaut
Artefacts obligatoires	Tous les artefacts du schéma
Suivi de progression	Aucun fichier suivi
Conseils à l'agent	Conseils d'apply intégrés

Exemple complet

name: review-first
version: 1
description: Proposal and implementation checklist

artifacts:
  - id: proposal
    generates: proposal.md
    description: Why the change is needed and what it affects
    template: proposal.md
    instruction: |
      Explain the problem, the proposed change, and its impact.
    requires: []

  - id: tasks
    generates: tasks.md
    description: Trackable implementation checklist
    template: tasks.md
    instruction: |
      Break the approved proposal into ordered implementation tasks.
    requires:
      - proposal

apply:
  requires:
    - tasks
  tracks: tasks.md
  instruction: |
    Work through the pending tasks and mark each one complete.

Validation

openspec schema validate <nom> vérifie :

• Les types de champs et les champs obligatoires
• Les chemins relatifs
• Les ID d'artefacts, les dépendances et les cycles
• Les ID de apply.requires : chacun doit être un artefact du schéma
• Les fichiers de modèle

Un schéma avec un ID inconnu dans apply.requires ne se charge pas, donc chaque commande qui l'utilise signale l'erreur.

La validation avertit, sans faire échouer, lorsque apply.tracks n'est pas exactement égal à la valeur generates d'un artefact. OpenSpec trouve l'artefact suivi en comparant ces deux chaînes, donc toute autre valeur l'empêche de déterminer à quel artefact appartient la progression du fichier. Cela inclut une faute de frappe comme task.md, mais aussi tracks: tasks/main.md face à generates: tasks/*.md, où le glob produit bien le fichier mais les chaînes diffèrent toujours. Apply continue de lire le fichier dans les deux cas, mais openspec list et openspec status comptent tasks.md à la place.

La validation ne détecte pas ces erreurs :

Erreur	Conséquence
Un champ est mal orthographié, comme instrution	OpenSpec l'ignore. La validation ne signale pas la faute de frappe.
name diffère du répertoire du schéma	La validation passe. OpenSpec utilise quand même le nom du répertoire pour la recherche.