schema.yaml

Mọi trường của một định nghĩa schema, dùng để đọc hoặc ghi một schema.

schema.yaml liệt kê các tệp lập kế hoạch mà một workflow tạo ra. Tệp này cũng xác định thứ tự của chúng và việc bàn giao cho triển khai.

Vị trí

Schema của dự án nằm trong openspec/schemas/<name>/:

text

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

OpenSpec kiểm tra ba nơi để tìm thư mục đó. Nơi khớp đầu tiên sẽ được chọn.

Bản sao	Thư mục
1. Dự án	`<project>/openspec/schemas/<name>/`
2. Người dùng, macOS và Linux	`~/.local/share/openspec/schemas/<name>/`
2. Người dùng, Windows	`%LOCALAPPDATA%\openspec\schemas\<name>\`
3. Gói	Các schema được cài đặt cùng CLI

Nếu XDG_DATA_HOME được đặt, thư mục người dùng sẽ chuyển sang $XDG_DATA_HOME/openspec/schemas/<name>/ trên mọi nền tảng.

Tên thư mục là khóa tra cứu được --schema, config.yaml và .openspec.yaml sử dụng. Nếu trường name khác với tên thư mục, OpenSpec vẫn dùng tên thư mục để tra cứu.

openspec schema which <name> in ra thư mục đang hoạt động và mọi bản sao có độ ưu tiên thấp hơn mà nó che khuất.

Các trường cấp cao nhất

Trường	Ràng buộc
`name`	Bắt buộc. Một chuỗi không rỗng được lưu làm tên schema. Việc tra cứu vẫn dùng tên thư mục.
`version`	Bắt buộc. Một số nguyên dương được lưu làm bản sửa đổi schema. Giá trị này không làm thay đổi hành vi của OpenSpec.
`description`	Một chuỗi tùy chọn được `openspec schemas` in ra. Khi không có giá trị, schema không có mô tả.
`artifacts`	Bắt buộc. Danh sách không rỗng gồm các mục artifact.
`apply`	Các thiết lập apply tùy chọn. Khi không có khối này, OpenSpec dùng giá trị mặc định của apply.

Các trường artifact

Mỗi mục trong artifacts xác định một tệp lập kế hoạch hoặc một tập tệp.

Trường	Ràng buộc
`id`	Bắt buộc. Một chuỗi duy nhất, không rỗng được dùng trong các phụ thuộc, quy tắc dự án, lệnh và thiết lập apply.
`generates`	Bắt buộc. Một đường dẫn tương đối hoặc glob cho agent biết nơi ghi artifact bên trong thư mục thay đổi.
`description`	Bắt buộc. Một chuỗi gắn nhãn artifact trong các hướng dẫn được gửi đến agent.
`template`	Bắt buộc. Một đường dẫn tương đối đến định dạng của artifact trong thư mục `templates/` của schema.
`instruction`	Hướng dẫn tùy chọn cho agent biết nội dung cần tạo.
`requires`	Danh sách các ID artifact phải hoàn thành trước. Mặc định: `[]`.

`generates`

Đường dẫn bắt đầu từ thư mục thay đổi. Với một thay đổi có tên add-auth:

yaml

generates: proposal.md

Artifact được đặt tại đây:

text

openspec/changes/add-auth/proposal.md

Một glob có thể khớp với nhiều tệp:

yaml

generates: specs/**/*.md

Mẫu này khớp với các tệp Markdown nằm dưới openspec/changes/add-auth/specs/.

OpenSpec nhận diện các dạng glob sau trong generates:

Ký tự đại diện và lớp ký tự: các giá trị chứa *, ? hoặc [, chẳng hạn như specs/**/*.md và review-[ab].md.
Mở rộng dấu ngoặc nhọn: các lựa chọn thay thế như review-{api,ui}.md và các dải như file-{1..3}.md.
Extglob: các mẫu như @(proposal|design).md, +(proposal|design).md và !(proposal|design).md.

Tên tệp nguyên văn: một dấu ! ở đầu tự nó không tạo thành glob. Dùng generates: '!review.md' để đặt tên cho tệp đó. Dấu ngoặc đơn thường như (proposal|design).md và dấu ngoặc nhọn một phần tử như review-{api}.md cũng được giữ nguyên văn.

OpenSpec từ chối các đường dẫn tuyệt đối, đường dẫn chứa phân đoạn .. và các glob lồng dấu ngoặc nhọn hoặc ngoặc đơn sâu hơn 16 cấp, chẳng hạn như {a,{b,{c,...}}}. Các mẫu thực tế chỉ cần một hoặc hai cấp. Nó cũng từ chối một glob mà dấu ngoặc nhọn mở rộng thành hơn 1.024 mẫu, chẳng hạn như {a,b} lặp lại mười một lần hoặc một dải như file-{1..5000}.md. Thông báo lỗi là Artifact output pattern expands to more than 1024 patterns. Các mẫu thực tế mở rộng thành một vài mẫu.

Hoàn thành

OpenSpec kiểm tra xem đầu ra có tồn tại hay không. Nó không đọc tệp để quyết định artifact đã hoàn thành hay chưa.

Giá trị `generates`	Hoàn thành khi
`proposal.md`	Tệp đó tồn tại.
`specs/*/.md`	Glob khớp với ít nhất một tệp.

`template`

Đường dẫn bắt đầu từ thư mục templates/ của schema. Trong schema review-first:

yaml

template: proposal.md

OpenSpec đọc tệp này:

text

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

OpenSpec cung cấp nội dung của template cho agent làm định dạng đầu ra. Nó không sao chép template vào thư mục thay đổi.

OpenSpec từ chối các đường dẫn tuyệt đối và đường dẫn chứa phân đoạn ...

`requires`

Phụ thuộc: mọi ID trong requires phải đặt tên cho một artifact khác trong cùng schema.
Trạng thái sẵn sàng: một artifact trở nên sẵn sàng sau khi tất cả các phụ thuộc của nó hoàn thành.
Đồ thị không hợp lệ: ID bị thiếu, ID trùng lặp và chu trình phụ thuộc đều khiến kiểm tra hợp lệ thất bại.
Đồng hạng: khi nhiều artifact sẵn sàng, thứ tự của chúng trong artifacts quyết định artifact nào OpenSpec trả về trước.

Các trường apply

apply xác định những gì phải tồn tại trước khi quá trình triển khai bắt đầu.

Trường	Ràng buộc
`requires`	Bắt buộc. Danh sách không rỗng gồm các artifact phải tồn tại trước khi hướng dẫn apply trở nên sẵn sàng.
`tracks`	Đường dẫn tương đối hoặc glob tùy chọn cho các tệp nhiệm vụ Markdown trong thư mục thay đổi. Mặc định: `null`.
`instruction`	Hướng dẫn tùy chọn được gửi đến agent khi apply sẵn sàng. OpenSpec dùng hướng dẫn tích hợp sẵn theo mặc định.

requires của artifact kiểm soát thứ tự lập kế hoạch. apply.requires kiểm soát thời điểm hướng dẫn apply trở nên sẵn sàng.

`tracks`

Đường dẫn bắt đầu từ thư mục thay đổi. Với một thay đổi có tên add-auth, tracks: tasks.md đọc:

text

openspec/changes/add-auth/tasks.md

Một glob như tracks: "**/tasks.md" đọc mọi tệp khớp, chẳng hạn như backend/tasks.md và frontend/tasks.md. OpenSpec kết hợp các nhiệm vụ và tiến độ của chúng. Dùng cùng giá trị cho trường generates của artifact để trạng thái và danh sách theo dõi cùng các tệp. Các giới hạn dấu ngoặc nhọn từ generates (sâu 16 cấp, 1.024 mẫu sau khi mở rộng) cũng áp dụng ở đây.

Apply vẫn ở trạng thái bị chặn nếu không có tệp nào khớp hoặc các tệp khớp không chứa checkbox có văn bản nhiệm vụ. OpenSpec đếm các dạng checkbox sau:

markdown

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

Mọi dấu đánh dấu danh sách Markdown đều hoạt động: -, *, + hoặc một số có tối đa chín chữ số theo sau là . hoặc ). Cho phép có khoảng trắng ở đầu. Phần tasks.md của trang spec-driven định nghĩa định dạng chặt chẽ hơn do schema mặc định tạo ra.

Các tệp được theo dõi quyết định trạng thái apply:

blocked: không có tệp nào khớp hoặc không có tệp đọc được nào chứa checkbox có văn bản nhiệm vụ.
ready: có ít nhất một nhiệm vụ đang chờ hoặc một tệp khớp không thể đọc được trong khi tệp khác cung cấp nhiệm vụ.
all_done: mọi nhiệm vụ được theo dõi đều đã được đánh dấu và mọi tệp khớp đều đã được đọc.

Nếu một tệp khớp không thể đọc được, apply vẫn giữ các nhiệm vụ và tiến độ từ các tệp đọc được nhưng không đánh dấu thay đổi là all_done. Đầu ra JSON của apply xác định từng tệp không khả dụng và lý do.

OpenSpec từ chối các đường dẫn tuyệt đối và đường dẫn chứa phân đoạn ...

Giá trị mặc định của apply

Hành vi	Mặc định
Artifact bắt buộc	Mọi artifact trong schema
Theo dõi tiến độ	Không có tệp được theo dõi
Hướng dẫn cho agent	Hướng dẫn apply tích hợp sẵn

Ví dụ đầy đủ

yaml

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.

Kiểm tra hợp lệ

openspec schema validate <name> kiểm tra:

Kiểu trường và các trường bắt buộc
Đường dẫn tương đối
ID artifact, các phụ thuộc và chu trình
ID trong apply.requires: mỗi ID phải là một artifact trong schema
Các tệp template

Schema có ID apply.requires không xác định sẽ không tải được, vì vậy mọi lệnh sử dụng nó đều báo lỗi.

Kiểm tra hợp lệ sẽ cảnh báo, nhưng không làm thất bại, khi apply.tracks không khớp chính xác với giá trị generates của một artifact nào đó. OpenSpec tìm artifact được theo dõi bằng cách so sánh hai chuỗi đó, vì vậy bất kỳ khác biệt nào cũng khiến nó không thể xác định tệp thuộc về tiến độ của artifact nào. Điều này bao gồm lỗi chính tả như task.md, và cả trường hợp tracks: tasks/main.md so với generates: tasks/*.md, khi glob thực sự tạo ra tệp nhưng các chuỗi vẫn khác nhau. Trong cả hai trường hợp, apply vẫn tiếp tục đọc tệp, nhưng openspec list và openspec status lại đếm tasks.md thay vào đó.

Kiểm tra hợp lệ không phát hiện các lỗi sau:

Lỗi	Điều gì xảy ra
Một trường bị viết sai chính tả, chẳng hạn như `instrution`	OpenSpec bỏ qua trường đó. Kiểm tra hợp lệ không báo lỗi chính tả.
`name` khác với thư mục schema	Kiểm tra hợp lệ thành công. OpenSpec vẫn dùng tên thư mục để tra cứu.

schema.yaml ​

Vị trí ​

Các trường cấp cao nhất ​

Các trường artifact ​

generates ​

Hoàn thành ​

template ​

requires ​

Các trường apply ​

tracks ​

Giá trị mặc định của apply ​

Ví dụ đầy đủ ​

Kiểm tra hợp lệ ​

schema.yaml

Vị trí

Các trường cấp cao nhất

Các trường artifact

`generates`

Hoàn thành

`template`

`requires`

Các trường apply

`tracks`

Giá trị mặc định của apply

Ví dụ đầy đủ

Kiểm tra hợp lệ