Metadata Perubahan (.openspec.yaml)

Aturan dan aturan validasi untuk metadata yang disimpan dengan setiap perubahan.

Lokasi

Setiap perubahan menyimpan metadata di openspec/changes/<change-name>/.openspec.yaml, next to its artifacts. Membuat perubahan menulis file dengan schema dan created terisi.

Field

Key	Type	Required	Effect
schema	string	Yes	Skema alur kerja ini diikuti perubahan ini
created	string, YYYY-MM-DD	No	Mencatat tanggal perubahan dibuat
goal	string	No	Mencatat tujuan perubahan
affected_areas	list of strings	No	Mencatat area yang diharus disentuh perubahan
initiative	map: store and id	No	Mencatat inisiatif perubahan ini
skip_specs	boolean	No	Mendeklarasikan perubahan tidak membuat delta spesifikasi, sehingga validasi nol delta diterima
retire_capabilities	boolean	No	Mengotorisasi arsip untuk menghapus kemampuan yang dikosongkan perubahan ini

schema

Schema alur kerja ini diikuti perubahan ini. Ia ditetapkan ketika perubahan dibuat dan mengalahkan konfigurasi proyek, sehingga perubahan menahan skema meski openspec/config.yaml berubah kemudian. Jalankan openspec schemas untuk menampilkan nama skema yang tersedia.

initiative

Inisiatif perubahan ini, sebagai store id dan initiative id, ambos kebab-case:

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

Kunci selain store dan id ditolak. Tidak ada perintah yang membaca link ini hari.

skip_specs

Mendeklarasikan perubahan secara sengaja membuat delta spesifikasi nol: pembersihan murni, alat bantu, atau perubahan dokumentasi. Dengan ditetapkan, validasi menerima delta nol, dan artefak yang akan menghasilkan file spesifikasi dianggap selesai. Menetapkan sementara file spesifikasi ada di bawah specs/ adalah kesalahan validasi.

retire_capabilities

Mengotorisasi arsip untuk pensiun kemampuan. Ketika delta REMOVED perubahan ini mengangkat kebutuhan terakhir sebuah kemampuan, arsip menghapus spesifikasi utama kemampuan tersebut, bukan menghentikan. Tanda ini ada karena penghapusan hanya bisa dipulihkan dari git, jadi tetap menjadi panggilan penulis.

Extension keys

A top-level key that starts with a lowercase x- is yours, for data another tool or your team keeps beside the change, such as a tracker id or an owner:

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

• Name: the lowercase x- prefix followed by at least one character, with no whitespace anywhere. Any case or spelling works after the prefix, so x-jiraKey and x-trackerID qualify. X-Tracker, a bare x-, and x- tracker do not, and are reported as unknown keys.
• Value: any YAML value. OpenSpec does not read or validate it, and it changes no behavior.
• Scope: top-level only. An x- key inside initiative is still rejected, like any other key there.
• Validation: extension keys are never reported as unknown, so openspec validate --strict passes on a change that carries them.
• Archive: the file moves with the change unchanged, extension keys included.

Contoh

A filled-in .openspec.yaml:

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

Validasi

The file is validated whenever a command writes or reads it. A write that fails validation throws and writes nothing. Reading an existing file fails on invalid YAML, a field that breaks its contract, or a schema name that is not available. A missing file is not an error, and the change is treated as having no metadata.

Unlike config.yaml, bad values are never dropped with a warning. A metadata error stops the command.

• Unknown top-level keys: OpenSpec ignores them. status, instructions, validate, and archive report that they have no effect. JSON output carries the warning in its structured result. Extension keys are not unknown and are never reported.
• Strict validation: openspec validate --strict treats an unknown-key warning as a failure. A change whose only extra keys are extension keys passes.