schema.yaml

Ogni campo di una definizione di schema, per la lettura o la scrittura.

schema.yaml elenca i file di pianificazione che un workflow crea. Definisce anche il loro ordine e il passaggio all'implementazione.

Posizione

Lo schema di un progetto si trova in openspec/schemas/<name>/:

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

OpenSpec controlla tre posizioni per quella directory. Vince la prima corrispondenza.

Copia	Directory
1. Progetto	<project>/openspec/schemas/<name>/
2. Utente, macOS e Linux	~/.local/share/openspec/schemas/<name>/
2. Utente, Windows	%LOCALAPPDATA%\openspec\schemas\<name>\
3. Pacchetto	Gli schemi installati con la CLI

Se XDG_DATA_HOME è impostata, la directory utente si sposta in $XDG_DATA_HOME/openspec/schemas/<name>/ su ogni piattaforma.

Il nome della directory è la chiave di ricerca usata da --schema, config.yaml e .openspec.yaml. Se il campo name differisce dal nome della directory, OpenSpec usa comunque il nome della directory per la ricerca.

openspec schema which <name> stampa la directory attiva e le eventuali copie a priorità inferiore che nasconde.

Campi di primo livello

Campo	Contratto
name	Obbligatorio. Una stringa non vuota memorizzata come nome dello schema. La ricerca usa comunque il nome della directory.
version	Obbligatorio. Un intero positivo memorizzato come revisione dello schema. Il valore non modifica il comportamento di OpenSpec.
description	Una stringa facoltativa stampata da openspec schemas. Senza un valore, lo schema non ha descrizione.
artifacts	Obbligatorio. Un elenco non vuoto di voci degli artefatti.
apply	Impostazioni di apply facoltative. Senza blocco, OpenSpec usa i valori predefiniti di apply.

Campi degli artefatti

Ogni voce sotto artifacts definisce un file di pianificazione o un insieme di file.

Campo	Contratto
id	Obbligatorio. Una stringa univoca e non vuota usata nelle dipendenze, nelle regole del progetto, nei comandi e nelle impostazioni di apply.
generates	Obbligatorio. Un percorso relativo o un glob che indica all'agente dove scrivere l'artefatto all'interno della cartella della modifica.
description	Obbligatorio. Una stringa che etichetta l'artefatto nelle istruzioni inviate all'agente.
template	Obbligatorio. Un percorso relativo al formato dell'artefatto nella cartella templates/ dello schema.
instruction	Guida facoltativa che indica all'agente quale contenuto produrre.
requires	Un elenco di ID di artefatti che devono essere completati prima. Predefinito: [].

generates

Il percorso parte dalla cartella della modifica. Per una modifica denominata add-auth:

generates: proposal.md

L'artefatto va qui:

openspec/changes/add-auth/proposal.md

Un glob può corrispondere a più file:

generates: specs/**/*.md

Corrisponde ai file Markdown sotto openspec/changes/add-auth/specs/.

OpenSpec riconosce queste forme di glob in generates:

• Wildcard e classi di caratteri: valori contenenti *, ? o [, come specs/**/*.md e review-[ab].md.
• Espansioni con parentesi graffe: alternative come review-{api,ui}.md e intervalli come file-{1..3}.md.
• Extglob: pattern come @(proposal|design).md, +(proposal|design).md e !(proposal|design).md.

Nomi di file letterali: un ! iniziale da solo non rende un valore un glob. Usa generates: '!review.md' per indicare quel file. Anche le parentesi semplici come (proposal|design).md e le parentesi graffe con un solo elemento come review-{api}.md restano letterali.

OpenSpec rifiuta percorsi assoluti, percorsi contenenti un segmento .. e glob che annidano parentesi graffe o parentesi tonde oltre 16 livelli di profondità, come {a,{b,{c,...}}}. I pattern reali richiedono uno o due livelli. Rifiuta anche un glob le cui parentesi graffe si espandono in più di 1.024 pattern, come {a,b} ripetuto undici volte o un intervallo come file-{1..5000}.md. Il messaggio di errore dice Artifact output pattern expands to more than 1024 patterns. I pattern reali si espandono in una manciata di elementi.

Completamento

OpenSpec controlla se l'output esiste. Non legge il file per decidere se l'artefatto è completo.

Valore di generates	Completo quando
proposal.md	Quel file esiste.
specs/**/*.md	Il glob corrisponde ad almeno un file.

template

Il percorso parte dalla cartella templates/ dello schema. Nello schema review-first:

template: proposal.md

OpenSpec legge questo file:

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

OpenSpec fornisce il contenuto del template all'agente come formato di output. Non copia il template nella cartella della modifica.

OpenSpec rifiuta percorsi assoluti e percorsi contenenti un segmento ...

requires

• Dipendenze: ogni ID in requires deve indicare un altro artefatto nello stesso schema.
• Stato pronto: un artefatto diventa pronto dopo che tutte le sue dipendenze sono complete.
• Grafici non validi: ID mancanti, ID duplicati e cicli di dipendenza non superano la validazione.
• Pareggi: quando più artefatti sono pronti, il loro ordine in artifacts determina quale OpenSpec restituisce per primo.

Campi di apply

apply definisce ciò che deve esistere prima che inizi l'implementazione.

Campo	Contratto
requires	Obbligatorio. Un elenco non vuoto di artefatti che devono esistere prima che le istruzioni di apply diventino pronte.
tracks	Un percorso relativo o un glob facoltativo per i file di attività Markdown nella cartella della modifica. Predefinito: null.
instruction	Guida facoltativa inviata all'agente quando apply è pronto. OpenSpec usa per impostazione predefinita una guida integrata.

requires degli artefatti controlla l'ordine di pianificazione. apply.requires controlla quando le istruzioni di apply diventano pronte.

tracks

Il percorso parte dalla cartella della modifica. Per una modifica denominata add-auth, tracks: tasks.md legge:

openspec/changes/add-auth/tasks.md

Un glob come tracks: "**/tasks.md" legge ogni file corrispondente, come backend/tasks.md e frontend/tasks.md. OpenSpec combina le loro attività e i loro progressi. Usa lo stesso valore per il campo generates di un artefatto, così che lo stato e l'elenco tengano traccia degli stessi file. Anche qui valgono i limiti delle parentesi graffe di generates (16 livelli di profondità, 1.024 pattern espansi).

Apply resta bloccato se nessun file corrisponde o se i file corrispondenti non contengono alcuna casella di controllo con testo di attività. OpenSpec conteggia queste forme di casella di controllo:

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

Qualsiasi indicatore di elenco Markdown funziona: -, *, + o un numero di massimo nove cifre seguito da . o ). Sono consentiti spazi iniziali. La sezione tasks.md della pagina spec-driven definisce il formato più rigoroso prodotto dallo schema predefinito.

I file tracciati determinano lo stato di apply:

• blocked: nessun file corrisponde, oppure nessun file leggibile contiene una casella di controllo con testo di attività.
• ready: almeno un'attività è in sospeso, oppure non è stato possibile leggere un file corrispondente mentre un altro fornisce attività.
• all_done: ogni attività tracciata è selezionata e ogni file corrispondente è stato letto.

Se non è possibile leggere un file corrispondente, apply mantiene le attività e i progressi dei file leggibili ma non contrassegna la modifica come all_done. L'output JSON di apply identifica ogni file non disponibile e il motivo.

OpenSpec rifiuta percorsi assoluti e percorsi contenenti un segmento ...

Valori predefiniti di apply

Comportamento	Predefinito
Artefatti obbligatori	Ogni artefatto nello schema
Monitoraggio dei progressi	Nessun file tracciato
Guida per l'agente	Guida integrata di apply

Esempio completo

name: review-first
version: 1
description: Proposta e checklist di implementazione

artifacts:
  - id: proposal
    generates: proposal.md
    description: Perché la modifica è necessaria e cosa influisce
    template: proposal.md
    instruction: |
      Spiega il problema, la modifica proposta e il suo impatto.
    requires: []

  - id: tasks
    generates: tasks.md
    description: Checklist di implementazione tracciabile
    template: tasks.md
    instruction: |
      Suddividi la proposta approvata in attività di implementazione ordinate.
    requires:
      - proposal

apply:
  requires:
    - tasks
  tracks: tasks.md
  instruction: |
    Lavora sulle attività in sospeso e contrassegna ciascuna come completata.

Validazione

openspec schema validate <name> controlla:

• Tipi di campo e campi obbligatori
• Percorsi relativi
• ID degli artefatti, dipendenze e cicli
• ID in apply.requires: ciascuno deve essere un artefatto nello schema
• File template

Uno schema con un ID sconosciuto in apply.requires non viene caricato, quindi ogni comando che lo usa segnala l'errore.

La validazione avverte, senza fallire, quando apply.tracks non è esattamente uguale al valore generates di un qualche artefatto. OpenSpec individua l'artefatto tracciato confrontando quelle due stringhe, quindi qualsiasi altra cosa gli impedisce di stabilire a quale artefatto appartenga il progresso del file. Ciò include un refuso come task.md, e anche tracks: tasks/main.md rispetto a generates: tasks/*.md, dove il glob produce effettivamente il file ma le stringhe restano diverse. Apply continua comunque a leggere il file, ma openspec list e openspec status conteggiano invece tasks.md.

La validazione non rileva questi errori:

Errore	Cosa succede
Un campo è scritto male, ad esempio instrution	OpenSpec lo ignora. La validazione non segnala il refuso.
name differisce dalla directory dello schema	La validazione passa. OpenSpec usa comunque il nome della directory per la ricerca.