schema.yaml

Cada campo de una definición de esquema, para leer o escribir uno.

schema.yaml enumera los archivos de planificación que crea un flujo de trabajo. También define su orden y la transición a la implementación.

Ubicación

El esquema de un proyecto se ubica en openspec/schemas/<name>/:

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

OpenSpec verifica tres ubicaciones para ese directorio. Gana la primera coincidencia.

Copia	Directorio
1. Proyecto	<project>/openspec/schemas/<name>/
2. Usuario, macOS y Linux	~/.local/share/openspec/schemas/<name>/
2. Usuario, Windows	%LOCALAPPDATA%\openspec\schemas\<name>\
3. Paquete	Los esquemas instalados con la CLI

Si XDG_DATA_HOME está configurada, el directorio de usuario se mueve a $XDG_DATA_HOME/openspec/schemas/<name>/ en todas las plataformas.

El nombre del directorio es la clave de búsqueda utilizada por --schema, config.yaml y .openspec.yaml. Si el campo name difiere del nombre del directorio, OpenSpec igualmente usa el nombre del directorio para la búsqueda.

openspec schema which <name> imprime el directorio activo y cualquier copia de menor prioridad que oculte.

Campos de nivel superior

Campo	Contrato
name	Requerido. Una cadena no vacía que se almacena como el nombre del esquema. La búsqueda aún utiliza el nombre del directorio.
version	Requerido. Un entero positivo almacenado como la revisión del esquema. El valor no cambia el comportamiento de OpenSpec.
description	Una cadena opcional impresa por openspec schemas. Sin valor, el esquema no tiene descripción.
artifacts	Requerido. Una lista no vacía de entradas de artefactos.
apply	Configuración de apply opcional. Sin bloque, OpenSpec utiliza los valores predeterminados de apply.

Campos de artefacto

Cada entrada bajo artifacts define un archivo o conjunto de archivos de planificación.

Campo	Contrato
id	Requerido. Una cadena única no vacía utilizada en dependencias, reglas del proyecto, comandos y configuración de apply.
generates	Requerido. Una ruta relativa o glob que indica al agente dónde escribir el artefacto dentro de la carpeta de cambio.
description	Requerido. Una cadena que etiqueta el artefacto en las instrucciones enviadas al agente.
template	Requerido. Una ruta relativa al formato del artefacto en la carpeta templates/ del esquema.
instruction	Guía opcional que indica al agente qué contenido producir.
requires	Una lista de IDs de artefactos que deben estar completos primero. Predeterminado: [].

generates

La ruta comienza desde la carpeta de cambio. Para un cambio llamado add-auth:

generates: proposal.md

El artefacto se coloca aquí:

openspec/changes/add-auth/proposal.md

Un glob puede coincidir con varios archivos:

generates: specs/**/*.md

Esto coincide con archivos Markdown dentro de openspec/changes/add-auth/specs/.

OpenSpec reconoce estas formas de glob en generates:

• Comodines y clases de caracteres: valores que contienen *, ? o [, como specs/**/*.md y review-[ab].md.
• Expansiones de llaves: alternativas como review-{api,ui}.md y rangos como file-{1..3}.md.
• Extglobs: patrones como @(proposal|design).md, +(proposal|design).md y !(proposal|design).md.

Nombres de archivo literales: un ! inicial por sí solo no forma un glob. Use generates: '!review.md' para nombrar ese archivo. Paréntesis simples como (proposal|design).md y llaves de un solo elemento como review-{api}.md también permanecen literales.

OpenSpec rechaza rutas absolutas, rutas que contienen un segmento .. y globs que anidan llaves o paréntesis a más de 16 niveles de profundidad, como {a,{b,{c,...}}}. Los patrones reales necesitan uno o dos niveles. También rechaza un glob cuyas llaves se expanden a más de 1.024 patrones, como {a,b} repetido once veces o un rango como file-{1..5000}.md. El error dice Patrón de salida del artefacto se expande a más de 1024 patrones. Los patrones reales se expanden a unos pocos.

Finalización

OpenSpec verifica si la salida existe. No lee el archivo para decidir si el artefacto está completo.

Valor de generates	Se considera completo cuando
proposal.md	Ese archivo existe.
specs/**/*.md	El glob coincide con al menos un archivo.

template

La ruta comienza desde la carpeta templates/ del esquema. En el esquema review-first:

template: proposal.md

OpenSpec lee este archivo:

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

OpenSpec entrega el contenido de la plantilla al agente como el formato de salida. No copia la plantilla en la carpeta de cambio.

OpenSpec rechaza rutas absolutas y rutas que contienen un segmento ...

requires

• Dependencias: cada ID en requires debe nombrar otro artefacto en el mismo esquema.
• Estado listo: un artefacto pasa a estar listo después de que todas sus dependencias estén completas.
• Grafos inválidos: IDs faltantes, IDs duplicados y ciclos de dependencia fallan la validación.
• Empates: cuando varios artefactos están listos, su orden en artifacts decide cuál devuelve OpenSpec primero.

Campos de apply

apply define lo que debe existir antes de que comience la implementación.

Campo	Contrato
requires	Requerido. Una lista no vacía de artefactos que deben existir antes de que las instrucciones de apply estén listas.
tracks	Una ruta relativa opcional o glob para archivos Markdown de tareas en la carpeta de cambio. Predeterminado: null.
instruction	Guía opcional enviada al agente cuando apply está listo. De forma predeterminada, OpenSpec utiliza una guía incorporada.

El campo requires de los artefactos controla el orden de planificación. apply.requires controla cuándo las instrucciones de apply están listas.

tracks

La ruta comienza desde la carpeta de cambio. Para un cambio llamado add-auth, tracks: tasks.md lee:

openspec/changes/add-auth/tasks.md

Un glob como tracks: "**/tasks.md" lee cada archivo coincidente, como backend/tasks.md y frontend/tasks.md. OpenSpec combina sus tareas y su progreso. Use el mismo valor para el campo generates de un artefacto para que el estado y la lista rastreen los mismos archivos. Los límites de llaves de generates (16 niveles de profundidad, 1.024 patrones expandidos) también se aplican aquí.

Apply permanece bloqueado si ningún archivo coincide o los archivos coincidentes no contienen ninguna casilla de verificación con texto de tarea. OpenSpec cuenta estas formas de casilla de verificación:

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

Cualquier marcador de lista Markdown funciona: -, *, +, o un número de hasta nueve dígitos seguido de . o ). Se permiten espacios al inicio. La sección tasks.md de la página spec-driven define el formato más estricto que produce el esquema predeterminado.

Los archivos rastreados determinan el estado de apply:

• blocked: ningún archivo coincide, o ningún archivo legible tiene una casilla de verificación con texto de tarea.
• ready: al menos una tarea está pendiente, o un archivo coincidente no pudo leerse mientras otro proporciona tareas.
• all_done: cada tarea rastreada está marcada y cada archivo coincidente fue leído.

Si un archivo coincidente no puede leerse, apply conserva las tareas y el progreso de los archivos legibles pero no marca el cambio como all_done. La salida JSON de apply identifica cada archivo no disponible y la razón.

OpenSpec rechaza rutas absolutas y rutas que contengan un segmento ...

Valores predeterminados de apply

Comportamiento	Valor predeterminado
Artefactos requeridos	Cada artefacto del esquema
Seguimiento de progreso	Sin archivo rastreado
Guía del agente	Guía incorporada de apply

Ejemplo completo

name: review-first
version: 1
description: Propuesta y lista de verificación de implementación

artifacts:
  - id: proposal
    generates: proposal.md
    description: Por qué se necesita el cambio y a qué afecta
    template: proposal.md
    instruction: |
      Explica el problema, el cambio propuesto y su impacto.
    requires: []

  - id: tasks
    generates: tasks.md
    description: Lista de verificación de implementación rastreable
    template: tasks.md
    instruction: |
      Divide la propuesta aprobada en tareas de implementación ordenadas.
    requires:
      - proposal

apply:
  requires:
    - tasks
  tracks: tasks.md
  instruction: |
    Trabaja en las tareas pendientes y marca cada una como completada.

Validación

openspec schema validate <name> verifica:

• Tipos de campo y campos requeridos
• Rutas relativas
• IDs de artefacto, dependencias y ciclos
• IDs de apply.requires: cada uno debe ser un artefacto del esquema
• Archivos de plantilla

Un esquema con un ID desconocido en apply.requires no se carga, por lo que cualquier comando que lo utilice reporta el error.

La validación advierte, sin fallar, cuando apply.tracks no es exactamente igual al valor de generates de algún artefacto. OpenSpec encuentra el artefacto rastreado comparando esas dos cadenas, por lo que cualquier otra cosa impide saber a qué artefacto pertenece el progreso del archivo. Esto incluye un error tipográfico como task.md, y también tracks: tasks/main.md frente a generates: tasks/*.md, donde el glob sí produce el archivo pero las cadenas siguen siendo diferentes. Apply lee el archivo de todas formas, pero openspec list y openspec status cuentan tasks.md en su lugar.

La validación no detecta estos errores:

Error	Lo que ocurre
Un campo está mal escrito, como instrution	OpenSpec lo ignora. La validación no reporta el error tipográfico.
name difiere del directorio del esquema	La validación pasa. OpenSpec igualmente usa el nombre del directorio para la búsqueda.