> ## Documentation Index > Fetch the complete documentation index at: https://adcp-docs-ja.pier1.co.jp/llms.txt > Use this file to discover all available pages before exploring further. # スキーマ拡張 > AdCP 固有の `x-` プレフィックス付きスキーマ注釈のリファレンス。 AdCP スキーマは、JSON Schema 語彙を補完するいくつかの `x-` プレフィックス付き注釈キーワードを運びます。JSON Schema 検証器は [draft-07 §6](https://json-schema.org/draft-07/schema) に従って未知の `x-` キーワードを無視するため、これらのキーの追加は任意の準拠検証器とワイヤー互換です。 このページはそれらの注釈の正準リファレンスです。Codegen コンシューマー（TypeScript / Python / Go 型ジェネレーター）、ストーリーボードランナー、AdCP SDK ファミリーはこれらの注釈をプログラム的に読みます。検証者はそれらを読んでもよい（MAY）が、それらが記述する規範的動作は [security.mdx](/docs/building/by-layer/L1/security) の該当セクションまたはフィールド自身の説明でも文書化されています。 ## `x-status` スキーマまたはプロパティを **実験的** — コアプロトコルの一部だがまだ凍結されていない — としてマークします。実験的サーフェスを実装するセラーは、`get_adcp_capabilities` の `experimental_features` に機能 id を宣言します。完全な卒業ポリシーについては [実験的ステータス](/docs/reference/experimental-status) を参照。 ```jsonc theme={null} "trusted_match": { "type": "object", "x-status": "experimental", "description": "Trusted Match Protocol support..." } ``` 許可される値: `"experimental"`。キーワードは安定サーフェスでは省略されます。 ## `x-adcp-validation` 構造化された規範的制約を散文の説明から機械可読な形状に引き上げます。ストーリーボードランナーと SDK 検証器は構造化されたルールを消費します。codegen コンシューマーは注釈を無視して人間の説明を読めます。 このキーワードは、ストーリーボードランナーが英語をパースして強制できない「...のとき存在しなければならない（MUST）」や「...のホストと等しくなければならない（MUST）」句を現在説明が運ぶフィールドに最も有用です。 ### 形状 ```jsonc theme={null} "some_field": { "type": "string", "format": "uri", "description": "Brief one or two sentences for codegen JSDoc; full constraints live in x-adcp-validation and the linked spec.", "x-adcp-validation": { "trust_root": true, "required_when": { "any_of": [ ... ] }, "schema_required_when": { ... }, "verifier_constraints": { ... }, "distinct_from": "other.field.path", "spec": "docs/.../section.mdx#anchor" } } ``` ### サブキー | Key | Type | Purpose | | ---------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `trust_root` | boolean | フィールドが署名検証に負荷を担う。検証者は権威的として扱わなければならない（MUST）。 | | `required_when` | `any_of` / `all_of` をラップするオブジェクト | ストーリーボード強制の required-when ルール（3.x）。オブジェクトは `any_of`（OR 結合）または `all_of`（AND 結合）のいずれか正確に 1 つを持ち、それぞれがリーフ条件の配列を含む。各リーフは次のいずれか: `{ "field": "...", "non_empty": true }`、`{ "field": "...", "equals": }`、`{ "field": "...", "any_subfield_present": true }`。ラップするオブジェクトは JSON Schema の `anyOf`/`allOf` の先例をミラーし、ツール読み取り者が馴染みのある boolean 結合子セマンティクスを再利用できる。素の配列は受け入れられない — 常にラップする。 | | `schema_required_when` | condition | ルールがストーリーボード強制からスキーマ必須に昇格するとき。通常、`any_item_matches_pattern` 経由でバージョンパターンに一致する `adcp.supported_versions` にキー付けされる（例: 4.0 切り替えと任意の 4.x パッチの `"^4\\."`）。 | | `forbidden_when` | `any_of` / `all_of` をラップするオブジェクト | `required_when` の逆。ラップされた条件が成立するとき、フィールドは欠如していなければならない（型によっては `false`/空）（MUST）。`required_when` と同じリーフ形状。存在が別の姿勢と相互排他的なフィールドに使う。 | | `disjoint_with` | string（ドット付きパス）またはドット付きパスの配列 | アイテムレベルの相互排他: このフィールドの配列のどの値も、名前付き配列のいずれにも現れてはならない（MAY NOT）。ストーリーボードランナーは各について集合の非交差性をアサートする。例: `request_signing.warn_for` は `disjoint_with: "request_signing.required_for"` を運ぶ。なぜなら操作は一方または他方にありえるが、決して両方ではないから。 | | `subset_of` | string（ドット付きパス） | アイテムレベルの部分集合制約: このフィールドの配列のすべての値は、名前付き配列にも現れなければならない（MUST）。例: `request_signing.required_for` は `subset_of: "request_signing.supported_for"` を運ぶ — 操作はサポートされずに必須にはなれない。 | | `verifier_constraints` | object | 上記の構造化サブキーに適合しない検証者側ルールの自由形式のキー値マップ。キーは規範的（例: `agent_url_match: "byte_equal"`）。ストーリーボードランナーはこれらをテストベクターに対して強制する。適合するとき構造化サブキー（`required_when`、`forbidden_when`、`disjoint_with`、`subset_of`）を優先。一般化しない一回限りのルールにのみ `verifier_constraints` に手を伸ばす。 | | `distinct_from` | string（ドット付きパス） | 名前の混同を防ぐため、類似の形状だが異なるセマンティクスを持つ別のフィールドを名指しする（例: `identity.brand_json_url` は `sponsored_intelligence.brand_url` と別）。検証者は一方を他方の代わりにしてはならない（MUST NOT）。 | | `spec` | string（アンカー付き相対パス） | フィールドの完全なセマンティクスを定義するドキュメントの規範的セクションへのポインター。他のサブキーが存在するとき常に必須。 | ### 適合性 * 検証器は前方互換性のため未知のサブキーを無視しなければならない（MUST）（スキーマがマイナーリリースで新しいエントリを追加しうる）。 * ストーリーボードランナーは `required_when`、`schema_required_when`、`verifier_constraints` を消費してリリースごとにテストケースを生成する。まだサブキーを認識しないランナーはそれをスキップし「認識されない検証ルール」警告を発しなければならない（MUST）。 * Codegen コンシューマー（TypeScript / Python / Go 型ジェネレーター）は `x-adcp-validation.spec` を `@see` JSDoc リンクとしてサーフェスしてもよい（MAY）が、それ以外は注釈を不透明として扱う。 ### 現在の使用 代表的な使用: | Field | Sub-keys used | Rule | | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `identity.brand_json_url` | `trust_root`、`required_when`、`schema_required_when`、`verifier_constraints`、`distinct_from` | 署名鍵ディスカバリーのための trust-root ポインター。署名姿勢に結びついた required-when。4.0 でスキーマ必須。`sponsored_intelligence.brand_url` と別。[security.mdx §エージェントの署名鍵の発見](/docs/building/by-layer/L1/security) を参照。 | | `identity.key_origins` | `verifier_constraints`（`purpose_anchoring`） | リストされたすべての purpose は、レスポンスの他の場所で宣言された対応する署名姿勢を持たなければならない（MUST）。クロスフィールドルール。[security.mdx §オリジン分離](/docs/building/by-layer/L1/security) を参照。 | | `request_signing.required_for` | `subset_of` | リストされたすべての操作は `supported_for` にも現れなければならない（MUST） — 操作はサポートされずに必須にはなれない。 | | `request_signing.warn_for` | `disjoint_with`、`subset_of` | 操作は `warn_for` と `required_for` の両方に現れてはならない（MUST NOT）。リストされたすべての操作は `supported_for` にも現れなければならない（MUST）。 | | `webhook_signing.supported` | `verifier_constraints`（`must_equal_when`） | セラーが変更 webhook の発出をアドバタイズするとき（`media_buy.reporting_delivery_methods` が `webhook` を含む、または `media_buy.content_standards.supports_webhook_delivery: true`）、`supported` は `true` でなければならない（MUST）。ダウングレードベクターを閉じる。 | | `wholesale_feed_webhooks.event_types` | `verifier_constraints`（`wholesale_feed_webhook_capability_consistency`） | `product.*` イベントタイプはホールセール `get_products` を必要とする。`signal.*` イベントタイプはホールセール `get_signals` を必要とする。`wholesale_feed.bulk_change` は少なくとも 1 つの宣言されたホールセール修復パスを必要とし、修復可能なフィードファミリーのみを名指ししなければならない。 | | `get_products.wholesale_feed_version` / `get_signals.wholesale_feed_version` | `verifier_constraints`（`required_for_wholesale_request`） | バージョントークンはホールセール読み取りレスポンスで必須だが、共有レスポンススキーマはレスポンスボディだけからリクエストの `buying_mode` / `discovery_mode` を推論できない。 | JSON Schema によってネイティブに既に強制され、移行から除外: * **`adcp.idempotency`** — 判別された `oneOf` が、サポートブランチで `replay_ttl_seconds` を既に要求し、非サポートブランチでそれを禁止する。 * **`webhook_signing.algorithms`** — 各アイテムの `enum: ["ed25519", "ecdsa-p256-sha256"]` が既に許可リストを強制する。 移行履歴は [adcontextprotocol/adcp#3827](https://github.com/adcontextprotocol/adcp/issues/3827) で追跡。 ## `x-adcp-open-payload` SDK ジェネレーターにオープンエンドに見えるフィールドを分類します。注釈は文書的で非検証です。フィールドの JSON Schema が依然としてワイヤー検証を制御します。 許可されるオーサリング値: | Value | Meaning for schema authors and generators | | ------ | ---------------------------------------------------------------------------------------------------------------------------------- | | `true` | フィールドは意図的に自由形式のペイロードデータを運ぶ。ジェネレーターは object/decoded-JSON アームを警告なしに `Record` または別の汎用 JSON コンテナとしてモデル化してもよい（MAY）。 | | 省略 | 未分類。ジェネレーターとスキーマリントルールは `true` も `false` も推論すべきではない（SHOULD NOT）。レビュー中に注釈のない `additionalProperties: true` オブジェクトフィールドで警告してもよい（MAY）。 | `false` は将来の構造化だが拡張許容マーカーのために予約されています。ソーススキーマは、リポジトリが少なくとも 1 つの正準使用サイトとその値のジェネレーターコントラクトを定義するまで、`x-adcp-open-payload: false` を設定してはなりません（MUST NOT）。 混合フィールドについては、注釈は object または decoded-JSON ペイロードアームにのみ適用されます。スカラーアームは依然として宣言されたスキーマに従います。例えば、上流の記録されたボディは、コンテンツタイプが JSON 形状のとき decoded JSON オブジェクトで、それ以外は文字列でありうる。`x-adcp-open-payload: true` は、文字列アームをオブジェクトモデルとしてではなく、decoded JSON ペイロードを意図的にオープンとしてマークする。 ```jsonc theme={null} "breakdown": { "type": "object", "x-adcp-open-payload": true, "additionalProperties": true } ``` レガシーまたはまだ分類されていないフィールドには省略を使う。「閉じている」を意味するために省略を使わない。 ## `x-adcp-hoist` ソーススキーマを正準に共有される型としてマークするビルド時ディレクティブ。スキーマバンドラーは、すべてのインライン出現を単一のルート `$defs` エントリに引き上げ、インラインコピーを `$ref` ポインターに置き換える。ディレクティブ自体はバンドル出力から除去される。ワイヤーに無関係 — 検証器はそれを無視しなければならず（MUST）（draft-07 §6 の未知キーワードセマンティクス）、準拠コンシューマーはバンドルされたアーティファクトでそれを観測すべきではない（SHOULD NOT）。 ```jsonc theme={null} { "$id": "/schemas/core/price-block.json", "title": "Price Block", "x-adcp-hoist": true, "type": "object", "properties": { "cpm": { "type": "number" }, "currency": { "type": "string" } } } ``` ### なぜ複雑なオブジェクトにオプトインか 純粋な enum は自動的に引き上げられます（[`hoistDuplicateInlineEnums`](https://github.com/adcontextprotocol/adcp/pull/3170) を参照）。なぜなら 2 つの構造的に同一な enum のマージはセマンティクス保存だからです。複雑なオブジェクトは異なります — 構造的同一性 ≠ 意味的同一性。`BriefAsset`（提案されたクリエイティブ仕様）と `VASTAsset`（配信された動画クリエイティブ）は現在フィールドを共有しますが、異なるライフサイクル概念を表します。それらを自動マージすると、ソーススキーマが表現しないクロスツール結合が生まれ、SDK がマージされた型に対して codegen したらほどくのが難しくなります。`x-adcp-hoist` は共有か分割かの決定をスキーマごとに意図的にします。 ### バンドラーの動作 * **任意の出現回数（≥1）で引き上げる。** ディレクティブは意図 — 「これは正準な名前付き型」 — を宣言するため、後で 2 番目の参照を追加しても codegen サーフェスは決して変わらない。 * **`title` が必須。** タイトルの欠如または空 → ビルド時エラー。ディレクティブは意図的であることが意図される。 * **同じタイトル + 異なる形状はビルド時エラー。** 同じ `title` だが異なるフィールドで作られた 2 つのマークされたスキーマは、そうでなければ一方を `Foo2` に黙ってサフィックス付けし、ディレクティブの「正準名」保証を無効にする。 * **既存の `$defs` キーとの衝突はサフィックス付けされる**（`PriceBlock2`）。純粋 enum 引き上げが使う慣例に一致。 * **バンドル出力から除去される** — 正準 `$defs` エントリからも、既存の `$defs` ブロック内に書かれた任意の迷子マーカーからも。 ### SDK / codegen への影響 以前インライン化されたソーススキーマに `x-adcp-hoist` を追加することはワイヤー互換（バンドルされたスキーマは依然として同じペイロードを検証する）ですが、codegen 形状の変更です: 以前匿名のインライン型（しばしば `Foo1`、`Foo2`、…）を発した TypeScript / Python / Go 型ジェネレーターは、今や単一の名前付き型を発します。SDK 採用者は独自の非推奨ポリシーに従ってリネームエイリアスを維持します — クライアント側のリネーム/エイリアス追跡については [adcp-client#942](https://github.com/adcontextprotocol/adcp-client/issues/942) を参照。 ### 適合性 * 検証器は draft-07 §6 に従って `x-adcp-hoist` を無視しなければならない（MUST）（未知キーワードは許容される）。ディレクティブはワイヤーセマンティクスを持たない。 * ソースツリーコンシューマー（バンドルされたアーティファクトではなく `static/schemas/source/...` を直接デリファレンスするサードパーティ）は、`x-adcp-hoist: true` を no-op 注釈として扱わなければならない（MUST）。スキーマのコンテンツがコントラクト。 * `scripts/build-schemas.cjs` 以外のバンドラーは、ディレクティブを尊重しても無視してもよい（MAY）。それを無視するバンドラーは、重複排除されていないインラインコピーを持つワイヤー互換バンドルを生成する。 ### 履歴 * [#4557](https://github.com/adcontextprotocol/adcp/issues/4557) で導入。[#3145](https://github.com/adcontextprotocol/adcp/issues/3145) フェーズ 2 の後継。 ## 将来の拡張 新しい `x-adcp-*` キーワードはマイナーリリースで追加されます。コンシューマーはエラーなしに未知の `x-` キーワードを許容しなければなりません（MUST）。慣例は `x-adcp-` 名前空間を予約します。ベンダー固有またはデプロイ固有の注釈は、衝突を避けるためベンダー固有のプレフィックス（例: `x-yourorg-`）を使うべきです（SHOULD）。