Метаданные изменения (.openspec.yaml)

РасположениеCopy Anchor Link

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

ПоляCopy Anchor Link

schemaCopy Anchor Link

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

initiativeCopy Anchor Link

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

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

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

skip_specsCopy Anchor Link

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

retire_capabilitiesCopy Anchor Link

Разрешает при архивировании удалить возможность. Когда дельты REMOVED этого изменения удаляют последнее требование возможности, при архивировании удаляется её основная спецификация, а операция не останавливается. Этот флаг нужен потому, что удаление можно отменить только с помощью git, поэтому решение остаётся за автором.

Ключи расширенийCopy Anchor Link

Ключ верхнего уровня, начинающийся со строчного 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 успешно выполняется для изменения, которое их содержит.
• Архив: файл перемещается вместе с изменением без изменений, включая ключи расширений.

ПримерCopy Anchor Link

Заполненный файл .openspec.yaml:

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

ВалидацияCopy Anchor Link

Файл проходит валидацию каждый раз, когда команда записывает или читает его. При ошибке валидации во время записи выбрасывается исключение, и ничего не записывается. Чтение существующего файла завершается ошибкой, если YAML недопустим, поле нарушает свой контракт или имя схемы недоступно. Отсутствие файла не является ошибкой: изменение считается не имеющим метаданных.

В отличие от config.yaml, недопустимые значения никогда не отбрасываются с предупреждением. Ошибка метаданных останавливает команду.

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