Изменение метаданных (.openspec.yaml)

Поддерживаемые поля и правила валидации для метаданных, хранящихся с каждым изменением.

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

Каждое изменение хранит свои метаданные в openspec/changes/<change-name>/.openspec.yaml, рядом с его артефактами. При создании изменения файл записывается с заполненными полями schema и created.

Поля

Ключ	Тип	Обязательное	Эффект
schema	string	Да	Схема рабочего процесса, которой следует это изменение
created	string, YYYY-MM-DD	Нет	Фиксирует дату создания изменения
goal	string	Нет	Фиксирует, что призвано сделать изменение
affected_areas	список строк	Нет	Фиксирует области, которых коснётся изменение
initiative	map: store и id	Нет	Фиксирует инициативу, к которой относится это изменение
skip_specs	boolean	Нет	Объявляет, что изменение не создаёт дельт спецификаций, поэтому нулевые дельты проходят валидацию
retire_capabilities	boolean	Нет	Разрешает архиву удалять возможность (capability), которую это изменение опустошает

schema

Схема рабочего процесса, которой следует это изменение. Устанавливается при создании изменения и имеет приоритет над конфигурацией проекта, поэтому изменение сохраняет свою схему, даже если openspec/config.yaml изменится впоследствии. Выполните openspec schemas, чтобы вывести список доступных имён схем.

initiative

Инициатива, к которой относится это изменение, в виде идентификатора хранилища (store id) и идентификатора инициативы, оба в kebab-case:

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

Ключи, отличные от store и id, отклоняются. Ни одна команда сегодня не читает эту связь.

skip_specs

Объявляет, что изменение намеренно не создаёт дельт спецификаций: чистый рефакторинг, инструментарий или изменение документации. При установленном флаге валидация принимает нулевые дельты, а артефакты, которые генерировали бы файлы спецификаций, считаются завершёнными. Установка этого флага при наличии файлов спецификаций в specs/ является ошибкой валидации.

retire_capabilities

Разрешает архиву вывести возможность (capability) из эксплуатации. Когда дельты 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 рассматривает предупреждение о неизвестном ключе как сбой. Изменение, единственными дополнительными ключами которого являются ключи расширений, проходит проверку.