schema.yaml

Каждое поле определения схемы, для чтения или записи.

schema.yaml содержит список файлов планирования, которые создаёт рабочий процесс. Он также определяет их порядок и передачу к реализации.

Расположение

Схема проекта находится в openspec/schemas/<name>/:

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

OpenSpec проверяет три местоположения для этого каталога. Первое совпадение выигрывает.

Копия	Каталог
1. Проект	<project>/openspec/schemas/<name>/
2. Пользователь, macOS и Linux	~/.local/share/openspec/schemas/<name>/
2. Пользователь, Windows	%LOCALAPPDATA%\openspec\schemas\<name>\
3. Пакет	Схемы, установленные вместе с CLI

Если задана переменная XDG_DATA_HOME, пользовательский каталог перемещается в $XDG_DATA_HOME/openspec/schemas/<name>/ на всех платформах.

Имя каталога является ключом поиска, используемым --schema, config.yaml и .openspec.yaml. Если поле name отличается от имени каталога, OpenSpec всё равно использует имя каталога для поиска.

openspec schema which <name> выводит активный каталог и все копии с более низким приоритетом, которые он скрывает.

Поля верхнего уровня

Поле	Контракт
name	Обязательное. Непустая строка, сохраняемая как имя схемы. Поиск по-прежнему использует имя каталога.
version	Обязательное. Положительное целое число, сохраняемое как ревизия схемы. Значение не меняет поведение OpenSpec.
description	Необязательная строка, выводимая командой openspec schemas. Без значения схема не имеет описания.
artifacts	Обязательное. Непустой список записей артефактов.
apply	Необязательные настройки применения. Без блока OpenSpec использует значения по умолчанию для применения.

Поля артефакта

Каждая запись в artifacts определяет один файл планирования или набор файлов.

Поле	Контракт
id	Обязательное. Уникальная непустая строка, используемая в зависимостях, правилах проекта, командах и настройках применения.
generates	Обязательное. Относительный путь или glob, указывающий агенту, куда записать артефакт внутри папки изменения.
description	Обязательное. Строка, помечающая артефакт в инструкциях, отправляемых агенту.
template	Обязательное. Относительный путь к формату артефакта в папке templates/ схемы.
instruction	Необязательное руководство, указывающее агенту, какой контент создавать.
requires	Список идентификаторов артефактов, которые должны быть завершены первыми. По умолчанию: [].

generates

Путь начинается от папки изменения. Для изменения с именем add-auth:

generates: proposal.md

Артефакт попадает сюда:

openspec/changes/add-auth/proposal.md

Glob может соответствовать нескольким файлам:

generates: specs/**/*.md

Это соответствует Markdown-файлам ниже openspec/changes/add-auth/specs/.

OpenSpec распознаёт следующие формы glob в generates:

• Подстановочные знаки и классы символов: значения, содержащие *, ? или [, например specs/**/*.md и review-[ab].md.
• Расширения фигурных скобок: альтернативы, такие как review-{api,ui}.md, и диапазоны, такие как file-{1..3}.md.
• Extglobs: шаблоны, такие как @(proposal|design).md, +(proposal|design).md и !(proposal|design).md.

Буквенные имена файлов: один начальный ! не делает glob. Используйте generates: '!review.md', чтобы назвать этот файл. Простые круглые скобки, такие как (proposal|design).md, и фигурные скобки с одним элементом, такие как review-{api}.md, также остаются буквенными.

OpenSpec отклоняет абсолютные пути, пути, содержащие сегмент .., и globs, которые вкладывают фигурные или круглые скобки более чем на 16 уровней вглубь, например {a,{b,{c,...}}}. Реальным шаблонам нужен один или два уровня. Он также отклоняет glob, чьи фигурные скобки расширяются более чем на 1 024 шаблона, например {a,b}, повторённый одиннадцать раз, или диапазон вроде file-{1..5000}.md. Ошибка гласит: Artifact output pattern expands to more than 1024 patterns. Реальные шаблоны расширяются до нескольких.

Завершение

OpenSpec проверяет, существует ли выходной файл. Он не читает файл, чтобы решить, завершён ли артефакт.

Значение generates	Завершён, когда
proposal.md	Этот файл существует.
specs/**/*.md	Glob соответствует хотя бы одному файлу.

template

Путь начинается от папки templates/ схемы. В схеме review-first:

template: proposal.md

OpenSpec читает этот файл:

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

OpenSpec передаёт содержимое шаблона агенту как формат выходного файла. Он не копирует шаблон в папку изменения.

OpenSpec отклоняет абсолютные пути и пути, содержащие сегмент ...

requires

• Зависимости: каждый ID в requires должен указывать на другой артефакт в той же схеме.
• Состояние готовности: артефакт становится готовым после завершения всех его зависимостей.
• Недопустимые графы: отсутствующие ID, дублирующиеся ID и циклы зависимостей приводят к ошибке валидации.
• Ничьи: когда несколько артефактов готовы, их порядок в artifacts определяет, какой из них OpenSpec вернёт первым.

Поля применения

apply определяет, что должно существовать перед началом реализации.

Поле	Контракт
requires	Обязательное. Непустой список артефактов, которые должны существовать, прежде чем инструкции применения станут готовыми.
tracks	Необязательный относительный путь или glob для Markdown-файлов задач в папке изменения. По умолчанию: null.
instruction	Необязательное руководство, отправляемое агенту, когда применение готово. OpenSpec использует встроенное руководство по умолчанию.

requires артефакта управляет порядком планирования. apply.requires управляет тем, когда инструкции применения становятся готовыми.

tracks

Путь начинается от папки изменения. Для изменения с именем add-auth tracks: tasks.md читает:

openspec/changes/add-auth/tasks.md

Glob, такой как tracks: "**/tasks.md", читает каждый подходящий файл, например backend/tasks.md и frontend/tasks.md. OpenSpec объединяет их задачи и прогресс. Используйте то же значение для поля generates артефакта, чтобы статус и список отслеживали одни и те же файлы. Ограничения фигурных скобок из generates (16 уровней вглубь, 1 024 расширенных шаблона) применяются и здесь.

Применение остаётся заблокированным, если ни один файл не подходит или подходящие файлы не содержат чекбокса с текстом задачи. OpenSpec учитывает следующие формы чекбоксов:

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

Работает любой маркер списка Markdown: -, *, + или число до девяти цифр, за которым следует . или ). Разрешены ведущие пробелы. Раздел tasks.md страницы спецификационно-ориентированной разработки определяет более строгий формат, создаваемый схемой по умолчанию.

Отслеживаемые файлы управляют состоянием применения:

• blocked: ни один файл не подходит, или ни один читаемый файл не имеет чекбокса с текстом задачи.
• ready: хотя бы одна задача ожидает, или подходящий файл не удалось прочитать, в то время как другой предоставляет задачи.
• all_done: каждая отслеживаемая задача отмечена и каждый подходящий файл прочитан.

Если подходящий файл не удаётся прочитать, применение сохраняет задачи и прогресс из читаемых файлов, но не помечает изменение как all_done. JSON-вывод применения идентифицирует каждый недоступный файл и причину.

OpenSpec отклоняет абсолютные пути и пути, содержащие сегмент ...

Значения по умолчанию для применения

Поведение	По умолчанию
Обязательные артефакты	Каждый артефакт в схеме
Отслеживание прогресса	Нет отслеживаемого файла
Руководство агента	Встроенное руководство применения

Полный пример

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.

Валидация

openspec schema validate <name> проверяет:

• Типы полей и обязательные поля
• Относительные пути
• ID артефактов, зависимости и циклы
• ID apply.requires: каждый должен быть артефактом в схеме
• Файлы шаблонов

Схема с неизвестным ID в apply.requires не загружается, поэтому каждая команда, использующая её, сообщает об ошибке.

Валидация предупреждает, не считая ошибкой, когда apply.tracks не точно равно значению generates какого-либо артефакта. OpenSpec находит отслеживаемый артефакт, сравнивая эти две строки, поэтому любое другое значение не позволяет определить, прогрессу какого артефакта принадлежит файл. Это включает опечатку вроде task.md, а также tracks: tasks/main.md против generates: tasks/*.md, где glob действительно создаёт файл, но строки всё равно различаются. Применение в любом случае продолжает читать файл, но openspec list и openspec status учитывают tasks.md.

Валидация не обнаруживает следующие ошибки:

Ошибка	Что происходит
Поле написано с ошибкой, например instrution	OpenSpec игнорирует его. Валидация не сообщает об опечатке.
name отличается от каталога схемы	Валидация проходит. OpenSpec по-прежнему использует имя каталога для поиска.