schema.yaml

Jedes Feld einer Schema-Definition, zum Lesen oder Schreiben.

schema.yaml listet die Planungsdateien auf, die ein Workflow erstellt. Es definiert auch deren Reihenfolge und die Übergabe an die Implementierung.

Ort

Ein Projektschema liegt unter openspec/schemas/<name>/:

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

OpenSpec prüft drei Orte für dieses Verzeichnis. Die erste Übereinstimmung gewinnt.

Kopie	Verzeichnis
1. Projekt	<project>/openspec/schemas/<name>/
2. Benutzer, macOS und Linux	~/.local/share/openspec/schemas/<name>/
2. Benutzer, Windows	%LOCALAPPDATA%\openspec\schemas\<name>\
3. Paket	Die mit der CLI installierten Schemas

Wenn XDG_DATA_HOME gesetzt ist, verschiebt sich das Benutzerverzeichnis auf $XDG_DATA_HOME/openspec/schemas/<name>/ auf allen Plattformen.

Der Verzeichnisname ist der Suchschlüssel, der von --schema, config.yaml und .openspec.yaml verwendet wird. Wenn das Feld name vom Verzeichnisnamen abweicht, verwendet OpenSpec für die Suche weiterhin den Verzeichnisnamen.

openspec schema which <name> gibt das aktive Verzeichnis und alle darunter liegenden Kopien aus, die es verbirgt.

Felder auf oberster Ebene

Feld	Vertrag
name	Erforderlich. Ein nicht-leerer String, der als Schema-Name gespeichert wird. Die Suche verwendet weiterhin den Verzeichnisnamen.
version	Erforderlich. Eine positive ganze Zahl, die als Schema-Revision gespepeichert wird. Der Wert ändert das Verhalten von OpenSpec nicht.
description	Ein optionaler String, der von openspec schemas ausgegeben wird. Ohne Wert hat das Schema keine Beschreibung.
artifacts	Erforderlich. Eine nicht-leere Liste von Artefakt-Einträgen.
apply	Optionale Apply-Einstellungen. Ohne Block verwendet OpenSpec die Apply-Standardwerte.

Artefakt-Felder

Jeder Eintrag unter artifacts definiert eine Planungsdatei oder eine Gruppe von Dateien.

Feld	Vertrag
id	Erforderlich. Ein eindeutiger, nicht-leerer String, der in Abhängigkeiten, Projektregeln, Befehlen und Apply-Einstellungen verwendet wird.
generates	Erforderlich. Ein relativer Pfad oder Glob, der dem Agenten angibt, wo das Artefakt im Änderungsordner geschrieben werden soll.
description	Erforderlich. Ein String, der das Artefakt in den an den Agenten gesendeten Anweisungen beschriftet.
template	Erforderlich. Ein relativer Pfad zum Format des Artefakts im templates/-Ordner des Schemas.
instruction	Optionale Anleitung, die dem Agenten mitteilt, welchen Inhalt er erstellen soll.
requires	Eine Liste von Artefakt-IDs, die zuerst abgeschlossen sein müssen. Standard: [].

generates

Der Pfad beginnt im Änderungsordner. Für eine Änderung namens add-auth:

generates: proposal.md

Das Artefakt landet hier:

openspec/changes/add-auth/proposal.md

Ein Glob kann mehrere Dateien erfassen:

generates: specs/**/*.md

Dies erfasst Markdown-Dateien unter openspec/changes/add-auth/specs/.

OpenSpec erkennt diese Glob-Formen in generates:

• Wildcards und Zeichenklassen: Werte, die *, ? oder [ enthalten, wie specs/**/*.md und review-[ab].md.
• Brace-Expansionen: Alternativen wie review-{api,ui}.md und Bereiche wie file-{1..3}.md.
• Extglobs: Muster wie @(proposal|design).md, +(proposal|design).md und !(proposal|design).md.

Literale Dateinamen: Ein führendes ! allein macht noch kein Glob. Verwenden Sie generates: '!review.md', um diese Datei zu benennen. Einfache Klammern wie (proposal|design).md und Ein-Element-Braces wie review-{api}.md bleiben ebenfalls literal.

OpenSpec verwirft absolute Pfade, Pfade mit einem ..-Segment und Globs, die Braces oder Klammern mehr als 16 Ebenen tief verschachteln, wie {a,{b,{c,...}}}. Echte Muster benötigen eine oder zwei Ebenen. Es verwirft auch einen Glob, dessen Braces sich zu mehr als 1.024 Mustern erweitern, wie {a,b} elfmal wiederholt oder ein Bereich wie file-{1..5000}.md. Die Fehlermeldung lautet Artifact output pattern expands to more than 1024 patterns. Echte Muster erweitern sich auf eine Handvoll.

Abschluss

OpenSpec prüft, ob das Ergebnis existiert. Es liest die Datei nicht, um zu entscheiden, ob das Artefakt abgeschlossen ist.

generates-Wert	Abgeschlossen, wenn
proposal.md	Diese Datei existiert.
specs/**/*.md	Der Glob mindestens eine Datei erfasst.

template

Der Pfad beginnt im templates/-Ordner des Schemas. Im review-first-Schema:

template: proposal.md

OpenSpec liest diese Datei:

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

OpenSpec übergibt den Inhalt der Vorlage an den Agenten als Ausgabeformat. Es kopiert die Vorlage nicht in den Änderungsordner.

OpenSpec verwirft absolute Pfade und Pfade mit einem ..-Segment.

requires

• Abhängigkeiten: Jede ID in requires muss ein anderes Artefakt im selben Schema benennen.
• Bereitschaftsstatus: Ein Artefakt wird bereit, nachdem alle seine Abhängigkeiten abgeschlossen sind.
• Ungültige Graphen: Fehlende IDs, doppelte IDs und Abhängigkeitszyklen führen zu einem Validierungsfehler.
• Gleichstand: Wenn mehrere Artefakte bereit sind, entscheidet ihre Reihenfolge in artifacts, welches OpenSpec zuerst zurückgibt.

Apply-Felder

apply definiert, was vorhanden sein muss, bevor die Implementierung beginnt.

Feld	Vertrag
requires	Erforderlich. Eine nicht-leere Liste von Artefakten, die vorhanden sein müssen, bevor Apply-Anweisungen bereit werden.
tracks	Ein optionaler relativer Pfad oder Glob für Markdown-Aufgabendateien im Änderungsordner. Standard: null.
instruction	Optionale Anleitung, die an den Agenten gesendet wird, wenn Apply bereit ist. OpenSpec verwendet standardmäßig integrierte Anleitungen.

Artefakt-requires steuert die Planungsreihenfolge. apply.requires steuert, wann Apply-Anweisungen bereit werden.

tracks

Der Pfad beginnt im Änderungsordner. Für eine Änderung namens add-auth liest tracks: tasks.md:

openspec/changes/add-auth/tasks.md

Ein Glob wie tracks: "**/tasks.md" liest jede übereinstimmende Datei, wie backend/tasks.md und frontend/tasks.md. OpenSpec kombiniert deren Aufgaben und Fortschritt. Verwenden Sie denselben Wert für das generates-Feld eines Artefakts, damit Status und Liste die gleichen Dateien verfolgen. Die Brace-Grenzen von generates (16 Ebenen tief, 1.024 erweiterte Muster) gelten auch hier.

Apply bleibt blockiert, wenn keine Datei übereinstimmt oder die übereinstimmenden Dateien kein Kontrollkästchen mit Aufgabentext enthalten. OpenSpec zählt diese Kontrollkästchen-Formen:

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

Jedes Markdown-Listenzeichen funktioniert: -, *, + oder eine Zahl von bis zu neun Ziffern, gefolgt von . oder ). Führende Leerzeichen sind erlaubt. Der tasks.md-Abschnitt der spec-driven-Seite definiert das strengere Format, das vom Standardschema erzeugt wird.

Die verfolgten Dateien steuern den Apply-Status:

• blocked: keine Datei stimmt überein oder keine lesbare Datei hat ein Kontrollkästchen mit Aufgabentext.
• ready: mindestens eine Aufgabe ist ausstehend, oder eine übereinstimmende Datei konnte nicht gelesen werden, während eine andere Aufgaben bereitstellt.
• all_done: jede verfolgte Aufgabe ist abgehakt und jede übereinstimmende Datei wurde gelesen.

Wenn eine übereinstimmende Datei nicht gelesen werden kann, behält Apply die Aufgaben und den Fortschritt aus lesbaren Dateien bei, markiert die Änderung jedoch nicht als all_done. Apply JSON-Ausgabe identifiziert jede nicht verfügbare Datei und den Grund.

OpenSpec verwirft absolute Pfade und Pfade mit einem ..-Segment.

Apply-Standardwerte

Verhalten	Standard
Erforderliche Artefakte	Jedes Artefakt im Schema
Fortschrittsverfolgung	Keine verfolgte Datei
Agenten-Anleitung	Integrierte Apply-Anleitung

Vollständiges Beispiel

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.

Validierung

openspec schema validate <name> prüft:

• Feldtypen und erforderliche Felder
• Relative Pfade
• Artefakt-IDs, Abhängigkeiten und Zyklen
• apply.requires-IDs: Jede muss ein Artefakt im Schema sein
• Vorlagendateien

Ein Schema mit einer unbekannten apply.requires-ID wird nicht geladen, daher meldet jeder Befehl, der es verwendet, den Fehler.

Die Validierung warnt, ohne zu fehlschlagen, wenn apply.tracks nicht exakt dem generates-Wert eines Artefakts entspricht. OpenSpec findet das verfolgte Artefakt, indem es diese beiden Strings vergleicht, daher lässt alles andere es nicht in der Lage zu bestimmen, zu welchem Artefakt der Fortschritt der Datei gehört. Dazu gehört ein Tippfehler wie task.md, aber auch tracks: tasks/main.md gegenüber generates: tasks/*.md, wo der Glob die Datei zwar erzeugt, aber die Strings dennoch abweichen. Apply liest die Datei in jedem Fall weiter, aber openspec list und openspec status zählen stattdessen tasks.md.

Die Validierung erkennt diese Fehler nicht:

Fehler	Was passiert
Ein Feld ist falsch geschrieben, wie instrution	OpenSpec ignoriert es. Die Validierung meldet den Tippfehler nicht.
name weicht vom Schema-Verzeichnis ab	Die Validierung besteht. OpenSpec verwendet für die Suche weiterhin den Verzeichnisnamen.