Änderungsmetadaten (.openspec.yaml)

Die unterstützten Felder und Validierungsregeln für die Metadaten, die mit jeder Änderung gespeichert werden.

Speicherort

Jede Änderung speichert ihre Metadaten unter openspec/changes/<change-name>/.openspec.yaml, neben ihren Artefakten. Beim Erstellen einer Änderung wird die Datei mit ausgefülltem schema und created geschrieben.

Felder

Schlüssel	Typ	Erforderlich	Wirkung
schema	string	Ja	Das Workflow-Schema, dem diese Änderung folgt
created	string, YYYY-MM-DD	Nein	Zeichnet das Datum auf, an dem die Änderung erstellt wurde
goal	string	Nein	Zeichnet auf, was die Änderung beabsichtigt
affected_areas	Liste von Strings	Nein	Zeichnet die Bereiche auf, die die Änderung voraussichtlich betrifft
initiative	Map: store und id	Nein	Zeichnet die Initiative auf, zu der diese Änderung gehört
skip_specs	boolean	Nein	Erklärt, dass die Änderung keine Spec-Deltas erzeugt, sodass null Deltas valide sind
retire_capabilities	boolean	Nein	Ermächtigt das Archiv, eine Capability zu löschen, die diese Änderung leert

schema

Das Workflow-Schema, dem diese Änderung folgt. Es wird beim Erstellen der Änderung festgelegt und hat Vorrang vor der Projektkonfiguration, sodass eine Änderung ihr Schema behält, auch wenn openspec/config.yaml danach geändert wird. Führen Sie openspec schemas aus, um die verfügbaren Schema-Namen aufzulisten.

initiative

Die Initiative, zu der diese Änderung gehört, als Store-ID und Initiativ-ID, beide im kebab-case:

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

Andere Schlüssel als store und id werden abgelehnt. Derzeit liest kein Befehl diese Verknüpfung.

skip_specs

Erklärt, dass die Änderung bewusst keine Spec-Deltas erzeugt: ein reines Refactoring, eine Tooling- oder Dokumentationsänderung. Wenn es gesetzt ist, akzeptiert die Validierung null Deltas, und Artefakte, die Spec-Dateien erzeugen würden, gelten als abgeschlossen. Es zu setzen, während unter specs/ Spec-Dateien existieren, ist ein Validierungsfehler.

retire_capabilities

Ermächtigt das Archiv, eine Capability stillzulegen. Wenn die REMOVED-Deltas dieser Änderung die letzte Anforderung einer Capability entfernen, löscht das Archiv das Hauptspec dieser Capability, statt anzuhalten. Das Flag existiert, weil die Löschung nur über git wiederherstellbar ist, daher bleibt es eine Entscheidung des Autors.

Erweiterungsschlüssel

Ein Schlüssel auf oberster Ebene, der mit einem kleingeschriebenen x- beginnt, gehört Ihnen, für Daten, die ein anderes Tool oder Ihr Team neben der Änderung vorhält, wie eine Tracker-ID oder ein Verantwortlicher:

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

• Name: das kleingeschriebene x--Präfix, gefolgt von mindestens einem Zeichen, ohne Leerzeichen irgendwo. Nach dem Präfix funktioniert jede Schreibweise, also qualifizieren sich x-jiraKey und x-trackerID. X-Tracker, ein bloßes x- und x- tracker tun dies nicht und werden als unbekannte Schlüssel gemeldet.
• Wert: ein beliebiger YAML-Wert. OpenSpec liest oder validiert ihn nicht, und er ändert kein Verhalten.
• Geltungsbereich: nur oberste Ebene. Ein x--Schlüssel innerhalb von initiative wird weiterhin abgelehnt, wie jeder andere Schlüssel dort.
• Validierung: Erweiterungsschlüssel werden nie als unbekannt gemeldet, daher besteht openspec validate --strict eine Änderung, die sie trägt.
• Archiv: die Datei wandert unverändert mit der Änderung, einschließlich der Erweiterungsschlüssel.

Beispiel

Eine ausgefüllte .openspec.yaml:

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

Validierung

Die Datei wird validiert, sobald ein Befehl sie schreibt oder liest. Ein Schreibvorgang, der die Validierung nicht besteht, wirft einen Fehler und schreibt nichts. Das Lesen einer vorhandenen Datei schlägt fehl bei ungültigem YAML, einem Feld, das seinen Vertrag bricht, oder einem nicht verfügbaren Schema-Namen. Eine fehlende Datei ist kein Fehler, und die Änderung wird so behandelt, als hätte sie keine Metadaten.

Anders als bei config.yaml werden fehlerhafte Werte nie mit einer Warnung verworfen. Ein Metadatenfehler stoppt den Befehl.

• Unbekannte Schlüssel auf oberster Ebene: OpenSpec ignoriert sie. status, instructions, validate und archive melden, dass sie keine Wirkung haben. Die JSON-Ausgabe trägt die Warnung in ihrem strukturierten Ergebnis. Erweiterungsschlüssel sind nicht unbekannt und werden nie gemeldet.
• Strikte Validierung: openspec validate --strict behandelt eine Warnung über unbekannte Schlüssel als Fehlschlag. Eine Änderung, deren einzige zusätzliche Schlüssel Erweiterungsschlüssel sind, besteht.