Change metadata (.openspec.yaml)

De ondersteunde vallen en validatieregels voor de metadata die bij elke change wordt opgeslagen.

Locatie

Elke change bewaart zijn metadata op openspec/changes/<change-name>/.openspec.yaml, naast zijn artifacts. Het aanmaken van een change schrijft het bestand met schema en created ingevuld.

Velden

Key	Type	Required	Effect
schema	string	Yes	Het workflow-schema dat deze change volgt
created	string, YYYY-MM-DD	No	Recordt de datum waarop de change is gecreëerd
goal	string	No	Recordt wat de change beoogt te doen
affected_areas	list of strings	No	Recordt de gebieden die de change verwacht aan te raken
initiative	map: store and id	No	Recordt de initiatief waar deze change toe behoort
skip_specs	boolean	No	Verklaart dat de change geen spec-deltas maakt, dus nul deltas valideren
retire_capabilities	boolean	No	Machtigt archive om een capability te verwijderen deze change leegmaken

schema

Het workflow-schema dat deze change volgt. Het wordt ingesteld wanneer de change wordt aangemaakt en heeft voorrang op de projectconfiguratie, dus een change behoudt zijn schema zelfs als openspec/config.yaml later verandert. Voer openspec schemas uit om de beschikbare schemaname te lijsten.

initiative

De initiatief waar deze change toe behoort, als een store id en een initiative id, both kebab-case:

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

Andere keys dan store en id worden geweigerd. Geen enkel commando leest de link vandaag.

skip_specs

Verklaart dat de change opzettelijk geen spec-deltas maakt: een pure refactor, tooling- of docs-wijziging. Met deze ingesteld, accepteert validatie nul deltas, en artifacts die spec-bestanden zouden genereren worden als compleet beschouwd. Het instellen terwijl spec-bestanden onder specs/ bestaan, is een validatiefout.

retire_capabilities

Machtigt archive om een capability te retiren. Wanneer de REMOVED-deltas van deze change de laatste vereiste die een capability heeft weghalen, delete archive de main-spec van die capability in plaats van te stoppen. Het bestand bestaat omdat de verwijdering alleen te herstellen is vanuit git, dus het blijft de keuze van de auteur.

Extension keys

Een top-level key die begint met een lowercase x- is van jou, voor gegevens die een andere tool of je team naast de change bewaart, zoals een tracker id of een eigenaar:

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

• Naam: de lowercase x- prefix gevolgd door minstens één karakter, zonder enige ruimte ergens. Elke case of spelling werkt na de prefix, dus x-jiraKey en x-trackerID voldoen. X-Tracker, een kale x-, en x- tracker niet, en worden gerapporteerd als onbekende keys.
• Waarde: elke YAML-waarde. OpenSpec leest of valideert het niet, en het verandert geen gedrag.
• Bereik: alleen top-level. Een x--key binnen initiative wordt nog steeds geweigerd, zoals elke andere key daar.
• Validatie: extension keys worden nooit gerapporteerd als onbekend, dus openspec validate --strict slaagt voor een change die ze draagt.
• Archive: het bestand verandert met de change, inclusief extension keys.

Voorbeeld

Een ingevulde .openspec.yaml:

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

Validatie

Het bestand wordt gevalideerd wanneer een commando het schrijft of leest. Een schrijven dat validatie faalt gooit een fout en schrijft niets. Het lezen van een bestaand bestand faalt op ongeldige YAML, een veld dat zijn contract breekt, of een schemanaam die niet beschikbaar is. Een ontbrekend bestand is geen fout, en de change wordt treatment als geen metadata.

In tegenstelling tot config.yaml, slechte waarden worden nooit met een waarschuwing weggegooid. Een metadata-fout stopt het commando.

• Onbekende top-level keys: OpenSpec negeert ze. status, instructions, validate, en archive rapporteren dat ze geen effect hebben. JSON-uitvoer draagt de waarschuwing in zijn gestructureerde resultaat. Extension keys zijn niet onbekend en worden nooit gerapporteerd.
• Strikte validatie: openspec validate --strict treat een onbekende-key-waarschuwing als een falen. Een change wiens enige extra keys extension keys zijn, slaagt.