Metadati della modifica (.openspec.yaml)

I campi supportati e le regole di validazione per i metadati memorizzati con ciascuna modifica.

Posizione

Ogni modifica conserva i propri metadati in openspec/changes/<change-name>/.openspec.yaml, accanto ai propri artefatti. La creazione di una modifica scrive il file con schema e created compilati.

Campi

Chiave	Tipo	Obbligatorio	Effetto
schema	string	Sì	Lo schema di flusso di lavoro seguito da questa modifica
created	string, YYYY-MM-DD	No	Registra la data di creazione della modifica
goal	string	No	Registra ciò che la modifica si propone di fare
affected_areas	list of strings	No	Registra le aree che la modifica prevede di toccare
initiative	map: store e id	No	Registra l'iniziativa a cui appartiene questa modifica
skip_specs	boolean	No	Dichiara che la modifica non produce delta di specifica, quindi zero delta sono validi
retire_capabilities	boolean	No	Autorizza archive a eliminare una capability svuotata da questa modifica

schema

Lo schema di flusso di lavoro seguito da questa modifica. Viene impostato alla creazione della modifica e prevale sulla configurazione del progetto, quindi una modifica conserva il proprio schema anche se openspec/config.yaml viene modificato successivamente. Eseguire openspec schemas per elencare i nomi degli schema disponibili.

initiative

L'iniziativa a cui appartiene questa modifica, come store id e initiative id, entrambi in kebab-case:

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

Chiavi diverse da store e id vengono rifiutate. Nessun comando legge il collegamento oggi.

skip_specs

Dichiara che la modifica intenzionalmente non produce delta di specifica: un refactor puro, di strumentazione o di documentazione. Con questa opzione impostata, la validazione accetta zero delta e gli artefatti che genererebbero file di specifica contano come completi. Impostarla mentre esistono file di specifica sotto specs/ è un errore di validazione.

retire_capabilities

Autorizza archive a ritirare una capability. Quando i delta REMOVED di questa modifica eliminano l'ultimo requisito di una capability, archive elimina la specifica principale di quella capability invece di interrompersi. Il flag esiste perché l'eliminazione è recuperabile solo da git, quindi resta una decisione dell'autore.

Chiavi di estensione

Una chiave di primo livello che inizia con x- minuscolo è tua, per dati che un altro strumento o il tuo team conserva accanto alla modifica, come un tracker id o un owner:

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

• Nome: il prefisso x- minuscolo seguito da almeno un carattere, senza spazi bianchi. Dopo il prefisso funziona qualsiasi combinazione di maiuscole/minuscole, quindi x-jiraKey e x-trackerID sono validi. X-Tracker, un x- da solo e x- tracker non lo sono e vengono segnalati come chiavi sconosciute.
• Valore: qualsiasi valore YAML. OpenSpec non lo legge né lo valida e non modifica alcun comportamento.
• Ambito: solo di primo livello. Una chiave x- all'interno di initiative viene comunque rifiutata, come qualsiasi altra chiave lì.
• Validazione: le chiavi di estensione non vengono mai segnalate come sconosciute, quindi openspec validate --strict passa su una modifica che le contiene.
• Archive: il file si sposta con la modifica senza modifiche, chiavi di estensione incluse.

Esempio

Un .openspec.yaml compilato:

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

Validazione

Il file viene validato ogni volta che un comando lo scrive o lo legge. Una scrittura che fallisce la validazione genera un'eccezione e non scrive nulla. La lettura di un file esistente fallisce su YAML non valido, un campo che viola il suo contratto o un nome di schema non disponibile. Un file mancante non è un errore e la modifica viene trattata come priva di metadati.

Al contrario di config.yaml, i valori errati non vengono mai eliminati con un avviso. Un errore di metadati interrompe il comando.

• Chiavi di primo livello sconosciute: OpenSpec le ignora. status, instructions, validate e archive segnalano che non hanno alcun effetto. L'output JSON riporta l'avviso nel suo risultato strutturato. Le chiavi di estensione non sono sconosciute e non vengono mai segnalate.
• Validazione strict: openspec validate --strict tratta un avviso di chiave sconosciuta come un fallimento. Una modifica le cui uniche chiavi extra sono chiavi di estensione passa.