schema.yaml

Bir şema tanımının her alanı, bir tanesini okumak veya yazmak için.

schema.yaml, bir iş akışının oluşturduğu planlama dosyalarını listeler. Ayrıca bunların sırasını ve uygulamaya aktarımı tanımlar.

Konum

Bir proje şeması openspec/schemas/<name>/ altında yer alır:

openspec/schemas/review-first/
├── schema.yaml
└── templates/
    ├── proposal.md
    └── tasks.md

OpenSpec bu dizin için üç yeri kontrol eder. İlk eşleşme kazanır.

Kopya	Dizin
1. Proje	<project>/openspec/schemas/<name>/
2. Kullanıcı, macOS ve Linux	~/.local/share/openspec/schemas/<name>/
2. Kullanıcı, Windows	%LOCALAPPDATA%\openspec\schemas\<name>\
3. Paket	CLI ile kurulan şemalar

XDG_DATA_HOME ayarlanmışsa, kullanıcı dizini her platformda $XDG_DATA_HOME/openspec/schemas/<name>/ konumuna taşınır.

Dizin adı, --schema, config.yaml ve .openspec.yaml tarafından kullanılan arama anahtarıdır. name alanı dizin adından farklıysa, OpenSpec arama için yine dizin adını kullanır.

openspec schema which <name> etkin dizini ve gizlediği düşük öncelikli kopyaları yazdırır.

Üst düzey alanlar

Alan	Sözleşme
name	Gerekli. Şema adı olarak saklanan boş olmayan bir dize. Arama yine dizin adını kullanır.
version	Gerekli. Şema revizyonu olarak saklanan pozitif bir tam sayı. Değer, OpenSpec'in davranışını değiştirmez.
description	openspec schemas tarafından yazdırılan isteğe bağlı bir dize. Değer yoksa, şemanın açıklaması yoktur.
artifacts	Gerekli. Boş olmayan bir artifact girdileri listesi.
apply	İsteğe bağlı apply ayarları. Blok yoksa, OpenSpec apply varsayılanlarını kullanır.

Artifact alanları

artifacts altındaki her girdi bir planlama dosyasını veya dosya kümesini tanımlar.

Alan	Sözleşme
id	Gerekli. Bağımlılıklarda, proje kurallarında, komutlarda ve apply ayarlarında kullanılan benzersiz, boş olmayan bir dize.
generates	Gerekli. Agent'a değişiklik klasörü içinde artifact'ı nereye yazacağını söyleyen göreli bir yol veya glob.
description	Gerekli. Agent'a gönderilen talimatlarda artifact'ı etiketleyen bir dize.
template	Gerekli. Şemanın templates/ klasöründe artifact'ın biçimine giden göreli bir yol.
instruction	Agent'a ne içerik üreteceğini söyleyen isteğe bağlı rehberlik.
requires	Önce tamamlanması gereken artifact ID'lerinin listesi. Varsayılan: [].

generates

Yol değişiklik klasöründen başlar. add-auth adlı bir değişiklik için:

generates: proposal.md

Artifact buraya gider:

openspec/changes/add-auth/proposal.md

Bir glob birden fazla dosya ile eşleşebilir:

generates: specs/**/*.md

Bu, openspec/changes/add-auth/specs/ altındaki Markdown dosyaları ile eşleşir.

OpenSpec, generates içinde şu glob biçimlerini tanır:

• Wildcard'lar ve karakter sınıfları: *, ? veya [ içeren değerler, örneğin specs/**/*.md ve review-[ab].md.
• Küme parantezi genişletmeleri: review-{api,ui}.md gibi alternatifler ve file-{1..3}.md gibi aralıklar.
• Extglob'lar: @(proposal|design).md, +(proposal|design).md ve !(proposal|design).md gibi desenler.

Gerçek dosya adları: yalnızca baştaki ! bir glob yapmaz. O dosyayı adlandırmak için generates: '!review.md' kullanın. (proposal|design).md gibi düz parantezler ve review-{api}.md gibi tek öğeli küme parantezleri de gerçek kalır.

OpenSpec mutlak yolları, .. segmenti içeren yolları ve küme parantezlerini veya parantezleri 16 seviyeden fazla iç içe geçiren glob'ları reddeder, örneğin {a,{b,{c,...}}}. Gerçek desenler bir veya iki seviyeye ihtiyaç duyar. Ayrıca küme parantezleri 1.024'ten fazla desene genişleyen glob'ları reddeder, örneğin on bir kez tekrarlanan {a,b} veya file-{1..5000}.md gibi bir aralık. Hata Artifact output pattern expands to more than 1024 patterns der. Gerçek desenler bir avuç genişler.

Tamamlanma

OpenSpec çıktının var olup olmadığını kontrol eder. Artifact'ın tamamlanıp tamamlanmadığına karar vermek için dosyayı okumaz.

generates değeri	Ne zaman tamamlanır
proposal.md	O dosya varken.
specs/**/*.md	Glob en az bir dosya ile eşleştiğinde.

template

Yol şemanın templates/ klasöründen başlar. review-first şemasında:

template: proposal.md

OpenSpec şu dosyayı okur:

openspec/schemas/review-first/templates/proposal.md

OpenSpec şablonun içeriğini agent'a çıktı biçimi olarak verir. Şablonu değişiklik klasörüne kopyalamaz.

OpenSpec mutlak yolları ve .. segmenti içeren yolları reddeder.

requires

• Bağımlılıklar: requires içindeki her ID aynı şemadaki başka bir artifact'ı adlandırmalıdır.
• Hazır durum: bir artifact tüm bağımlılıkları tamamlandıktan sonra hazır olur.
• Geçersiz grafikler: eksik ID'ler, yinelenen ID'ler ve bağımlılık döngüleri doğrulamayı başarısız kılar.
• Eşitlikler: birden fazla artifact hazır olduğunda, artifacts içindeki sıraları OpenSpec'in hangisini ilk döndüreceğini belirler.

Apply alanları

apply, uygulamanın başlamasından önce neyin var olması gerektiğini tanımlar.

Alan	Sözleşme
requires	Gerekli. Apply talimatları hazır hale gelmeden önce var olması gereken artifact'ların boş olmayan bir listesi.
tracks	Değişiklik klasöründeki Markdown görev dosyaları için isteğe bağlı göreli bir yol veya glob. Varsayılan: null.
instruction	Apply hazır olduğunda agent'a gönderilen isteğe bağlı rehberlik. OpenSpec varsayılan olarak yerleşik rehberliği kullanır.

Artifact requires planlama sırasını kontrol eder. apply.requires apply talimatlarının ne zaman hazır olacağını kontrol eder.

tracks

Yol değişiklik klasöründen başlar. add-auth adlı bir değişiklik için, tracks: tasks.md şunu okur:

openspec/changes/add-auth/tasks.md

tracks: "**/tasks.md" gibi bir glob, backend/tasks.md ve frontend/tasks.md gibi eşleşen her dosyayı okur. OpenSpec görevlerini ve ilerlemelerini birleştirir. Durum ve listenin aynı dosyaları izlemesi için artifact'ın generates alanı için aynı değeri kullanın. generates'den gelen küme parantezi sınırları (16 seviye derinlik, 1.024 genişletilmiş desen) burada da geçerlidir.

Hiçbir dosya eşleşmezse veya eşleşen dosyalarda görev metni içeren onay kutusu yoksa apply kilitli kalır. OpenSpec şu onay kutusu biçimlerini sayar:

- [ ] Bekleyen görev
- [x] Tamamlanan görev
* [X] Tamamlanan görev
+ [ ] Bekleyen görev
1. [ ] Bekleyen görev
2) [x] Tamamlanan görev

Herhangi bir Markdown liste işareti çalışır: -, *, +, veya . veya ) izleyen dokuza kadar bir sayı. Baştaki boşluklara izin verilir. Spec-driven sayfasının tasks.md bölümü varsayılan şema tarafından üretilen daha katı biçimi tanımlar.

İzlenen dosyalar apply durumunu yönetir:

• blocked: hiçbir dosya eşleşmiyor veya okunabilir hiçbir dosyada görev metni içeren onay kutusu yok.
• ready: en az bir görev bekliyor veya eşleşen bir dosya, başka bir dosya görev sağlarken okunamadı.
• all_done: izlenen her görev işaretli ve eşleşen her dosya okundu.

Eşleşen bir dosya okunamıyorsa, apply okunabilir dosyalardan gelen görevleri ve ilerlemeyi korur ancak değişikliği all_done olarak işaretlemez. Apply JSON çıktısı her kullanılamayan dosyayı ve nedeni tanımlar.

OpenSpec mutlak yolları ve .. segmenti içeren yolları reddeder.

Apply varsayılanları

Davranış	Varsayılan
Gerekli artifact'lar	Şemadaki her artifact
İlerleme izleme	İzlenen dosya yok
Agent rehberliği	Yerleşik apply rehberliği

Tam örnek

name: review-first
version: 1
description: Öneri ve uygulama kontrol listesi

artifacts:
  - id: proposal
    generates: proposal.md
    description: Değişikliğe neden ihtiyaç duyulduğu ve neyi etkilediği
    template: proposal.md
    instruction: |
      Problemi, önerilen değişikliği ve etkisini açıklayın.
    requires: []

  - id: tasks
    generates: tasks.md
    description: İzlenebilir uygulama kontrol listesi
    template: tasks.md
    instruction: |
      Onaylanan öneriyi sıralı uygulama görevlerine bölün.
    requires:
      - proposal

apply:
  requires:
    - tasks
  tracks: tasks.md
  instruction: |
    Bekleyen görevleri çalışın ve her birini tamamlandı olarak işaretleyin.

Doğrulama

openspec schema validate <name> şunları kontrol eder:

• Alan türleri ve gerekli alanlar
• Göreli yollar
• Artifact ID'leri, bağımlılıklar ve döngüler
• apply.requires ID'leri: her biri şemada bir artifact olmalıdır
• Şablon dosyaları

Bilinmeyen bir apply.requires ID'sine sahip bir şema yüklenmez, bu nedenle onu kullanan her komut hatayı bildirir.

Doğrulama, apply.tracks değeri bir artifact'ın generates değerine tam olarak eşit olmadığında başarısız olmadan uyarır. OpenSpec izlenen artifact'ı bu iki dizeyi karşılaştırarak bulur, bu nedenle başka herhangi bir şey hangi artifact'ın ilerlemesine ait olduğunu söylemesini engeller. Bu, task.md gibi bir yazım hatasını ve ayrıca tracks: tasks/main.md'nin generates: tasks/*.md'ye karşı olduğu durumu içerir; burada glob dosyayı üretir ancak dizeler yine farklıdır. Apply her iki durumda da dosyayı okumaya devam eder, ancak openspec list ve openspec status bunun yerine tasks.md'yi sayar.

Doğrulama şu hataları yakalamaz:

Hata	Ne olur
Bir alan yanlış yazılmış, örneğin instrution	OpenSpec onu yok sayar. Doğrulama yazım hatasını bildirmez.
name şema dizininden farklı	Doğrulama geçer. OpenSpec arama için yine dizin adını kullanır.