Alterar metadados (.openspec.yaml)

Os campos suportados e as regras de validação para os metadados armazenados com cada alteração.

Localização

Cada alteração mantém seus metadados em openspec/changes/<change-name>/.openspec.yaml, junto com seus artefatos. A criação de uma alteração grava o arquivo com schema e created preenchidos.

Campos

Chave	Tipo	Obrigatório	Efeito
schema	string	Sim	O esquema de fluxo de trabalho que esta alteração segue
created	string, YYYY-MM-DD	Não	Registra a data em que a alteração foi criada
goal	string	Não	Registra o que a alteração se propõe a fazer
affected_areas	lista de strings	Não	Registra as áreas que a alteração espera afetar
initiative	mapa: store e id	Não	Registra a iniciativa à qual esta alteração pertence
skip_specs	booleano	Não	Declara que a alteração não faz deltas de spec, então zero deltas são válidos
retire_capabilities	booleano	Não	Autoriza o arquivo a excluir uma capability que esta alteração esvazia

schema

O esquema de fluxo de trabalho que esta alteração segue. É definido quando a alteração é criada e prevalece sobre a configuração do projeto, de modo que uma alteração mantém seu esquema mesmo que openspec/config.yaml seja alterado posteriormente. Execute openspec schemas para listar os nomes de esquemas disponíveis.

initiative

A iniciativa à qual esta alteração pertence, como um id de repositório e um id de iniciativa, ambos em kebab-case:

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

Chaves diferentes de store e id são rejeitadas. Nenhum comando lê esse vínculo atualmente.

skip_specs

Declara que a alteração intencionalmente não faz deltas de spec: uma refatoração pura, mudança de ferramentas ou de documentação. Com ele definido, a validação aceita zero deltas, e artefatos que gerariam arquivos de spec são considerados completos. Defini-lo enquanto arquivos de spec existirem em specs/ é um erro de validação.

retire_capabilities

Autoriza o arquivo a aposentar uma capability. Quando os deltas REMOVED desta alteração removem o último requisito que uma capability possui, o arquivo exclui o spec principal dessa capability em vez de interromper. A flag existe porque a exclusão só é recuperável pelo git, então a decisão permanece do autor.

Chaves de extensão

Uma chave de nível superior que começa com x- minúsculo é sua, para dados que outra ferramenta ou sua equipe mantém junto à alteração, como um id de rastreador ou um proprietário:

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

• Nome: o prefixo x- minúsculo seguido de pelo menos um caractere, sem espaços em branco em qualquer lugar. Qualquer caixa ou grafia funciona após o prefixo, então x-jiraKey e x-trackerID se qualificam. X-Tracker, um x- isolado e x- tracker não se qualificam e são reportados como chaves desconhecidas.
• Valor: qualquer valor YAML. O OpenSpec não o lê nem o valida, e não altera nenhum comportamento.
• Escopo: apenas nível superior. Uma chave x- dentro de initiative ainda é rejeitada, como qualquer outra chave lá.
• Validação: chaves de extensão nunca são reportadas como desconhecidas, então openspec validate --strict passa em uma alteração que as contém.
• Arquivo: o arquivo se move com a alteração inalterado, incluindo as chaves de extensão.

Exemplo

Um .openspec.yaml preenchido:

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

Validação

O arquivo é validado sempre que um comando o grava ou lê. Uma gravação que falha na validação lança uma exceção e não grava nada. A leitura de um arquivo existente falha em YAML inválido, um campo que quebra seu contrato ou um nome de esquema que não está disponível. Um arquivo ausente não é um erro, e a alteração é tratada como não tendo metadados.

Diferentemente de config.yaml, valores inválidos nunca são descartados com um aviso. Um erro de metadados interrompe o comando.

• Chaves de nível superior desconhecidas: O OpenSpec as ignora. status, instructions, validate e archive reportam que não têm efeito. A saída JSON carrega o aviso em seu resultado estruturado. Chaves de extensão não são desconhecidas e nunca são reportadas.
• Validação estrita: openspec validate --strict trata um aviso de chave desconhecida como uma falha. Uma alteração cujas únicas chaves extras são chaves de extensão passa.