Зміна метаданих (.openspec.yaml)

Підтримувані поля та правила перевірки для метаданих, що зберігаються разом із кожною зміною.

Розташування

Кожна зміна зберігає свої метадані у openspec/changes/<change-name>/.openspec.yaml, поруч зі своїми артефактами. Створення зміни записує файл із заповненими schema та created.

Поля

Ключ	Тип	Обов'язкове	Ефект
schema	рядок	Так	Схема робочого процесу, якої дотримується ця зміна
created	рядок, YYYY-MM-DD	Ні	Записує дату створення зміни
goal	рядок	Ні	Записує мету зміни
affected_areas	список рядків	Ні	Записує області, яких зміна планує торкнутися
initiative	об'єкт: store та id	Ні	Записує ініціативу, до якої належить ця зміна
skip_specs	булеве	Ні	Оголошує, що зміна не має дельт специфікацій, тому нуль дельт проходить перевірку
retire_capabilities	булеве	Ні	Дозволяє архіву видалити можливість, яку ця зміна спорожнює

schema

Схема робочого процесу, якої дотримується ця зміна. Вона встановлюється під час створення зміни та має пріоритет над конфігурацією проєкту, тому зміна зберігає свою схему, навіть якщо openspec/config.yaml зміниться пізніше. Виконайте openspec schemas, щоб переглянути доступні назви схем.

initiative

Ініціатива, до якої належить ця зміна, як ідентифікатор сховища та ідентифікатор ініціативи, обидва у kebab-case:

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

Ключі, відмінні від store та id, відхиляються. Жодна команда зараз не читає це посилання.

skip_specs

Оголошує, що зміна навмисно не створює дельт специфікацій: це чистий рефакторинг, зміна інструментів або документації. З цим налаштуванням перевірка приймає нуль дельт, а артефакти, які б генерували файли специфікацій, вважаються завершеними. Встановлення цього прапорця, коли файли специфікацій існують у specs/, є помилкою перевірки.

retire_capabilities

Дозволяє архіву вивести можливість з експлуатації. Коли дельти REMOVED цієї зміни забирають останню вимогу, яку має можливість, архів видаляє основний файл специфікації цієї можливості замість зупинки. Прапорець існує, оскільки видалення відновлюється лише з git, тому рішення залишається за автором.

Ключі розширення

Ключ верхнього рівня, що починається з малої літери x-, належить вам, для даних, які інший інструмент або ваша команда зберігає поруч зі зміною, наприклад, ідентифікатор трекера або власник:

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

• Назва: префікс x- у нижньому регістрі, за яким слідує принаймні один символ, без пробілів будь-де. Будь-який регістр або написання після префікса допустимі, тому x-jiraKey та x-trackerID підходять. X-Tracker, голий x- та x- tracker не підходять і повідомляються як невідомі ключі.
• Значення: будь-яке значення YAML. OpenSpec не читає та не перевіряє його, і воно не змінює жодної поведінки.
• Область застосування: лише верхній рівень. Ключ x- всередині initiative все одно відхиляється, як і будь-який інший ключ там.
• Перевірка: ключі розширення ніколи не повідомляються як невідомі, тому openspec validate --strict проходить для зміни, яка їх містить.
• Архів: файл переміщується разом зі зміною без змін, включно з ключами розширення.

Приклад

Заповнений .openspec.yaml:

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

Перевірка

Файл перевіряється щоразу, коли команда записує або читає його. Запис, який не проходить перевірку, викидає помилку та нічого не записує. Читання наявного файлу завершується помилкою через недійсний YAML, поле, яке порушує свій контракт, або назву схеми, яка недоступна. Відсутній файл не є помилкою, і зміна розглядається як така, що не має метаданих.

На відміну від config.yaml, погані значення ніколи не відкидаються з попередженням. Помилка метаданих зупиняє команду.

• Невідомі ключі верхнього рівня: OpenSpec їх ігнорує. status, instructions, validate та archive повідомляють, що вони не мають ефекту. JSON-вивід містить попередження у своєму структурованому результаті. Ключі розширення не є невідомими і ніколи не повідомляються.
• Сувора перевірка: openspec validate --strict розглядає попередження про невідомий ключ як помилку. Зміна, єдиними додатковими ключами якої є ключі розширення, проходить перевірку.