schema.yaml

Elk veld van een schemadefinitie, voor het lezen of schrijven ervan.

schema.yaml geeft de planningbestanden weer die een workflow maakt. Het definieert ook hun volgorde en de overdracht naar implementatie.

Locatie

Een projectschema bevindt zich onder openspec/schemas/<name>/:

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

OpenSpec controleert drie locaties voor die map. De eerste overeenkomst wint.

Kopie	Map
1. Project	<project>/openspec/schemas/<name>/
2. Gebruiker, macOS en Linux	~/.local/share/openspec/schemas/<name>/
2. Gebruiker, Windows	%LOCALAPPDATA%\openspec\schemas\<name>\
3. Pakket	De schemas geïnstalleerd met de CLI

Als XDG_DATA_HOME is ingesteld, verhuist de gebruikersmap naar $XDG_DATA_HOME/openspec/schemas/<name>/ op elk platform.

De mapnaam is de zoekopdrachtssleutel die wordt gebruikt door --schema, config.yaml en .openspec.yaml. Als het veld name verschilt van de mapnaam, gebruikt OpenSpec nog steeds de mapnaam voor de opzoeking.

openspec schema which <name> drukt de actieve map af en eventuele kopieën met een lagere prioriteit die worden verborgen.

Velden op topniveau

Veld	Contract
name	Verplicht. Een niet-lege string die wordt opgeslagen als de schemanaam. Opzoeking gebruikt nog steeds de mapnaam.
version	Verplicht. Een positief geheel getal dat wordt opgeslagen als de herschikkingsversie van het schema. De waarde verandert het gedrag van OpenSpec niet.
description	Een optionele string die wordt afgedrukt door openspec schemas. Zonder waarde heeft het schema geen beschrijving.
artifacts	Verplicht. Een niet-lege lijst van artifactvermeldingen.
apply	Optionele toepassingsinstellingen. Zonder blok gebruikt OpenSpec de standaardwaarden voor toepassen.

Artifactvelden

Elke vermelding onder artifacts definieert één planningbestand of een reeks bestanden.

Veld	Contract
id	Verplicht. Een unieke, niet-lege string die wordt gebruikt in afhankelijkheden, projectregels, opdrachten en toepassingsinstellingen.
generates	Verplicht. Een relatief pad of glob die de agent vertelt waar het artifact binnen de wijzigingsmap moet worden weggeschreven.
description	Verplicht. Een string die het artifact labelt in instructies die naar de agent worden gestuurd.
template	Verplicht. Een relatief pad naar het formaat van het artifact in de templates/-map van het schema.
instruction	Optionele begeleiding die de agent vertelt welke inhoud moet worden geproduceerd.
requires	Een lijst van artifact-ID's die eerst voltooid moeten zijn. Standaard: [].

generates

Het pad begint vanaf de wijzigingsmap. Voor een wijziging met de naam add-auth:

generates: proposal.md

Het artifact gaat hierheen:

openspec/changes/add-auth/proposal.md

Een glob kan meerdere bestanden matchen:

generates: specs/**/*.md

Dit matcht Markdown-bestanden onder openspec/changes/add-auth/specs/.

OpenSpec herkent deze globvormen in generates:

• Jokers en tekenklassen: waarden die *, ? of [ bevatten, zoals specs/**/*.md en review-[ab].md.
• Blokuitbreidingen: alternatieven zoals review-{api,ui}.md en bereiken zoals file-{1..3}.md.
• Extglobs: patronen zoals @(proposal|design).md, +(proposal|design).md en !(proposal|design).md.

Letterlijke bestandsnamen: een voorafgaande ! alleen maakt geen glob. Gebruik generates: '!review.md' om dat bestand te benoemen. Platte haakjes zoals (proposal|design).md en enkelvoudige blokhaken zoals review-{api}.md blijven ook letterlijk.

OpenSpec weigert absolute paden, paden die een ..-segment bevatten, en globs die blokhaken of haakjes meer dan 16 niveaus diep nesten, zoals {a,{b,{c,...}}}. Echte patronen hebben één of twee niveaus nodig. Het weigert ook een glob waarvan de blokhaken uitbreiden tot meer dan 1.024 patronen, zoals {a,b} elf keer herhaald of een bereik zoals file-{1..5000}.md. De foutmelding luidt Artifact output pattern expands to more than 1024 patterns. Echte patronen breiden uit tot een handvol.

Voltooiing

OpenSpec controleert of de uitvoer bestaat. Het leest het bestand niet om te beslissen of het artifact voltooid is.

generates-waarde	Voltooid wanneer
proposal.md	Dat bestand bestaat.
specs/**/*.md	De glob matcht ten minste één bestand.

template

Het pad begint vanaf de templates/-map van het schema. In het review-first-schema:

template: proposal.md

OpenSpec leest dit bestand:

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

OpenSpec geeft de inhoud van de sjabloon aan de agent als het uitvoerformaat. Het kopieert de sjabloon niet naar de wijzigingsmap.

OpenSpec weigert absolute paden en paden die een ..-segment bevatten.

requires

• Afhankelijkheden: elke ID in requires moet een ander artifact in hetzelfde schema benoemen.
• Klaarstaat: een artifact wordt klaar nadat al zijn afhankelijkheden voltooid zijn.
• Ongeldige grafen: ontbrekende IDs, dubbele IDs en afhankelijkheidscycli mislukken bij validatie.
• Gelijke stand: wanneer meerdere artifacts klaar zijn, bepaalt hun volgorde in artifacts welk er eerst door OpenSpec wordt teruggegeven.

Apply-velden

apply definieert wat er moet bestaan voordat implementatie start.

Veld	Contract
requires	Verplicht. Een niet-lege lijst van artifacts die moeten bestaan voordat toepassingsinstructies klaar zijn.
tracks	Een optioneel relatief pad of glob voor Markdown-taakbestanden in de wijzigingsmap. Standaard: null.
instruction	Optionele begeleiding die naar de agent wordt gestuurd wanneer apply klaar is. OpenSpec gebruikt standaard ingebouwde begeleiding.

Artifact requires regelt de planningsvolgorde. apply.requires regelt wanneer toepassingsinstructies klaar zijn.

tracks

Het pad begint vanaf de wijzigingsmap. Voor een wijziging met de naam add-auth, tracks: tasks.md leest:

openspec/changes/add-auth/tasks.md

Een glob zoals tracks: "**/tasks.md" leest elk matchend bestand, zoals backend/tasks.md en frontend/tasks.md. OpenSpec combineert hun taken en voortgang. Gebruik dezelfde waarde voor het generates-veld van een artifact zodat status en lijst dezelfde bestanden volgen. De blokgrenzen van generates (16 niveaus diep, 1.024 uitgebreide patronen) gelden hier ook.

Apply blijft geblokkeerd als er geen bestand matcht of de gematchte bestanden geen checkbox met taaktekst bevatten. OpenSpec telt deze checkboxvormen:

- [ ] Pending task
- [x] Completed task
* [X] Completed task
+ [ ] Pending task
1. [ ] Pending task
2) [x] Completed task

Elke Markdown-lijstmarker werkt: -, *, +, of een cijfer van maximaan negen cijfers gevolgd door . of ). Vooraanstaande spaties zijn toegestaan. De sectie tasks.md van de spec-driven pagina definieert het strengere formaat dat wordt geproduceerd door het standaardschema.

De getrackte bestanden sturen de apply-status:

• blocked: geen bestand matcht, of geen leesbaar bestand heeft een checkbox met taaktekst.
• ready: ten minste één taak staat open, of een gematcht bestand kon niet worden gelezen terwijl een ander taken biedt.
• all_done: elke getrackte taak is aangevinkt en elk gematcht bestand is gelezen.

Als een gematcht bestand niet kan worden gelezen, houdt apply de taken en voortgang van leesbare bestanden vast maar markeert het de wijziging niet als all_done. Toepassen JSON-uitvoer identificeert elk ontoegankelijk bestand en de reden.

OpenSpec weigert absolute paden en paden die een ..-segment bevatten.

Standaardwaarden toepassen

Gedrag	Standaard
Vereiste artifacts	Elk artifact in het schema
Voortgangstracking	Geen getrackt bestand
Agentbegeleiding	Ingebouwde toepassingbegeleiding

Compleet voorbeeld

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.

Validatie

openspec schema validate <name> controleert:

• Veldtypen en verplichte velden
• Relatieve paden
• Artifact-ID's, afhankelijkheden en cycli
• apply.requires-ID's: elk moet een artifact in het schema zijn
• Sjabloonbestanden

Een schema met een onbekende apply.requires-ID laadt niet, dus elk commando dat het gebruikt rapporteert de fout.

Validatie waarschuwt, zonder te falen, wanneer apply.tracks niet exact gelijk is aan de generates-waarde van enig artifact. OpenSpec vindt het getrackte artifact door die twee strings te vergelijken, dus alles anders laat het unable om te vertellen aan welk artifact de voortgang van het bestand toebehoort. Dat omvat een typefout zoals task.md, en ook tracks: tasks/main.md tegenover generates: tasks/*.md, waarbij de glob het bestand wel produceert maar de strings nog steeds verschillen. Apply blijft het bestand op beide manieren lezen, maar openspec list en openspec status tellen tasks.md in plaats daarvan.

Validatie vangt deze fouten niet:

Fout	Wat gebeurt er
Een veld is verkeerd gespeld, zoals instrution	OpenSpec negeert het. Validatie rapporteert de typefout niet.
name verschilt van de schemamap	Validatie slaagt. OpenSpec gebruikt nog steeds de mapnaam voor opzoeking.