Metadatos del cambio (.openspec.yaml)

Los campos admitidos y las reglas de validación de los metadatos que se almacenan con cada cambio.

Ubicación

Cada cambio guarda sus metadatos en openspec/changes/<change-name>/.openspec.yaml, junto a sus artefactos. Al crear un cambio, se escribe el archivo con schema y created completados.

Campos

Clave	Tipo	Obligatorio	Efecto
schema	cadena	Sí	El esquema de flujo de trabajo que sigue este cambio
created	cadena, YYYY-MM-DD	No	Registra la fecha en que se creó el cambio
goal	cadena	No	Registra qué se propone conseguir el cambio
affected_areas	lista de cadenas	No	Registra las áreas que el cambio prevé afectar
initiative	mapa: store e id	No	Registra la iniciativa a la que pertenece este cambio
skip_specs	booleano	No	Declara que el cambio no genera deltas de especificación, por lo que la validación acepta cero deltas
retire_capabilities	booleano	No	Autoriza a archive a eliminar una capacidad que este cambio deja vacía

schema

El esquema de flujo de trabajo que sigue este cambio. Se establece cuando se crea el cambio y tiene prioridad sobre la configuración del proyecto, por lo que un cambio conserva su esquema aunque openspec/config.yaml cambie después. Ejecuta openspec schemas para listar los nombres de esquema disponibles.

initiative

La iniciativa a la que pertenece este cambio, como un id de store y un id de iniciativa, ambos en kebab-case:

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

Las claves distintas de store e id se rechazan. Ningún comando lee el enlace actualmente.

skip_specs

Declara que el cambio, intencionadamente, no genera deltas de especificación: se trata de un refactor puro, un cambio de herramientas o un cambio de documentación. Al establecerlo, la validación acepta cero deltas, y los artefactos que generarían archivos de especificación se consideran completos. Establecerlo cuando ya existen archivos de especificación en specs/ es un error de validación.

retire_capabilities

Autoriza a archive a retirar una capacidad. Cuando los deltas REMOVED de este cambio eliminan el último requisito que tiene una capacidad, archive elimina la especificación principal de esa capacidad en lugar de detenerse. La marca existe porque la eliminación solo se puede recuperar desde git, por lo que queda a criterio del autor.

Claves de extensión

Una clave de nivel superior que empieza por x- en minúsculas es tuya, para datos que otra herramienta o tu equipo guarda junto al cambio, como un id de seguimiento o un responsable:

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

• Nombre: el prefijo x- en minúsculas seguido de al menos un carácter, sin ningún espacio en blanco. Cualquier combinación de mayúsculas y minúsculas o grafía es válida después del prefijo, por lo que x-jiraKey y x-trackerID son válidos. X-Tracker, un x- aislado y x- tracker no lo son, y se informan como claves desconocidas.
• Valor: cualquier valor YAML. OpenSpec no lo lee ni lo valida, y no cambia ningún comportamiento.
• Ámbito: solo nivel superior. Una clave x- dentro de initiative sigue rechazándose, como cualquier otra clave allí.
• Validación: las claves de extensión nunca se informan como desconocidas, por lo que openspec validate --strict se completa correctamente en un cambio que las contiene.
• Archive: el archivo se mueve con el cambio sin modificaciones, incluidas las claves de extensión.

Ejemplo

Un archivo .openspec.yaml completado:

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

Validación

El archivo se valida siempre que un comando lo escribe o lo lee. Una escritura que no supera la validación lanza una excepción y no escribe nada. La lectura de un archivo existente falla si el YAML no es válido, si un campo incumple su contrato o si el nombre de esquema no está disponible. Que falte el archivo no es un error, y el cambio se trata como si no tuviera metadatos.

A diferencia de config.yaml, los valores incorrectos nunca se descartan con una advertencia. Un error de metadatos detiene el comando.

• Claves de nivel superior desconocidas: OpenSpec las ignora. status, instructions, validate y archive indican que no tienen efecto. La salida JSON incluye la advertencia en su resultado estructurado. Las claves de extensión no son desconocidas y nunca se notifican.
• Validación estricta: openspec validate --strict trata una advertencia de clave desconocida como un fallo. Un cambio cuyas únicas claves adicionales son claves de extensión pasa la validación.