schema.yaml

Cada campo de uma definição de schema, para leitura ou escrita.

schema.yaml lista os arquivos de planejamento que um workflow cria. Ele também define sua ordem e a transição para implementação.

Localização

Um schema de projeto fica em openspec/schemas/<name>/:

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

OpenSpec verifica três locais para esse diretório. A primeira correspondência vence.

Cópia	Diretório
1. Projeto	<project>/openspec/schemas/<name>/
2. Usuário, macOS e Linux	~/.local/share/openspec/schemas/<name>/
2. Usuário, Windows	%LOCALAPPDATA%\openspec\schemas\<name>\
3. Pacote	Os schemas instalados com a CLI

Se XDG_DATA_HOME estiver definido, o diretório do usuário passa para $XDG_DATA_HOME/openspec/schemas/<name>/ em todas as plataformas.

O nome do diretório é a chave de busca usada por --schema, config.yaml e .openspec.yaml. Se o campo name diferir do nome do diretório, o OpenSpec ainda usa o nome do diretório para a busca.

openspec schema which <name> imprime o diretório ativo e quaisquer cópias de menor prioridade que ele oculta.

Campos de nível superior

Campo	Contrato
name	Obrigatório. Uma string não vazia armazenada como o nome do schema. A busca ainda usa o nome do diretório.
version	Obrigatório. Um número inteiro positivo armazenado como a revisão do schema. O valor não altera o comportamento do OpenSpec.
description	Uma string opcional impressa por openspec schemas. Sem valor, o schema não tem descrição.
artifacts	Obrigatório. Uma lista não vazia de entradas de artifact.
apply	Configurações opcionais de apply. Sem bloco, o OpenSpec usa os padrões de apply.

Campos de artifact

Cada entrada em artifacts define um arquivo de planejamento ou conjunto de arquivos.

Campo	Contrato
id	Obrigatório. Uma string única e não vazia usada em dependências, regras do projeto, comandos e configurações de apply.
generates	Obrigatório. Um caminho relativo ou glob informando ao agente onde escrever o artifact dentro da pasta de mudança.
description	Obrigatório. Uma string que rotula o artifact em instruções enviadas ao agente.
template	Obrigatório. Um caminho relativo para o formato do artifact na pasta templates/ do schema.
instruction	Orientação opcional informando ao agente qual conteúdo produzir.
requires	Uma lista de IDs de artifacts que devem ser concluídos primeiro. Padrão: [].

generates

O caminho começa na pasta de mudança. Para uma mudança chamada add-auth:

generates: proposal.md

O artifact vai para cá:

openspec/changes/add-auth/proposal.md

Um glob pode corresponder a vários arquivos:

generates: specs/**/*.md

Isso corresponde a arquivos Markdown abaixo de openspec/changes/add-auth/specs/.

O OpenSpec reconhece estas formas de glob em generates:

• Curingas e classes de caracteres: valores contendo *, ? ou [, como specs/**/*.md e review-[ab].md.
• Expansões de chaves: alternativas como review-{api,ui}.md e intervalos como file-{1..3}.md.
• Extglobs: padrões como @(proposal|design).md, +(proposal|design).md e !(proposal|design).md.

Nomes de arquivo literais: um ! inicial sozinho não torna um glob. Use generates: '!review.md' para nomear esse arquivo. Parênteses simples como (proposal|design).md e chaves de elemento único como review-{api}.md também permanecem literais.

O OpenSpec rejeita caminhos absolutos, caminhos contendo um segmento .. e globs que aninham chaves ou parênteses mais de 16 níveis de profundidade, como {a,{b,{c,...}}}. Padrões reais precisam de um ou dois níveis. Ele também rejeita um glob cujas chaves se expandem para mais de 1.024 padrões, como {a,b} repetido onze vezes ou um intervalo como file-{1..5000}.md. O erro diz Artifact output pattern expands to more than 1024 patterns. Padrões reais se expandem para um punhado.

Conclusão

O OpenSpec verifica se a saída existe. Ele não lê o arquivo para decidir se o artifact está completo.

Valor de generates	Completo quando
proposal.md	Esse arquivo existe.
specs/**/*.md	O glob corresponde a pelo menos um arquivo.

template

O caminho começa na pasta templates/ do schema. No schema review-first:

template: proposal.md

O OpenSpec lê este arquivo:

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

O OpenSpec fornece o conteúdo do template ao agente como formato de saída. Ele não copia o template para a pasta de mudança.

O OpenSpec rejeita caminhos absolutos e caminhos contendo um segmento ...

requires

• Dependências: cada ID em requires deve nomear outro artifact no mesmo schema.
• Estado pronto: um artifact se torna pronto após todas as suas dependências estarem completas.
• Grafos inválidos: IDs ausentes, IDs duplicados e ciclos de dependência falham na validação.
• Empates: quando vários artifacts estão prontos, sua ordem em artifacts decide qual o OpenSpec retorna primeiro.

Campos de apply

apply define o que deve existir antes do início da implementação.

Campo	Contrato
requires	Obrigatório. Uma lista não vazia de artifacts que devem existir antes que as instruções de apply fiquem prontas.
tracks	Um caminho relativo ou glob opcional para arquivos de tarefas Markdown na pasta de mudança. Padrão: null.
instruction	Orientação opcional enviada ao agente quando o apply está pronto. O OpenSpec usa orientação integrada por padrão.

O requires do artifact controla a ordem de planejamento. O apply.requires controla quando as instruções de apply ficam prontas.

tracks

O caminho começa na pasta de mudança. Para uma mudança chamada add-auth, tracks: tasks.md lê:

openspec/changes/add-auth/tasks.md

Um glob como tracks: "**/tasks.md" lê todos os arquivos correspondentes, como backend/tasks.md e frontend/tasks.md. O OpenSpec combina suas tarefas e progresso. Use o mesmo valor para o campo generates de um artifact para que status e lista acompanhem os mesmos arquivos. Os limites de chaves de generates (16 níveis de profundidade, 1.024 padrões expandidos) se aplicam aqui também.

O apply permanece bloqueado se nenhum arquivo corresponder ou se os arquivos correspondentes não contiverem nenhum checkbox com texto de tarefa. O OpenSpec conta estas formas de checkbox:

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

Qualquer marcador de lista Markdown funciona: -, *, + ou um número de até nove dígitos seguido de . ou ). Espaços iniciais são permitidos. A seção tasks.md da página spec-driven define o formato mais estrito produzido pelo schema padrão.

Os arquivos rastreados controlam o estado do apply:

• blocked: nenhum arquivo corresponde, ou nenhum arquivo legível tem um checkbox com texto de tarefa.
• ready: pelo menos uma tarefa está pendente, ou um arquivo correspondente não pôde ser lido enquanto outro fornece tarefas.
• all_done: todas as tarefas rastreadas estão marcadas e todos os arquivos correspondentes foram lidos.

Se um arquivo correspondente não puder ser lido, o apply mantém as tarefas e o progresso dos arquivos legíveis, mas não marca a mudança como all_done. Saída JSON do Apply identifica cada arquivo indisponível e o motivo.

O OpenSpec rejeita caminhos absolutos e caminhos contendo um segmento ...

Padrões de apply

Comportamento	Padrão
Artifacts obrigatórios	Todos os artifacts no schema
Rastreamento de progresso	Nenhum arquivo rastreado
Orientação do agente	Orientação integrada de apply

Exemplo completo

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.

Validação

openspec schema validate <name> verifica:

• Tipos de campos e campos obrigatórios
• Caminhos relativos
• IDs de artifacts, dependências e ciclos
• IDs de apply.requires: cada um deve ser um artifact no schema
• Arquivos de template

Um schema com um ID apply.requires desconhecido não carrega, então todos os comandos que o usam relatam o erro.

A validação avisa, sem falhar, quando apply.tracks não é exatamente igual ao valor generates de algum artifact. O OpenSpec encontra o artifact rastreado comparando essas duas strings, então qualquer outra coisa o deixa incapaz de dizer a qual artifact o arquivo pertence. Isso inclui um erro de digitação como task.md, e também tracks: tasks/main.md contra generates: tasks/*.md, onde o glob produz o arquivo, mas as strings ainda diferem. O apply continua lendo o arquivo de qualquer forma, mas openspec list e openspec status contam tasks.md em vez disso.

A validação não detecta estes erros:

Erro	O que acontece
Um campo está grafado errado, como instrution	O OpenSpec o ignora. A validação não relata o erro de digitação.
name difere do diretório do schema	A validação passa. O OpenSpec ainda usa o nome do diretório para a busca.