schema.yaml

Setiap bidang dari definisi skema, untuk membaca atau menulis satu.

schema.yaml mencantumkan file perencanaan yang dibuat oleh alur kerja. File ini juga mendefinisikan urutannya dan penyerahan ke implementasi.

Lokasi

Skema proyek berada di bawah openspec/schemas/<name>/:

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

OpenSpec memeriksa tiga lokasi untuk direktori tersebut. Kecocokan pertama yang menang.

Salinan	Direktori
1. Proyek	<project>/openspec/schemas/<name>/
2. Pengguna, macOS dan Linux	~/.local/share/openspec/schemas/<name>/
2. Pengguna, Windows	%LOCALAPPDATA%\openspec\schemas\<name>\
3. Paket	Skema yang diinstal dengan CLI

Jika XDG_DATA_HOME disetel, direktori pengguna berpindah ke $XDG_DATA_HOME/openspec/schemas/<name>/ di setiap platform.

Nama direktori adalah kunci pencarian yang digunakan oleh --schema, config.yaml, dan .openspec.yaml. Jika bidang name berbeda dari nama direktori, OpenSpec tetap menggunakan nama direktori untuk pencarian.

openspec schema which <name> mencetak direktori aktif dan salinan prioritas lebih rendah yang disembunyikannya.

Bidang tingkat atas

Bidang	Kontrak
name	Wajib. String non-kosong yang disimpan sebagai nama skema. Pencarian tetap menggunakan nama direktori.
version	Wajib. Bilangan bulat positif yang disimpan sebagai revisi skema. Nilai tersebut tidak mengubah perilaku OpenSpec.
description	String opsional yang dicetak oleh openspec schemas. Tanpa nilai, skema tidak memiliki deskripsi.
artifacts	Wajib. Daftar non-kosong dari entri artefak.
apply	Opsional pengaturan apply. Tanpa blok, OpenSpec menggunakan default apply.

Bidang artefak

Setiap entri di bawah artifacts mendefinisikan satu file perencanaan atau kumpulan file.

Bidang	Kontrak
id	Wajib. String unik dan non-kosong yang digunakan dalam dependensi, aturan proyek, perintah, dan pengaturan apply.
generates	Wajib. Jalur relatif atau glob yang memberi tahu agen di mana menulis artefak di dalam folder perubahan.
description	Wajib. String yang memberi label pada artefak dalam instruksi yang dikirim ke agen.
template	Wajib. Jalur relatif ke format artefak di folder templates/ skema.
instruction	Panduan opsional yang memberi tahu agen konten apa yang harus diproduksi.
requires	Daftar ID artefak yang harus selesai terlebih dahulu. Default: [].

generates

Jalur dimulai dari folder perubahan. Untuk perubahan bernama add-auth:

generates: proposal.md

Artefak ditempatkan di sini:

openspec/changes/add-auth/proposal.md

Glob dapat mencocokkan beberapa file:

generates: specs/**/*.md

Ini mencocokkan file Markdown di bawah openspec/changes/add-auth/specs/.

OpenSpec mengenali bentuk glob berikut dalam generates:

• Wildcard dan kelas karakter: nilai yang mengandung *, ?, atau [, seperti specs/**/*.md dan review-[ab].md.
• Ekspansi kurung kurawal: alternatif seperti review-{api,ui}.md dan rentang seperti file-{1..3}.md.
• Extglob: pola seperti @(proposal|design).md, +(proposal|design).md, dan !(proposal|design).md.

Nama file literal: tanda ! di awal saja tidak membuat glob. Gunakan generates: '!review.md' untuk menamai file tersebut. Tanda kurung biasa seperti (proposal|design).md dan kurung kurawal satu elemen seperti review-{api}.md juga tetap literal.

OpenSpec menolak jalur absolut, jalur yang mengandung segmen .., dan glob yang menyarangkan kurung kurawal atau tanda kurung lebih dari 16 tingkat kedalaman, seperti {a,{b,{c,...}}}. Pola nyata hanya membutuhkan satu atau dua tingkat. OpenSpec juga menolak glob yang kurung kurawalnya mengembang menjadi lebih dari 1.024 pola, seperti {a,b} yang diulang sebelas kali atau rentang seperti file-{1..5000}.md. Kesalahannya mengatakan Artifact output pattern expands to more than 1024 patterns. Pola nyata mengembang menjadi beberapa saja.

Penyelesaian

OpenSpec memeriksa apakah output ada. OpenSpec tidak membaca file untuk memutuskan apakah artefak sudah lengkap.

Nilai generates	Lengkap ketika
proposal.md	File tersebut ada.
specs/**/*.md	Glob tersebut mencocokkan setidaknya satu file.

template

Jalur dimulai dari folder templates/ skema. Dalam skema review-first:

template: proposal.md

OpenSpec membaca file ini:

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

OpenSpec memberikan isi template kepada agen sebagai format output. OpenSpec tidak menyalin template ke dalam folder perubahan.

OpenSpec menolak jalur absolut dan jalur yang mengandung segmen ...

requires

• Dependensi: setiap ID dalam requires harus menamai artefak lain dalam skema yang sama.
• Status siap: sebuah artefak menjadi siap setelah semua dependensinya lengkap.
• Graf tidak valid: ID yang hilang, ID duplikat, dan siklus dependensi gagal validasi.
• Ikatan: ketika beberapa artefak siap, urutannya dalam artifacts menentukan mana yang dikembalikan OpenSpec terlebih dahulu.

Bidang apply

apply mendefinisikan apa yang harus ada sebelum implementasi dimulai.

Bidang	Kontrak
requires	Wajib. Daftar non-kosong artefak yang harus ada sebelum instruksi apply menjadi siap.
tracks	Jalur relatif atau glob opsional untuk file tugas Markdown di folder perubahan. Default: null.
instruction	Panduan opsional yang dikirim ke agen ketika apply siap. OpenSpec menggunakan panduan bawaan secara default.

requires artefak mengontrol urutan perencanaan. apply.requires mengontrol kapan instruksi apply menjadi siap.

tracks

Jalur dimulai dari folder perubahan. Untuk perubahan bernama add-auth, tracks: tasks.md membaca:

openspec/changes/add-auth/tasks.md

Glob seperti tracks: "**/tasks.md" membaca setiap file yang cocok, seperti backend/tasks.md dan frontend/tasks.md. OpenSpec menggabungkan tugas dan progresnya. Gunakan nilai yang sama untuk bidang generates artefak sehingga status dan daftar melacak file yang sama. Batas kurung kurawal dari generates (16 tingkat kedalaman, 1.024 pola yang mengembang) juga berlaku di sini.

Apply tetap terblokir jika tidak ada file yang cocok atau file yang cocok tidak mengandung kotak centang dengan teks tugas. OpenSpec menghitung bentuk kotak centang berikut:

- [ ] Pending task
- [x] Completed task
* [X] Completed task
+ [ ] Pending task
1. [ ] Pending task
2) [x] Completed task

Penanda daftar Markdown apa pun berfungsi: -, *, +, atau angka hingga sembilan digit yang diikuti oleh . atau ). Spasi di awal diperbolehkan. Bagian tasks.md pada halaman spec-driven mendefinisikan format yang lebih ketat yang dihasilkan oleh skema default.

File yang dilacak menggerakkan status apply:

• blocked: tidak ada file yang cocok, atau tidak ada file yang dapat dibaca memiliki kotak centang dengan teks tugas.
• ready: setidaknya satu tugas tertunda, atau file yang cocok tidak dapat dibaca sementara file lain menyediakan tugas.
• all_done: setiap tugas yang dilacak telah dicentang dan setiap file yang cocok telah dibaca.

Jika file yang cocok tidak dapat dibaca, apply tetap menyimpan tugas dan progres dari file yang dapat dibaca tetapi tidak menandai perubahan sebagai all_done. Output JSON apply mengidentifikasi setiap file yang tidak tersedia dan alasannya.

OpenSpec menolak jalur absolut dan jalur yang mengandung segmen ...

Default apply

Perilaku	Default
Artefak wajib	Setiap artefak dalam skema
Pelacakan progres	Tidak ada file yang dilacak
Panduan agen	Panduan apply bawaan

Contoh lengkap

name: review-first
version: 1
description: Proposal and implementation checklist

artifacts:
  - id: proposal
    generates: proposal.md
    description: Why the change is needed and what it affects
    template: proposal.md
    instruction: |
      Explain the problem, the proposed change, and its impact.
    requires: []

  - id: tasks
    generates: tasks.md
    description: Trackable implementation checklist
    template: tasks.md
    instruction: |
      Break the approved proposal into ordered implementation tasks.
    requires:
      - proposal

apply:
  requires:
    - tasks
  tracks: tasks.md
  instruction: |
    Work through the pending tasks and mark each one complete.

Validasi

openspec schema validate <name> memeriksa:

• Tipe bidang dan bidang wajib
• Jalur relatif
• ID artefak, dependensi, dan siklus
• ID apply.requires: masing-masing harus merupakan artefak dalam skema
• File template

Skema dengan ID apply.requires yang tidak dikenal tidak dimuat, sehingga setiap perintah yang menggunakannya melaporkan kesalahan.

Validasi memperingatkan, tanpa gagal, ketika apply.tracks tidak persis sama dengan nilai generates suatu artefak. OpenSpec menemukan artefak yang dilacak dengan membandingkan kedua string tersebut, sehingga hal lain membuatnya tidak dapat mengetahui progres artefak mana yang dimiliki file tersebut. Itu termasuk salah ketik seperti task.md, dan juga tracks: tasks/main.md terhadap generates: tasks/*.md, di mana glob memang menghasilkan file tetapi stringnya tetap berbeda. Apply tetap membaca file tersebut apa pun yang terjadi, tetapi openspec list dan openspec status menghitung tasks.md sebagai gantinya.

Validasi tidak menangkap kesalahan berikut:

Kesalahan	Yang terjadi
Bidang salah eja, seperti instrution	OpenSpec mengabaikannya. Validasi tidak melaporkan salah ketik tersebut.
name berbeda dari direktori skema	Validasi lolos. OpenSpec tetap menggunakan nama direktori untuk pencarian.