schema.yaml

ทุกฟิลด์ในคำนิยาม schema ไม่ว่าจะเป็นการอ่านหรือการเขียน

schema.yaml ระบุรายการไฟล์การวางแผนที่เวิร์กโฟลว์สร้างขึ้น นอกจากนี้ยังกำหนดลำดับและการส่งต่อสู่การนำไปปฏิบัติ

ตำแหน่ง

schema ของโปรเจกต์อยู่ใน openspec/schemas/<name>/:

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

OpenSpec ตรวจสอบสามตำแหน่งสำหรับไดเรกทอรีนั้น ตำแหน่งที่ตรงกันอันแรกจะถูกใช้

สำเนา	ไดเรกทอรี
1. โปรเจกต์	<project>/openspec/schemas/<name>/
2. ผู้ใช้, macOS และ Linux	~/.local/share/openspec/schemas/<name>/
2. ผู้ใช้, Windows	%LOCALAPPDATA%\openspec\schemas\<name>\
3. แพ็กเกจ	schema ที่ติดตั้งพร้อมกับ CLI

หากตั้งค่า XDG_DATA_HOME ไดเรกทอรีผู้ใช้จะย้ายไปที่ $XDG_DATA_HOME/openspec/schemas/<name>/ บนทุกแพลตฟอร์ม

ชื่อไดเรกทอรีคือคีย์การค้นหาที่ใช้โดย --schema, config.yaml และ .openspec.yaml หากฟิลด์ name แตกต่างจากชื่อไดเรกทอรี OpenSpec จะยังคงใช้ชื่อไดเรกทอรีสำหรับการค้นหา

openspec schema which <name> พิมพ์ไดเรกทอรีที่ใช้งานอยู่และสำเนาที่มีความสำคัญต่ำกว่าที่ถูกซ่อนไว้

ฟิลด์ระดับบนสุด

ฟิลด์	ข้อกำหนด
name	จำเป็นต้องมี สตริงที่ไม่ว่างเปล่าซึ่งเก็บเป็นชื่อ schema การค้นหายังคงใช้ชื่อไดเรกทอรี
version	จำเป็นต้องมี จำนวนเต็มบวกที่เก็บเป็นรีวิชันของ schema ค่านี้ไม่เปลี่ยนพฤติกรรมของ OpenSpec
description	สตริงทางเลือกที่พิมพ์โดย openspec schemas หากไม่มีค่า schema จะไม่มีคำอธิบาย
artifacts	จำเป็นต้องมี รายการที่ไม่ว่างเปล่าของ รายการ artifact
apply	ทางเลือก การตั้งค่า apply หากไม่มีบล็อก OpenSpec จะใช้ ค่าเริ่มต้นของ apply

ฟิลด์ของ artifact

ฟิลด์	ข้อกำหนด
id	จำเป็นต้องมี สตริงที่ไม่ซ้ำและไม่ว่างเปล่าซึ่งใช้ใน dependencies, กฎของโปรเจกต์, คำสั่ง และการตั้งค่า apply
generates	จำเป็นต้องมี พาธสัมพัทธ์หรือ glob ที่บอก agent ว่าจะเขียน artifact ไว้ที่ใดภายในโฟลเดอร์การเปลี่ยนแปลง
description	จำเป็นต้องมี สตริงที่ใช้ติดป้ายกำกับ artifact ในคำสั่งที่ส่งไปยัง agent
template	จำเป็นต้องมี พาธสัมพัทธ์ไปยังรูปแบบของ artifact ในโฟลเดอร์ templates/ ของ schema
instruction	ทางเลือก คำแนะนำที่บอก agent ว่าควรสร้างเนื้อหาอะไร
requires	รายการของ ID artifact ที่ต้องเสร็จสมบูรณ์ก่อน ค่าเริ่มต้น: []

generates

พาธเริ่มต้นจากโฟลเดอร์การเปลี่ยนแปลง สำหรับการเปลี่ยนแปลงที่ชื่อ add-auth:

generates: proposal.md

artifact จะถูกวางไว้ที่นี่:

openspec/changes/add-auth/proposal.md

glob สามารถจับคู่ไฟล์หลายไฟล์ได้:

generates: specs/**/*.md

สิ่งนี้จับคู่ไฟล์ Markdown ที่อยู่ใต้ openspec/changes/add-auth/specs/

OpenSpec รู้จักรูปแบบ glob เหล่านี้ใน generates:

• ไวด์การ์ดและคลาสอักขระ: ค่าที่มี *, ? หรือ [ เช่น specs/**/*.md และ review-[ab].md
• การขยายวงเล็บปีกกา: ทางเลือกเช่น review-{api,ui}.md และช่วงเช่น file-{1..3}.md
• Extglobs: รูปแบบเช่น @(proposal|design).md, +(proposal|design).md และ !(proposal|design).md

ชื่อไฟล์ตามตัวอักษร: ! นำหน้าเพียงอย่างเดียวไม่ทำให้เป็น glob ใช้ generates: '!review.md' เพื่อระบุชื่อไฟล์นั้น วงเล็บธรรมดาเช่น (proposal|design).md และวงเล็บปีกกาแบบองค์ประกอบเดียวเช่น review-{api}.md จะยังคงเป็นตามตัวอักษร

OpenSpec ปฏิเสธพาธสัมบูรณ์ พาธที่มีส่วน .. และ glob ที่ซ้อนวงเล็บปีกกาหรือวงเล็บลึกเกิน 16 ระดับ เช่น {a,{b,{c,...}}} รูปแบบจริงต้องการหนึ่งหรือสองระดับ นอกจากนี้ยังปฏิเสธ glob ที่วงเล็บปีกกาขยายเป็นรูปแบบมากกว่า 1,024 รูปแบบ เช่น {a,b} ซ้ำสิบเอ็ดครั้งหรือช่วงเช่น file-{1..5000}.md ข้อผิดพลาดระบุว่า Artifact output pattern expands to more than 1024 patterns รูปแบบจริงขยายเป็นจำนวนเล็กน้อย

ความสมบูรณ์

OpenSpec ตรวจสอบว่าผลลัพธ์มีอยู่หรือไม่ ไม่ได้อ่านไฟล์เพื่อตัดสินใจว่า artifact เสร็จสมบูรณ์หรือไม่

ค่า generates	เสร็จสมบูรณ์เมื่อ
proposal.md	ไฟล์นั้นมีอยู่
specs/**/*.md	glob จับคู่ไฟล์อย่างน้อยหนึ่งไฟล์

template

พาธเริ่มต้นจากโฟลเดอร์ templates/ ของ schema ใน schema review-first:

template: proposal.md

OpenSpec อ่านไฟล์นี้:

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

OpenSpec มอบเนื้อหาของ template ให้กับ agent เป็นรูปแบบผลลัพธ์ ไม่ได้คัดลอก template ลงในโฟลเดอร์การเปลี่ยนแปลง

OpenSpec ปฏิเสธพาธสัมบูรณ์และพาธที่มีส่วน ..

requires

• การอ้างอิง: ทุก ID ใน requires ต้องระบุ artifact อื่นใน schema เดียวกัน
• สถานะพร้อม: artifact จะพร้อมหลังจากที่การอ้างอิงทั้งหมดเสร็จสมบูรณ์
• กราฟที่ไม่ถูกต้อง: ID ที่หายไป, ID ที่ซ้ำกัน และวงจรการอ้างอิงจะทำให้การตรวจสอบล้มเหลว
• การเสมอกัน: เมื่อมี artifact หลายรายการพร้อม ลำดับใน artifacts จะตัดสินว่า OpenSpec จะคืนค่ารายการใดก่อน

ฟิลด์ของ apply

ฟิลด์	ข้อกำหนด
requires	จำเป็นต้องมี รายการที่ไม่ว่างเปล่าของ artifact ที่ต้องมีอยู่ก่อนที่คำสั่ง apply จะพร้อม
tracks	ทางเลือก พาธสัมพัทธ์หรือ glob สำหรับไฟล์งาน Markdown ในโฟลเดอร์การเปลี่ยนแปลง ค่าเริ่มต้น: null
instruction	ทางเลือก คำแนะนำที่ส่งไปยัง agent เมื่อ apply พร้อม OpenSpec ใช้คำแนะนำในตัวโดยค่าเริ่มต้น

requires ของ artifact ควบคุมลำดับการวางแผน apply.requires ควบคุมเมื่อคำสั่ง apply พร้อม

tracks

พาธเริ่มต้นจากโฟลเดอร์การเปลี่ยนแปลง สำหรับการเปลี่ยนแปลงที่ชื่อ add-auth, tracks: tasks.md จะอ่าน:

openspec/changes/add-auth/tasks.md

glob เช่น tracks: "**/tasks.md" จะอ่านทุกไฟล์ที่ตรงกัน เช่น backend/tasks.md และ frontend/tasks.md OpenSpec รวมงานและความคืบหน้าของไฟล์เหล่านั้น ใช้ค่าเดียวกันสำหรับฟิลด์ generates ของ artifact เพื่อให้สถานะและรายการติดตามไฟล์เดียวกัน ข้อจำกัดของวงเล็บปีกกาจาก generates (ลึก 16 ระดับ, รูปแบบที่ขยาย 1,024 รูปแบบ) ใช้ที่นี่ด้วย

Apply จะยังคงถูกบล็อกหากไม่มีไฟล์ที่ตรงกันหรือไฟล์ที่ตรงกันไม่มีช่องทำเครื่องหมายที่มีข้อความงาน OpenSpec นับรูปแบบช่องทำเครื่องหมายเหล่านี้:

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

เครื่องหมายรายการ Markdown ใดก็ได้ใช้ได้: -, *, + หรือตัวเลขสูงสุดเก้าหลักตามด้วย . หรือ ) อนุญาตให้มีช่องว่างนำหน้า ส่วน tasks.md ของหน้า spec-driven กำหนดรูปแบบที่เข้มงวดกว่าที่สร้างโดย schema เริ่มต้น

ไฟล์ที่ติดตามจะขับเคลื่อนสถานะ apply:

• blocked: ไม่มีไฟล์ที่ตรงกัน หรือไม่มีไฟล์ที่อ่านได้ที่มีช่องทำเครื่องหมายพร้อมข้อความงาน
• ready: มีงานอย่างน้อยหนึ่งงานที่ค้างอยู่ หรือไฟล์ที่ตรงกันไม่สามารถอ่านได้ในขณะที่อีกไฟล์ให้งาน
• all_done: งานที่ติดตามทุกงานถูกทำเครื่องหมายและไฟล์ที่ตรงกันทุกไฟล์ถูกอ่านแล้ว

หากไฟล์ที่ตรงกันไม่สามารถอ่านได้ apply จะเก็บงานและความคืบหน้าจากไฟล์ที่อ่านได้ แต่จะไม่ทำเครื่องหมายการเปลี่ยนแปลงเป็น all_done ผลลัพธ์ JSON ของ Apply ระบุแต่ละไฟล์ที่ไม่สามารถใช้ได้และเหตุผล

OpenSpec ปฏิเสธพาธสัมบูรณ์และพาธที่มีส่วน ..

ค่าเริ่มต้นของ apply

พฤติกรรม	ค่าเริ่มต้น
artifact ที่จำเป็น	ทุก artifact ใน schema
การติดตามความคืบหน้า	ไม่มีไฟล์ที่ติดตาม
คำแนะนำสำหรับ agent	คำแนะนำ apply ในตัว

ตัวอย่างที่สมบูรณ์

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.

การตรวจสอบ

openspec schema validate <name> ตรวจสอบ:

• ชนิดฟิลด์และฟิลด์ที่จำเป็น
• พาธสัมพัทธ์
• ID ของ artifact, การอ้างอิง และวงจร
• ID ของ apply.requires: แต่ละรายการต้องเป็น artifact ใน schema
• ไฟล์ template

schema ที่มี ID apply.requires ที่ไม่รู้จักจะไม่โหลด ดังนั้นทุกคำสั่งที่ใช้มันจะรายงานข้อผิดพลาด

การตรวจสอบจะเตือนโดยไม่ทำให้ล้มเหลว เมื่อ apply.tracks ไม่เท่ากับค่า generates ของ artifact บางรายการโดยตรง OpenSpec ค้นหา artifact ที่ติดตามโดยการเปรียบเทียบสตริงสองตัวนั้น ดังนั้นสิ่งอื่นใดจะทำให้ไม่สามารถบอกได้ว่าไฟล์นั้นเป็นความคืบหน้าของ artifact ใด ซึ่งรวมถึงการพิมพ์ผิดเช่น task.md และรวมถึง tracks: tasks/main.md เทียบกับ generates: tasks/*.md ซึ่ง glob สร้างไฟล์นั้นจริงแต่สตริงยังคงต่างกัน Apply ยังคงอ่านไฟล์ไม่ว่ากรณีใด แต่ openspec list และ openspec status จะนับ tasks.md แทน

การตรวจสอบไม่จับข้อผิดพลาดเหล่านี้:

ข้อผิดพลาด	สิ่งที่เกิดขึ้น
ฟิลด์ถูกพิมพ์ผิด เช่น instrution	OpenSpec จะละเว้นมัน การตรวจสอบไม่รายงานการพิมพ์ผิด
name แตกต่างจากไดเรกทอรี schema	การตรวจสอบผ่าน OpenSpec ยังคงใช้ชื่อไดเรกทอรีสำหรับการค้นหา