Metadata của thay đổi (.openspec.yaml)

Các trường được hỗ trợ và quy tắc xác thực cho metadata được lưu cùng mỗi thay đổi.

Vị trí

Mỗi thay đổi lưu metadata của mình tại openspec/changes/<change-name>/.openspec.yaml, ngay cạnh các artifact của nó. Khi tạo một thay đổi, tệp được ghi với schema và created đã được điền sẵn.

Các trường

Khóa	Kiểu	Bắt buộc	Tác dụng
schema	string	Có	Schema quy trình làm việc mà thay đổi này tuân theo
created	string, YYYY-MM-DD	Không	Ghi lại ngày thay đổi được tạo ra
goal	string	Không	Ghi lại mục tiêu mà thay đổi hướng tới
affected_areas	danh sách string	Không	Ghi lại các khu vực mà thay đổi dự kiến sẽ tác động
initiative	map gồm store và id	Không	Ghi lại initiative mà thay đổi này thuộc về
skip_specs	boolean	Không	Khai báo thay đổi không tạo spec delta nào, do đó không có delta vẫn hợp lệ
retire_capabilities	boolean	Không	Cho phép archive xóa capability mà thay đổi này đã làm rỗng

schema

Schema quy trình làm việc mà thay đổi này tuân theo. Giá trị này được đặt khi thay đổi được tạo và có độ ưu tiên cao hơn cấu hình dự án, nên thay đổi vẫn giữ schema của mình ngay cả khi openspec/config.yaml thay đổi sau đó. Chạy openspec schemas để liệt kê các tên schema khả dụng.

initiative

Initiative mà thay đổi này thuộc về, dưới dạng một store id và một initiative id, cả hai đều viết theo kebab-case:

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

Các khóa khác ngoài store và id sẽ bị từ chối. Hiện chưa có lệnh nào đọc liên kết này.

skip_specs

Khai báo rằng thay đổi một cách chủ ý không tạo ra spec delta nào: là một thay đổi thuần refactor, tooling, hoặc tài liệu. Khi được đặt, xác thực chấp nhận không có delta nào, và các artifact lẽ ra sẽ tạo ra tệp spec được tính là hoàn tất. Đặt nó trong khi vẫn còn tệp spec dưới specs/ là một lỗi xác thực.

retire_capabilities

Cho phép archive loại bỏ một capability. Khi các delta REMOVED của thay đổi này lấy đi yêu cầu cuối cùng mà một capability có, archive sẽ xóa spec chính của capability đó thay vì dừng lại. Flag này tồn tại vì việc xóa chỉ có thể khôi phục từ git, nên nó vẫn là quyết định của người viết.

Khóa mở rộng

Một khóa cấp cao nhất bắt đầu bằng x- viết thường là của bạn, dành cho dữ liệu mà công cụ khác hoặc nhóm của bạn lưu bên cạnh thay đổi, chẳng hạn như một tracker id hoặc người phụ trách:

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

• Tên: tiền tố x- viết thường theo sau bởi ít nhất một ký tự, không có khoảng trắng ở bất kỳ đâu. Bất kỳ kiểu chữ hay cách viết nào sau tiền tố đều được chấp nhận, nên x-jiraKey và x-trackerID đều đạt yêu cầu. X-Tracker, một x- trống, và x- tracker thì không, và sẽ bị báo là các khóa không xác định.
• Giá trị: bất kỳ giá trị YAML nào. OpenSpec không đọc hay xác thực nó, và nó không làm thay đổi hành vi nào.
• Phạm vi: chỉ ở cấp cao nhất. Một khóa x- bên trong initiative vẫn bị từ chối, giống như bất kỳ khóa nào khác ở đó.
• Xác thực: các khóa mở rộng không bao giờ bị báo là không xác định, nên openspec validate --strict vẫn vượt qua với một thay đổi có chứa chúng.
• Archive: tệp được di chuyển cùng với thay đổi nguyên vẹn, kể cả các khóa mở rộng.

Ví dụ

Một tệp .openspec.yaml đã được điền:

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

Xác thực

Tệp được xác thực mỗi khi một lệnh ghi hoặc đọc nó. Một thao tác ghi không qua được xác thực sẽ ném lỗi và không ghi gì cả. Việc đọc một tệp hiện có sẽ thất bại nếu YAML không hợp lệ, nếu một trường vi phạm ràng buộc của nó, hoặc nếu tên schema không khả dụng. Tệp bị thiếu không phải là lỗi, và thay đổi được coi là không có metadata.

Không giống config.yaml, các giá trị sai không bao giờ bị loại bỏ kèm một cảnh báo. Một lỗi metadata sẽ dừng câu lệnh.

• Khóa cấp cao nhất không xác định: OpenSpec bỏ qua chúng. status, instructions, validate, và archive báo rằng chúng không có tác dụng. Đầu ra JSON mang theo cảnh báo trong kết quả có cấu trúc của nó. Khóa mở rộng không phải là khóa không xác định và không bao giờ bị báo.
• Xác thực nghiêm ngặt: openspec validate --strict coi một cảnh báo khóa không xác định là thất bại. Một thay đổi mà các khóa dư thừa duy nhất là các khóa mở rộng sẽ vượt qua.