Değişiklik meta verisi (.openspec.yaml)

Bir değişiklik ile birlikte saklanan meta verinin desteklenen alanları ve doğrulama kuralları.

Konum

Her değişiklik, artefaktlarının yanında, openspec/changes/<change-name>/.openspec.yaml adresinde meta verisini saklar. Bir değişiklik oluşturulduğunda, bu dosya schema ve created alanları doldurulmuş şekilde yazılır.

Alanlar

Anahtar	Tür	Zorunlu	Etki
schema	string	Evet	Bu değişikliğin uymakta olduğu çalışma akışı şeması
created	string, YYYY-MM-DD	Hayır	Değişikliğin oluşturulma tarihini kaydeder
goal	string	Hayır	Değişikliğin ne yapmak istediğini kaydeder
affected_areas	string listesi	Hayır	Değişikliğin dokunması beklenen alanları kaydeder
initiative	map: store ve id	Hayır	Bu değişikliğin ait olduğu inisiyatifi kaydeder
skip_specs	boolean	Hayır	Değişikliğin spesifik delta üretmediğini bildirir, böylece sıfır delta doğrulanır
retire_capabilities	boolean	Hayır	Arşivlemenin, bu değişiklikle boşaltılan bir yeteneği silmesine izin verir

schema

Bu değişikliğin uymakta olduğu çalışma akışı şeması. Değişiklik oluşturulduğunda ayarlanır ve proje yapılandırmasını geçersiz kılar; bu nedenle daha sonra openspec/config.yaml değişse bile değişiklik kendi şemasını korur. Kullanılabilir şema adlarını listelemek için openspec schemas komutunu çalıştırın.

initiative

Bu değişikliğin ait olduğu inisiyatif, hem kebab-case bir mağaza kimliği hem de bir inisiyatif kimliği olarak ifade edilir:

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

store ve id dışında kalan anahtarlar reddedilir. Günümüzde hiçbir komut bu bağlantıyı okumaz.

skip_specs

Değişikliğin bilinçli olarak spesifik delta üretmediğini bildirir: saf bir yeniden yapılandırma, araç veya dokümantasyon değişikliği. Bu ayarlandığında, doğrulama sıfır delta kabul eder ve spesifik dosyaları üretecek olan artefaktlar tamamlanmış sayılır. specs/ altında spesifik dosyalar varken bu ayarın yapılması bir doğrulama hatasıdır.

retire_capabilities

Arşivlemenin bir yeteneği emekli etmesine (kullanımdan kaldırmasına) izin verir. Bu değişikliğin REMOVED delta'ları bir yeteneğin son gerekliliğini kaldırırsa, arşivleme işlemi o yeteneğin ana spesifikini durdurmak yerine siler. Bu bayrağın var olma nedeni, silme işleminin yalnızca git'ten geri alınabilir olmasıdır; bu nedenle karar kullanıcının (yazarın) yetkisinde kalır.

Uzantı anahtarları

Küçük harf x- ile başlayan bir üst düzey anahtar, değişiklik ile birlikte tutulan ve başka bir aracın veya ekibinizin sahip olduğu veriler için size aittir; örneğin bir takipçi kimliği veya bir sahip:

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

• Ad: En az bir karakterle küçük harf x- öneki, herhangi bir yerde boşluk olmamalı. Önekinin ardından herhangi bir büyük/küçük harf veya yazım geçerlidir, bu nedenle x-jiraKey ve x-trackerID uygundur. X-Tracker, tek başına x- ve x- tracker uygun değildir ve bilinmeyen anahtar olarak raporlanır.
• Değer: Herhangi bir YAML değeri. OpenSpec bunu okumaz veya doğrulamaz ve davranışı değiştirmez.
• Kapsam: Yalnızca üst düzey. initiative içindeki bir x- anahtarı, oradaki diğer herhangi bir anahtar gibi reddedilir.
• Doğrulama: Uzantı anahtarları asla bilinmeyen olarak raporlanmaz, bu nedenle bunları taşıyan bir değişiklik üzerinde openspec validate --strict geçer.
• Arşivleme: Dosya, uzantı anahtarları dahil, değişiklik ile birlikte değiştirilmeden taşınır.

Örnek

Doldurulmuş bir .openspec.yaml:

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

Doğrulama

Dosya, bir komut yazdığı veya okuduğu zaman her doğrulanır. Doğrulaması başarısız olan bir yazma işlemi hata fırlatır ve hiçbir şey yazar. Mevcut bir dosyanın okunması, geçersiz YAML, sözleşmesini bozan bir alan veya kullanılabilir olmayan bir şema adı durumunda başarısız olur. Eksik dosya bir hata değildir ve değişiklik meta veriye sahip olmayan bir değişiklik olarak ele alınır.

config.yaml dosyasından farklı olarak, geçersiz değerler asla bir uyarı ile düşürülmez. Bir meta veri hatası komutu durdurur.

• Bilinmeyen üst düzey anahtarlar: OpenSpec bunları yoksayar. status, instructions, validate ve archive herhangi bir etkilerinin olmadığını bildirir. JSON çıktısı uyarıyı yapılandırılmış sonucunda taşır. Uzantı anahtarları bilinmeyen değildir ve asla raporlanmaz.
• Katı doğrulama: openspec validate --strict, bilinmeyen anahtar uyarısını bir başarısızlık olarak ele alır. Ekstra anahtarları yalnızca uzantı anahtarlarından oluşan bir değişiklik geçer.