schema.yaml

読み取りまたは書き込みを行う、スキーマ定義のすべてのフィールド。

schema.yaml は、ワークフローが作成する計画ファイルを一覧化します。また、それらの順序と実装への引き継ぎも定義します。

場所

プロジェクトのスキーマは openspec/schemas/<name>/ の下に配置されます。

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

OpenSpec はそのディレクトリを3か所でチェックします。最初に一致したものが使用されます。

コピー	ディレクトリ
1. プロジェクト	<project>/openspec/schemas/<name>/
2. ユーザー、macOS および Linux	~/.local/share/openspec/schemas/<name>/
2. ユーザー、Windows	%LOCALAPPDATA%\openspec\schemas\<name>\
3. パッケージ	CLI と一緒にインストールされたスキーマ

XDG_DATA_HOME が設定されている場合、ユーザーディレクトリはすべてのプラットフォームで $XDG_DATA_HOME/openspec/schemas/<name>/ に移動します。

ディレクトリ名は、--schema、config.yaml、および .openspec.yaml で使用される参照キーです。name フィールドがディレクトリ名と異なる場合でも、OpenSpec は参照にディレクトリ名を使用します。

openspec schema which <name> は、アクティブなディレクトリと、そのディレクトリに隠されている低優先度のコピーを出力します。

トップレベルフィールド

フィールド	契約
name	必須。 スキーマ名として保存される空でない文字列。参照には引き続きディレクトリ名が使用されます。
version	必須。 スキーマリビジョンとして保存される正の整数。この値は OpenSpec の動作を変更しません。
description	openspec schemas によって出力されるオプションの文字列。値がない場合、スキーマには説明がありません。
artifacts	必須。 アーティファクトエントリの空でないリスト。
apply	オプションの apply 設定。ブロックがない場合、OpenSpec は apply デフォルトを使用します。

アーティファクトフィールド

artifacts の下の各エントリは、1つの計画ファイルまたはファイルのセットを定義します。

フィールド	契約
id	必須。 依存関係、プロジェクトルール、コマンド、および apply 設定で使用される一意の空でない文字列。
generates	必須。 エージェントに対して、変更フォルダ内でアーティファクトを書き込む場所を示す相対パスまたはグロブ。
description	必須。 エージェントに送信される指示でアーティファクトにラベルを付ける文字列。
template	必須。 スキーマの templates/ フォルダ内でのアーティファクトのフォーマットへの相対パス。
instruction	エージェントに対してどのようなコンテンツを生成するかを伝えるオプションのガイダンス。
requires	最初に完了しなければならないアーティファクト ID のリスト。デフォルト: []。

generates

パスは変更フォルダから始まります。add-auth という名前の変更の場合:

generates: proposal.md

アーティファクトはここに配置されます:

openspec/changes/add-auth/proposal.md

グロブは複数のファイルに一致できます:

generates: specs/**/*.md

これは openspec/changes/add-auth/specs/ 以下の Markdown ファイルに一致します。

OpenSpec は generates で以下のグロブ形式を認識します:

• ワイルドカードと文字クラス: *、?、または [ を含む値（例: specs/**/*.md、review-[ab].md）
• ブレース展開: review-{api,ui}.md のような代替パターン、および file-{1..3}.md のような範囲
• エクストグロブ: @(proposal|design).md、+(proposal|design).md、!(proposal|design).md のようなパターン

リテラルファイル名: 先頭の ! だけではグロブになりません。generates: '!review.md' を使用してそのファイルを指定します。(proposal|design).md のような通常の括弧や review-{api}.md のような単一要素のブレースもリテラルのままです。

OpenSpec は絶対パス、.. セグメントを含むパス、および {a,{b,{c,...}}} のようにブレースや括弧が16レベルを超えて入れ子になったグロブを拒否します。実際のパターンには1つか2つのレベルが必要です。また、{a,b} を11回繰り返した場合や file-{1..5000}.md のような範囲など、ブレースが1,024を超えるパターンに展開されるグロブも拒否します。エラーには Artifact output pattern expands to more than 1024 patterns と表示されます。実際のパターンは数個に展開されます。

完了

OpenSpec は出力が存在するかどうかをチェックします。アーティファクトが完了したかどうかを判断するためにファイルを読み取りません。

generates 値	完了条件
proposal.md	そのファイルが存在する。
specs/**/*.md	グロブが少なくとも1つのファイルに一致する。

template

パスはスキーマの templates/ フォルダから始まります。review-first スキーマの場合:

template: proposal.md

OpenSpec はこのファイルを読み取ります:

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

OpenSpec はテンプレートの内容を出力フォーマットとしてエージェントに提供します。テンプレートを変更フォルダにコピーしません。

OpenSpec は絶対パスと .. セグメントを含むパスを拒否します。

requires

• 依存関係: requires のすべての ID は、同じスキーマ内の別のアーティファクトを参照しなければなりません。
• 準備完了状態: すべての依存関係が完了すると、アーティファクトの準備が整います。
• 無効なグラフ: 不足している ID、重複した ID、および依存関係のサイクルは検証に失敗します。
• 同順位: 複数のアーティファクトの準備が整った場合、artifacts での順序によって、OpenSpec が最初に返すものが決まります。

Apply フィールド

apply は、実装を開始する前に何が存在しなければならないかを定義します。

フィールド	契約
requires	必須。 apply 指示が準備完了になる前に存在しなければならないアーティファクトの空でないリスト。
tracks	変更フォルダ内の Markdown タスクファイルのためのオプションの相対パスまたはグロブ。デフォルト: null。
instruction	apply の準備が整ったときにエージェントに送信されるオプションのガイダンス。OpenSpec はデフォルトで組み込みのガイダンスを使用します。

アーティファクトの requires は計画順序を制御します。apply.requires は apply 指示が準備完了になるタイミングを制御します。

tracks

パスは変更フォルダから始まります。add-auth という名前の変更の場合、tracks: tasks.md は次を読み取ります:

openspec/changes/add-auth/tasks.md

tracks: "**/tasks.md" のようなグロブは、backend/tasks.md や frontend/tasks.md など、一致するすべてのファイルを読み取ります。OpenSpec はそれらのタスクと進捗を結合します。ステータスとリストが同じファイルを追跡できるように、アーティファクトの generates フィールドに同じ値を使用してください。generates からのブレース制限（16レベル、1,024個の展開パターン）もここに適用されます。

ファイルが一致しない場合、または一致したファイルにタスクテキスト付きのチェックボックスが含まれていない場合、apply はブロックされたままです。OpenSpec は以下のチェックボックス形式をカウントします:

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

任意の Markdown リストマーカーが機能します: -、*、+、または最大9桁の数字に . または ) を付けたもの。先行スペースが許可されています。spec-driven ページの tasks.md セクション は、デフォルトスキーマで生成されるより厳格なフォーマットを定義しています。

追跡されたファイルが apply 状態を駆動します:

• blocked: ファイルが一致しないか、読み取り可能なファイルにタスクテキスト付きのチェックボックスがない。
• ready: 少なくとも1つのタスクが保留中であるか、別のファイルがタスクを提供している間に一致したファイルを読み取れなかった。
• all_done: 追跡されたすべてのタスクがチェックされており、すべての一致したファイルが読み取られた。

一致したファイルを読み取れない場合、apply は読み取り可能なファイルからのタスクと進捗を保持しますが、変更を all_done としてマークしません。Apply JSON 出力 は、利用できない各ファイルとその理由を特定します。

OpenSpec は絶対パスと .. セグメントを含むパスを拒否します。

Apply デフォルト

動作	デフォルト
必須アーティファクト	スキーマ内のすべてのアーティファクト
進捗追跡	追跡ファイルなし
エージェントガイダンス	組み込みの 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、依存関係、およびサイクル
• apply.requires ID: それぞれがスキーマ内のアーティファクトでなければならない
• テンプレートファイル

未知の apply.requires ID を持つスキーマは読み込まれないため、それを使用するすべてのコマンドがエラーを報告します。

apply.tracks がいずれかのアーティファクトの generates 値と完全に等しくない場合、検証は失敗せずに警告します。OpenSpec はそれら2つの文字列を比較することで追跡されたアーティファクトを見つけるため、それ以外のものはファイルがどのアーティファクトの進捗に属するかを判断できなくなります。これには task.md のような誤字や、グロブがファイルを生成するものの文字列が異なる tracks: tasks/main.md 対 generates: tasks/*.md も含まれます。Apply はどちらの場合もファイルを読み取り続けますが、openspec list と openspec status は代わりに tasks.md をカウントします。

検証はこれらの間違いを捕捉しません:

間違い	発生すること
フィールドのスペルミス（例: instrution）	OpenSpec はそれを無視します。検証はスペルミスを報告しません。
name がスキーマディレクトリと異なる	検証は合格します。OpenSpec は参照にディレクトリ名を使用します。