x- プレフィックス付き注釈キーワードを運びます。JSON Schema 検証器は draft-07 §6 に従って未知の x- キーワードを無視するため、これらのキーの追加は任意の準拠検証器とワイヤー互換です。
このページはそれらの注釈の正準リファレンスです。Codegen コンシューマー（TypeScript / Python / Go 型ジェネレーター）、ストーリーボードランナー、AdCP SDK ファミリーはこれらの注釈をプログラム的に読みます。検証者はそれらを読んでもよい（MAY）が、それらが記述する規範的動作は security.mdx の該当セクションまたはフィールド自身の説明でも文書化されています。
x-status
スキーマまたはプロパティを 実験的 — コアプロトコルの一部だがまだ凍結されていない — としてマークします。実験的サーフェスを実装するセラーは、get_adcp_capabilities の experimental_features に機能 id を宣言します。完全な卒業ポリシーについては 実験的ステータス を参照。
"experimental"。キーワードは安定サーフェスでは省略されます。
x-adcp-validation
構造化された規範的制約を散文の説明から機械可読な形状に引き上げます。ストーリーボードランナーと SDK 検証器は構造化されたルールを消費します。codegen コンシューマーは注釈を無視して人間の説明を読めます。
このキーワードは、ストーリーボードランナーが英語をパースして強制できない「…のとき存在しなければならない（MUST）」や「…のホストと等しくなければならない（MUST）」句を現在説明が運ぶフィールドに最も有用です。
形状
サブキー
適合性
- 検証器は前方互換性のため未知のサブキーを無視しなければならない（MUST）（スキーマがマイナーリリースで新しいエントリを追加しうる）。
- ストーリーボードランナーは
required_when、schema_required_when、verifier_constraintsを消費してリリースごとにテストケースを生成する。まだサブキーを認識しないランナーはそれをスキップし「認識されない検証ルール」警告を発しなければならない（MUST）。 - Codegen コンシューマー（TypeScript / Python / Go 型ジェネレーター）は
x-adcp-validation.specを@seeJSDoc リンクとしてサーフェスしてもよい（MAY）が、それ以外は注釈を不透明として扱う。
現在の使用
代表的な使用:
JSON Schema によってネイティブに既に強制され、移行から除外:
adcp.idempotency— 判別されたoneOfが、サポートブランチでreplay_ttl_secondsを既に要求し、非サポートブランチでそれを禁止する。webhook_signing.algorithms— 各アイテムのenum: ["ed25519", "ecdsa-p256-sha256"]が既に許可リストを強制する。
x-adcp-open-payload
SDK ジェネレーターにオープンエンドに見えるフィールドを分類します。注釈は文書的で非検証です。フィールドの JSON Schema が依然としてワイヤー検証を制御します。
許可されるオーサリング値:
false は将来の構造化だが拡張許容マーカーのために予約されています。ソーススキーマは、リポジトリが少なくとも 1 つの正準使用サイトとその値のジェネレーターコントラクトを定義するまで、x-adcp-open-payload: false を設定してはなりません（MUST NOT）。
混合フィールドについては、注釈は object または decoded-JSON ペイロードアームにのみ適用されます。スカラーアームは依然として宣言されたスキーマに従います。例えば、上流の記録されたボディは、コンテンツタイプが JSON 形状のとき decoded JSON オブジェクトで、それ以外は文字列でありうる。x-adcp-open-payload: true は、文字列アームをオブジェクトモデルとしてではなく、decoded JSON ペイロードを意図的にオープンとしてマークする。
x-adcp-hoist
ソーススキーマを正準に共有される型としてマークするビルド時ディレクティブ。スキーマバンドラーは、すべてのインライン出現を単一のルート $defs エントリに引き上げ、インラインコピーを $ref ポインターに置き換える。ディレクティブ自体はバンドル出力から除去される。ワイヤーに無関係 — 検証器はそれを無視しなければならず（MUST）（draft-07 §6 の未知キーワードセマンティクス）、準拠コンシューマーはバンドルされたアーティファクトでそれを観測すべきではない（SHOULD NOT）。
なぜ複雑なオブジェクトにオプトインか
純粋な enum は自動的に引き上げられます（hoistDuplicateInlineEnums を参照）。なぜなら 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 を参照。
適合性
- 検証器は draft-07 §6 に従って
x-adcp-hoistを無視しなければならない（MUST）（未知キーワードは許容される）。ディレクティブはワイヤーセマンティクスを持たない。 - ソースツリーコンシューマー（バンドルされたアーティファクトではなく
static/schemas/source/...を直接デリファレンスするサードパーティ）は、x-adcp-hoist: trueを no-op 注釈として扱わなければならない（MUST）。スキーマのコンテンツがコントラクト。 scripts/build-schemas.cjs以外のバンドラーは、ディレクティブを尊重しても無視してもよい（MAY）。それを無視するバンドラーは、重複排除されていないインラインコピーを持つワイヤー互換バンドルを生成する。
履歴
将来の拡張
新しいx-adcp-* キーワードはマイナーリリースで追加されます。コンシューマーはエラーなしに未知の x- キーワードを許容しなければなりません（MUST）。慣例は x-adcp- 名前空間を予約します。ベンダー固有またはデプロイ固有の注釈は、衝突を避けるためベンダー固有のプレフィックス（例: x-yourorg-）を使うべきです（SHOULD）。