ข้อมูลเมตาของ change (.openspec.yaml)

ฟิลด์ที่รองรับและกฎการตรวจสอบความถูกต้องสำหรับข้อมูลเมตาที่จัดเก็บไว้พร้อมกับแต่ละ change

ตำแหน่งไฟล์

แต่ละ change จัดเก็บข้อมูลเมตาไว้ที่ openspec/changes/<change-name>/.openspec.yaml ซึ่งอยู่ข้างๆ กับ artifact ต่างๆ ของ change นั้น การสร้าง change จะเขียนไฟล์นี้โดยกรอกค่า schema และ created ไว้ให้แล้ว

ฟิลด์

คีย์	ชนิดข้อมูล	จำเป็น	ผลลัพธ์
schema	string	ใช่	schema ของ workflow ที่ change นี้ใช้
created	string, YYYY-MM-DD	ไม่	บันทึกวันที่ที่ change ถูกสร้าง
goal	string	ไม่	บันทึกเป้าหมายว่า change นี้ตั้งใจจะทำอะไร
affected_areas	list ของ string	ไม่	บันทึกพื้นที่ที่ change คาดว่าจะส่งผลกระทบ
initiative	map: store และ id	ไม่	บันทึก initiative ที่ change นี้สังกัดอยู่
skip_specs	boolean	ไม่	ประกาศว่า change นี้ไม่มี spec delta ใดๆ จึงตรวจสอบผ่านได้แม้ delta เป็นศูนย์
retire_capabilities	boolean	ไม่	อนุญาตให้ archive ลบ capability ที่ change นี้ทำให้ว่างลง

schema

schema ของ workflow ที่ change นี้ใช้ ค่านี้จะถูกกำหนดตอนสร้าง change และมีลำดับความสำคัญเหนือกว่า config ของโปรเจกต์ ดังนั้น change จะยังคงใช้ schema เดิมแม้ว่า openspec/config.yaml จะถูกเปลี่ยนไปภายหลังก็ตาม รันคำสั่ง openspec schemas เพื่อแสดงรายชื่อ schema ที่มีให้ใช้งาน

initiative

initiative ที่ change นี้สังกัดอยู่ โดยระบุเป็น store id และ initiative id ซึ่งทั้งคู่ใช้รูปแบบ kebab-case:

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

คีย์อื่นที่ไม่ใช่ store และ id จะถูกปฏิเสธ ปัจจุบันยังไม่มีคำสั่งใดอ่านข้อมูลการเชื่อมโยงนี้

skip_specs

ประกาศว่า change นี้ตั้งใจไม่สร้าง spec delta ใดๆ เช่น การ refactor เพียงอย่างเดียว งาน tooling หรือการแก้ไขเอกสาร เมื่อตั้งค่านี้ไว้ การตรวจสอบจะยอมรับ delta เป็นศูนย์ และ artifact ที่ปกติจะสร้างไฟล์ spec ก็จะถือว่าสมบูรณ์แล้ว การตั้งค่านี้ขณะที่ยังมีไฟล์ spec อยู่ภายใต้ specs/ จะถือเป็นข้อผิดพลาดในการตรวจสอบ

retire_capabilities

อนุญาตให้ archive ปลดระวาง capability ได้ เมื่อ REMOVED delta ของ change นี้นำ requirement สุดท้ายที่ capability มีอยู่ออกไป archive จะลบ main spec ของ capability นั้นแทนที่จะหยุดทำงาน ที่ต้องมี flag นี้ขึ้นมาเพราะการลบดังกล่าวสามารถกู้คืนได้จาก git เท่านั้น จึงเป็นการตัดสินใจของผู้เขียน change เอง

คีย์ส่วนขยาย

คีย์ระดับบนสุดที่ขึ้นต้นด้วย x- ตัวพิมพ์เล็กถือเป็นพื้นที่ของคุณ ใช้สำหรับข้อมูลที่เครื่องมืออื่นหรือทีมของคุณเก็บไว้ควบคู่กับ change เช่น tracker id หรือเจ้าของงาน:

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

• ชื่อ: ต้องเป็น prefix x- ตัวพิมพ์เล็ก ตามด้วยอักขระอย่างน้อยหนึ่งตัว โดยห้ามมีช่องว่างในตำแหน่งใดๆ หลัง prefix จะใช้ตัวพิมพ์หรือการสะกดแบบใดก็ได้ ดังนั้น x-jiraKey และ x-trackerID จึงผ่านเกณฑ์ ส่วน X-Tracker, x- เปล่าๆ และ x- tracker ไม่ผ่าน และจะถูกรายงานเป็นคีย์ที่ไม่รู้จัก
• ค่า: เป็นค่า YAML แบบใดก็ได้ OpenSpec จะไม่อ่านหรือตรวจสอบค่านี้ และค่านี้ไม่ส่งผลต่อพฤติกรรมการทำงานใดๆ
• ขอบเขต: ใช้ได้เฉพาะระดับบนสุดเท่านั้น คีย์ x- ที่อยู่ภายใน initiative จะยังคงถูกปฏิเสธ เช่นเดียวกับคีย์อื่นๆ ทั้งหมดในส่วนนั้น
• การตรวจสอบ: คีย์ส่วนขยายจะไม่ถูกรายงานเป็นคีย์ที่ไม่รู้จัก ดังนั้น openspec validate --strict จะผ่านสำหรับ change ที่มีคีย์เหล่านี้ติดมาด้วย
• การ archive: ไฟล์จะถูกย้ายไปพร้อมกับ change โดยไม่มีการเปลี่ยนแปลง รวมถึงคีย์ส่วนขยายด้วย

ตัวอย่าง

ตัวอย่าง .openspec.yaml ที่กรอกข้อมูลครบแล้ว:

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

การตรวจสอบความถูกต้อง

ไฟล์นี้จะถูกตรวจสอบความถูกต้องทุกครั้งที่มีคำสั่งเขียนหรืออ่านไฟล์ การเขียนที่ตรวจสอบไม่ผ่านจะเกิด error ขึ้นและไม่มีการเขียนอะไรลงไปเลย การอ่านไฟล์ที่มีอยู่จะล้มเหลวหาก YAML ไม่ถูกต้อง ฟิลด์ใดฝ่าฝืนข้อกำหนดของตัวเอง หรือชื่อ schema ที่ระบุไม่มีให้ใช้งาน กรณีไฟล์ไม่มีอยู่จะไม่ถือเป็น error และ change จะถูกปฏิบัติเหมือนไม่มีข้อมูลเมตา

ต่างจาก config.yaml ค่าที่ไม่ถูกต้องจะไม่ถูกทิ้งไปพร้อมกับคำเตือน ข้อผิดพลาดของข้อมูลเมตาจะทำให้คำสั่งหยุดทำงาน

• คีย์ระดับบนสุดที่ไม่รู้จัก: OpenSpec จะเพิกเฉยต่อคีย์เหล่านี้ โดย status, instructions, validate และ archive จะถูกรายงานว่าไม่มีผลใดๆ ผลลัพธ์ JSON จะแนบคำเตือนนี้ไว้ใน structured result คีย์ส่วนขยาย ไม่ถือเป็นคีย์ที่ไม่รู้จัก และจะไม่ถูกรายงานเลย
• การตรวจสอบแบบ strict: openspec validate --strict ถือว่าคำเตือนเรื่องคีย์ที่ไม่รู้จักเป็นความล้มเหลว change ที่มีคีย์เพิ่มเติมเป็นคีย์ส่วนขยายเพียงอย่างเดียวจะผ่านการตรวจสอบ