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.

Літеральні імена файлів: провідний ! сам по собі не робить рядок глобом. Використовуйте generates: '!review.md', щоб назвати цей файл. Звичайні дужки, такі як (proposal|design).md, та фігурні дужки з одним елементом, такі як review-{api}.md, також залишаються літеральними.

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

Завершення

OpenSpec перевіряє, чи існує вивід. Він не читає файл, щоб вирішити, чи завершено артефакт.

Значення generates	Повністю, коли
proposal.md	Існує цей файл.
specs/**/*.md	Глоб відповідає щонайменше одному файлу.

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

Глоб, такий як tracks: "**/tasks.md", читає кожен відповідний файл, наприклад backend/tasks.md та frontend/tasks.md. OpenSpec об'єднує їхні завдання та прогрес. Використовуйте те саме значення для поля generates артефакта, щоб статус і список відстежували ті самі файли. Обмеження фігурних дужок з generates (16 рівнів глибини, 1024 розгорнуті шаблони) застосовуються тут також.

Застосування залишається заблокованим, якщо жоден файл не відповідає або відповідні файли не містять прапорців із текстом завдання. OpenSpec рахує ці форми прапорців:

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

Працює будь-який маркер списку Markdown: -, *, + або число до дев'яти цифр, за яким слідує . або ). Допускаються провідні пробіли. Розділ tasks.md сторінки spec-driven визначає суворіший формат, який виробляє схема за замовчуванням.

Відстежувані файли керують станом застосування:

• 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> перевіряє:

• Типи полів та обов'язкові поля
• Відносні шляхи
• Ідентифікатори артефактів, залежності та цикли
• Ідентифікатори apply.requires: кожен має бути артефактом у схемі
• Файли шаблонів

Схема з невідомим ID apply.requires не завантажується, тому кожна команда, яка її використовує, повідомляє про помилку.

Валідація попереджає (без зупинки), якщо apply.tracks не дорівнює точно значенню generates деякого артефакта. OpenSpec знаходить відстежуваний артефакт, порівнюючи ці два рядки, тому будь-яка інша різниця залишає його нездатним визначити, чий прогрес належить цьому файлу. Це включає одруківку, таку як task.md, а також tracks: tasks/main.md проти generates: tasks/*.md, де глоб дійсно виробляє файл, але рядки все ще відрізняються. Застосування продовжує читати файл у будь-якому випадку, але openspec list та openspec status рахують tasks.md натомість.

Валідація не ловить ці помилки:

Помилка	Що відбувається
Поле написано неправильно, наприклад instrution	OpenSpec ігнорує його. Валідація не повідомляє про одруківку.
name відрізняється від каталогу схеми	Валідація проходить успішно. OpenSpec все одно використовує ім'я каталогу для пошуку.