AdCP — Template Format IDs

テンプレートフォーマットにより、単一のフォーマット定義で、バリアントごとに個別のフォーマット定義を作らずに、複数のディメンションまたはデュレーションのバリアントをサポートできます。これは、パブリッシャーが多数の類似バリアントをサポートする際のフォーマット爆発を排除します。

課題: フォーマット爆発

テンプレートフォーマットがないと、各ディメンションバリアントに個別のフォーマット定義と format_id が必要です:

{"format_id": {"agent_url": "...", "id": "display_300x250"}}
{"format_id": {"agent_url": "...", "id": "display_300x600"}}
{"format_id": {"agent_url": "...", "id": "display_728x90"}}
{"format_id": {"agent_url": "...", "id": "display_970x250"}}
// ... 50+ more sizes

50 のプレースメントサイズを持つパブリッシャー → 作成、保守、文書化する 50 の個別フォーマット定義。

解決策: パラメータ付きテンプレートフォーマット

単一のテンプレートフォーマット定義（display_static）が format_id オブジェクトでディメンションフィールドを受け入れ、クリエイティブが正確なディメンションを指定できるようにします。

フォーマットタイプと format_id

2 種類のフォーマット定義があり、3 種類の format_id を生成します:

フォーマット定義

具体フォーマット - フォーマット定義に固定のディメンション
- 明示的なディメンションを持つ renders 配列を持つ
- 例: display_300x250 は常に 300×250px を意味する
- パラメータを受け入れられない
テンプレートフォーマット - format_id でパラメータを受け入れる
- 受け入れるパラメータを列挙する accepts_parameters 配列を持つ
- 例: display_static は任意のディメンションになれる
- パラメータありでもなしでも使える

format_id の種類

具体 format_id - 具体フォーマットを参照
- 例: {id: "display_300x250"}
- パラメータなし（受け入れない）
テンプレート format_id - パラメータなしでテンプレートフォーマットを参照
- 例: {id: "display_static"}
- 任意のディメンションを受け入れるためにプレースメントで使う
パラメータ付き format_id - パラメータ付きのテンプレートフォーマット
- 例: {id: "display_static", width: 300, height: 250}
- 正確なディメンション（ピクセル）を指定するためにクリエイティブで使う

テンプレートフォーマット定義

パラメータを受け入れるフォーマット定義:

{
  "format_id": {
    "agent_url": "https://creative.adcontextprotocol.org"
    "id": "display_static"
  }
  "name": "Static Display Banner"
  "type": "display"
  "accepts_parameters": ["dimensions"]
  "renders": [
    {
      "role": "primary"
      "parameters_from_format_id": true
    }
  ]
  "assets": [
    {
      "item_type": "individual"
      "asset_id": "banner_image"
      "asset_type": "image"
      "required": true
      "requirements": {
        "parameters_from_format_id": true
      }
    }
    {
      "item_type": "individual"
      "asset_id": "clickthrough_url"
      "asset_type": "url"
      "required": true
    }
  ]
}

主なフィールド:

accepts_parameters: ["dimensions"] - フォーマットが format_id でディメンション（ピクセルの width/height）を受け入れる
renders[].parameters_from_format_id: true - レンダーパラメータが format_id に由来する
requirements.parameters_from_format_id: true - アセットパラメータが format_id と一致しなければならない

パラメータ付き format_id（クリエイティブマニフェスト）

クリエイティブは、テンプレートフォーマットを使うために format_id で正確なディメンションを指定します:

{
  "format_id": {
    "agent_url": "https://creative.adcontextprotocol.org"
    "id": "display_static"
    "width": 300
    "height": 250
  }
  "assets": {
    "banner_image": {
      "asset_type": "image"
      "url": "https://cdn.example.com/banner-300x250.png"
      "width": 300
      "height": 250
    }
    "clickthrough_url": {
      "asset_type": "url"
      "url": "https://example.com/landing"
    }
  }
}

この format_id はパラメータ付きです: 同じディメンションは常に同じ format_id オブジェクトを生成し、重複排除とキャッシュを可能にします。

プレースメントの制約

重要: セールスエージェントは、プレースメントで常にパラメータ付きの format_id（特定のディメンション/デュレーション付き）を返さなければなりません（MUST）。パラメータなしのテンプレート format_id は、list_creative_formats() のフォーマット定義でのみ使われます。パブリッシャーは、サポートするすべてのバリアントを列挙して、サポートするディメンションを指定します:

{
  "kind": "seller_inline",
  "placement_id": "homepage_banner",
  "name": "Homepage Banner",
  "mode": "targetable",
  "format_ids": [
    {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "display_static",
      "width": 300,
      "height": 250
    },
    {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "display_static",
      "width": 728,
      "height": 90
    }
  ]
}

検証: クリエイティブの format_id は、プレースメントのパラメータ付き format_id の一つと正確に一致しなければなりません。 プレースメントでパラメータ付きのみである理由:

バイヤーはどのディメンションが正確にサポートされるかを知る必要がある
何が受け入れられるかについて曖昧さがない
クリエイティブ提出時に明確な検証を可能にする
パラメータなしのテンプレート format_id は list_creative_formats() を介したフォーマット発見のためだけのもの

メリット

✅ スケーラビリティ - 1 つのテンプレートフォーマットが無制限のディメンションバリアントをサポート ✅ 予測可能 - 同じディメンション = 同じ format_id（キャッシュ/重複排除を可能にする） ✅ 自己完結 - クリエイティブが format_id を介してフォーマットを完全に指定する ✅ ポータブル - 300×250 のクリエイティブは 300×250 を受け入れる任意のプレースメントで機能する ✅ パブリッシャーの制御 - プレースメントが正確なディメンション制約を指定する ✅ 型安全 - width/height はエンコードされた文字列ではなく数値 ✅ 後方互換 - 具体（非テンプレート）フォーマットは変更なしで機能する

format_id のフィールド

ビジュアルフォーマット（ディスプレイ、DOOH、ネイティブ）

フィールド:

width（integer、最小: 1） - ピクセル単位の幅
height（integer、最小: 1） - ピクセル単位の高さ

例:

{
  "agent_url": "https://creative.adcontextprotocol.org"
  "id": "display_static"
  "width": 300
  "height": 250
}

時間ベースフォーマット（動画、音声）

フィールド:

duration_ms（number、最小: 1） - ミリ秒単位のデュレーション

例:

{
  "agent_url": "https://creative.adcontextprotocol.org"
  "id": "video_hosted"
  "duration_ms": 30000
}

組み合わせ（ディメンション付き動画）

フィールド:

width、height（integer） - ピクセル単位の動画フレームディメンション
duration_ms（number） - ミリ秒単位の動画の長さ

例:

{
  "agent_url": "https://creative.adcontextprotocol.org"
  "id": "video_hosted"
  "width": 1920
  "height": 1080
  "duration_ms": 30000
}

フォーマット定義のパターン

ディスプレイフォーマット（柔軟なディメンション）

{
  "format_id": {
    "agent_url": "https://creative.adcontextprotocol.org"
    "id": "display_static"
  }
  "name": "Static Display Banner"
  "type": "display"
  "accepts_parameters": ["dimensions"]
  "renders": null
  "assets": [...]
}

動画フォーマット（柔軟なデュレーション）

{
  "format_id": {
    "agent_url": "https://creative.adcontextprotocol.org"
    "id": "video_hosted"
  }
  "name": "Hosted Video"
  "type": "video"
  "accepts_parameters": ["duration"]
  "renders": null
  "assets": [...]
}

DOOH フォーマット（ピクセルディメンション）

{
  "format_id": {
    "agent_url": "https://creative.adcontextprotocol.org"
    "id": "dooh_static"
  }
  "name": "DOOH Static Display"
  "type": "dooh"
  "accepts_parameters": ["dimensions"]
  "renders": null
  "assets": [...]
}

ピクセルディメンション付きのクリエイティブ:

{
  "format_id": {
    "agent_url": "https://creative.adcontextprotocol.org"
    "id": "dooh_static"
    "width": 1920
    "height": 560
  }
  "assets": {...}
}

注: すべてのディメンションはピクセル単位です。物理的なスクリーンディメンション（例: 48 フィート × 14 フィートのビルボード）は、フォーマット仕様ではなくプレースメントメタデータです。

出力フォーマットを持つ生成系フォーマット

生成系フォーマットは、生成できる出力フォーマットを指定します: オプション 1: 特定のディメンションを生成

{
  "format_id": {"agent_url": "...", "id": "display_generative"}
  "output_format_ids": [
    {"agent_url": "...", "id": "display_static", "width": 300, "height": 250}
    {"agent_url": "...", "id": "display_static", "width": 728, "height": 90}
  ]
}

オプション 2: 任意のディメンションを生成（テンプレート出力）

{
  "format_id": {"agent_url": "...", "id": "display_generative"}
  "output_format_ids": [
    {"agent_url": "...", "id": "display_static"}
  ]
}

生成ロジックが任意のディメンションを扱える場合はテンプレート出力を使います。バイヤーが生成系フォーマットを呼ぶときにディメンションを指定します。

発見パターン

フォーマット定義: `list_creative_formats()`

クリエイティブエージェントとセールスエージェントの両方が、list_creative_formats() を介してテンプレートフォーマット定義を返せます:

{
  "formats": [
    {
      "format_id": {"agent_url": "...", "id": "display_static"}
      "accepts_parameters": ["dimensions"]
      "assets": [...]
    }
  ]
}

目的: バイヤーはどのフォーマットタイプが利用可能か、どのパラメータを受け入れるかを発見します。

プレースメントの制約: `get_products()`

要件: セールスエージェントは、プレースメントでパラメータ付きの format_id（特定のディメンション/デュレーション付き）を返さなければなりません（MUST）。パラメータなしのテンプレート format_id は、プレースメント仕様では許可されません。

{
  "products": [{
    "placements": [{
      "kind": "seller_inline",
      "placement_id": "display_multi_size",
      "name": "Display multi-size",
      "mode": "targetable",
      "format_ids": [
        {"agent_url": "...", "id": "display_static", "width": 300, "height": 250},
        {"agent_url": "...", "id": "display_static", "width": 728, "height": 90}
      ]
    }]
  }]
}

目的: バイヤーは各プレースメントでどの特定のディメンションがサポートされるかを発見します。 プレースメントでパラメータ付き format_id が必要な理由:

受け入れられるディメンションバリアントの明示的なリストを提供する
何が受け入れられるかについての曖昧さを排除する
クリエイティブ提出時に明確な検証を可能にする
バイヤーが自分のクリエイティブのディメンションを特定のプレースメント要件に照合できる

発見フロー:

バイヤーがクリエイティブまたはセールスエージェントで list_creative_formats() を呼ぶ → display_static がディメンションを受け入れるテンプレートフォーマットだと知る
バイヤーがセールスエージェントで get_products() を呼ぶ → どの特定のディメンションがサポートされるか（300×250、728×90）を知る
バイヤーが、プレースメントのサポートするディメンションの一つに一致するパラメータ付き format_id でクリエイティブを作成する

実装ガイドライン

クリエイティブエージェント向け

フォーマット定義:

柔軟なディメンションを持つフォーマットには accepts_parameters: ["dimensions"] を設定
柔軟なデュレーションを持つフォーマットには accepts_parameters: ["duration"] を設定
両方を持つフォーマット（例: ディメンション付き動画）には accepts_parameters: ["dimensions", "duration"] を設定
フォーマットがディメンションを受け入れる場合は renders 配列を省略（ディメンションは format_id に由来）
固定ディメンションの具体フォーマットには renders 配列を含める

検証:

format_id のディメンションをアセットのディメンションに対して検証
width/height/unit がそろって存在すること（部分的でない）を保証
format_id がアセットに一致しない場合は明確なエラーを返す

フォーマットの検索/マッチング:

list_creative_formats() はテンプレートフォーマット（ディメンションパラメータなし）を返す
ID によるフォーマット検索は、ディメンションパラメータを無視してベースフォーマット（agent_url + id）で一致する
例: {id: "display_static", width: 300, height: 250} のリクエストはテンプレートフォーマット {id: "display_static"} に一致する
ディメンションパラメータはフォーマット発見ではなくクリエイティブ検証に使われる

セールスエージェント向け

プロダクトレスポンス - 重要な要件:

プレースメントで常に特定のディメンション/デュレーション付きのパラメータ付き format_id を返す必要があります（MUST）
プレースメントの format_ids 配列でパラメータなしのテンプレート format_id を返してはなりません（NEVER）

サポートするすべてのディメンション/デュレーションのバリアントを明示的に列挙する:

{
  "placements": [{
    "kind": "seller_inline",
    "placement_id": "display_multi_size",
    "name": "Display multi-size",
    "mode": "targetable",
    "format_ids": [
      {"agent_url": "...", "id": "display_static", "width": 300, "height": 250},
      {"agent_url": "...", "id": "display_static", "width": 728, "height": 90},
      {"agent_url": "...", "id": "display_static", "width": 160, "height": 600}
    ]
  }]
}

この要件が存在する理由:

バイヤーはサポートするディメンションの明示的なリストを必要とする
何が受け入れられるかについての曖昧さがない
クリエイティブ提出時の検証を可能にする
パラメータなしのテンプレート format_id は list_creative_formats() のレスポンス専用

クリエイティブの検証:

クリエイティブの format_id が少なくとも 1 つのプレースメント format_id に正確に一致することを保証
一致には、すべてのフィールド（agent_url、id、width、height、duration_ms）の正確な等価が必要
部分一致や「十分近い」ディメンションはなし

バイヤー向け

クリエイティブマニフェストの構築:

accepts_parameters 配列を確認するためにフォーマット定義を取得
テンプレートフォーマットを使うときは format_id にディメンション/デュレーションフィールドを含める
アセットのディメンションが format_id のディメンションに一致することを保証
同期前にプレースメント format_id に対して検証

format_id の等価性ルール

2 つの format_id は、次の場合に限り同一です:

agent_url が正確に一致
id が正確に一致
width が正確に一致（存在する場合）
height が正確に一致（存在する場合）
duration_ms が正確に一致（存在する場合）

正規化

等価性またはキャッシュのために format_id を比較するとき: 必須フィールド:

width と height はそろって存在しなければならない（一方だけは指定できない）
すべてのディメンションはピクセル単位（整数）

数値精度:

width と height は整数（300 であって 300.5 ではない）
デュレーションは小数になれる（端数秒には 30000.5ms）

フィールド順:

等価性に JSON のフィールド順は関係しない
{"width": 300, "height": 250} は {"height": 250, "width": 300} と等しい

等価の例:

// These are IDENTICAL format IDs
{"agent_url": "...", "id": "display_static", "width": 300, "height": 250}
{"agent_url": "...", "id": "display_static", "width": 300, "height": 250}

// These are DIFFERENT format IDs
{"agent_url": "...", "id": "display_static", "width": 300, "height": 250}
{"agent_url": "...", "id": "display_static", "width": 728, "height": 90}

// INVALID - partial dimensions not allowed (schema validation will reject)
{"agent_url": "...", "id": "display_static", "width": 300}  // ❌ Missing height

マッチングロジック

プレースメント検証

重要: プレースメントは、常に明示的なディメンション/デュレーション付きのパラメータ付き format_id を指定しなければなりません（MUST）。パラメータなしのテンプレート format_id はプレースメントでは許可されません。 プレースメント内のパラメータ付きフォーマット（必須のパターン）:

// Placement specifies exact supported dimensions
{"format_ids": [
  {"agent_url": "...", "id": "display_static", "width": 300, "height": 250},
  {"agent_url": "...", "id": "display_static", "width": 728, "height": 90}
]}

// Creative matches only if exact equality with one of the placement's format_ids
{"format_id": {"agent_url": "...", "id": "display_static", "width": 300, "height": 250}}  // ✅ Match
{"format_id": {"agent_url": "...", "id": "display_static", "width": 728, "height": 90}}   // ✅ Match
{"format_id": {"agent_url": "...", "id": "display_static", "width": 160, "height": 600}}  // ❌ Not in placement list
{"format_id": {"agent_url": "...", "id": "display_static"}}                               // ❌ Missing dimensions

具体フォーマットからの移行

移行前（フォーマット爆発）:

// 50 separate format definitions
{
  "format_id": {"agent_url": "...", "id": "display_300x250"}
  "renders": [{"dimensions": {"width": 300, "height": 250}}]
}
{
  "format_id": {"agent_url": "...", "id": "display_728x90"}
  "renders": [{"dimensions": {"width": 728, "height": 90}}]
}
// ... 48 more

移行後（単一のテンプレートフォーマット）:

{
  "format_id": {"agent_url": "...", "id": "display_static"}
  "accepts_parameters": ["dimensions"]
  "assets": [...]
}

クリエイティブマニフェストの変更:

// Before: Format ID encoded dimensions in string
{
  "format_id": {"agent_url": "...", "id": "display_300x250"}
  "assets": {...}
}

// After: Dimensions as structured fields in format_id
{
  "format_id": {
    "agent_url": "..."
    "id": "display_static"
    "width": 300
    "height": 250
  }
  "assets": {...}
}

よくあるパターン

IAB 標準ディスプレイサイズ

IAB サイズに 15 の個別フォーマットを定義する代わりに、1 つのテンプレートを使います:

{
  "format_id": {"agent_url": "...", "id": "display_static"}
  "accepts_parameters": ["dimensions"]
}

クリエイティブはパラメータでサイズを指定します:

300×250: {id: "display_static", width: 300, height: 250}
728×90: {id: "display_static", width: 728, height: 90}
160×600: {id: "display_static", width: 160, height: 600}
など

動画の尺バリエーション

個別の 15 秒、30 秒、60 秒のフォーマット定義の代わりに:

{
  "format_id": {"agent_url": "...", "id": "video_hosted"}
  "accepts_parameters": ["duration"]
}

クリエイティブはデュレーションを指定します: {id: "video_hosted", duration_ms: 30000}

DOOH のスクリーンサイズ

すべてのビルボードサイズにフォーマットを定義する代わりに:

{
  "format_id": {"agent_url": "...", "id": "dooh_static"}
  "accepts_parameters": ["dimensions"]
}

クリエイティブはピクセルディメンションを指定します: {id: "dooh_static", width: 1920, height: 560} 注: すべてのディメンションはピクセル単位です。物理的なスクリーンサイズ（例: 48 フィート × 14 フィート）はプレースメントメタデータです。

参考

クリエイティブマニフェスト - 完全なマニフェストの構造
フォーマット発見 - バイヤーがフォーマットを発見する方法
プレースメントターゲティング - クリエイティブをプレースメントに割り当てる

​課題: フォーマット爆発

​解決策: パラメータ付きテンプレートフォーマット

​フォーマットタイプと format_id

​フォーマット定義

​format_id の種類

​テンプレートフォーマット定義

​パラメータ付き format_id（クリエイティブマニフェスト）

​プレースメントの制約

​メリット

​format_id のフィールド

​ビジュアルフォーマット（ディスプレイ、DOOH、ネイティブ）

​時間ベースフォーマット（動画、音声）

​組み合わせ（ディメンション付き動画）

​フォーマット定義のパターン

​ディスプレイフォーマット（柔軟なディメンション）

​動画フォーマット（柔軟なデュレーション）

​DOOH フォーマット（ピクセルディメンション）

​出力フォーマットを持つ生成系フォーマット

​発見パターン

​フォーマット定義: list_creative_formats()

​プレースメントの制約: get_products()

​実装ガイドライン

​クリエイティブエージェント向け

​セールスエージェント向け

​バイヤー向け

​format_id の等価性ルール

​正規化

​マッチングロジック

​プレースメント検証

​具体フォーマットからの移行

​よくあるパターン

​IAB 標準ディスプレイサイズ

​動画の尺バリエーション

​DOOH のスクリーンサイズ

​参考

課題: フォーマット爆発

解決策: パラメータ付きテンプレートフォーマット

フォーマットタイプと format_id

フォーマット定義

format_id の種類

テンプレートフォーマット定義

パラメータ付き format_id（クリエイティブマニフェスト）

プレースメントの制約

メリット

format_id のフィールド

ビジュアルフォーマット（ディスプレイ、DOOH、ネイティブ）

時間ベースフォーマット（動画、音声）

組み合わせ（ディメンション付き動画）

フォーマット定義のパターン

ディスプレイフォーマット（柔軟なディメンション）

動画フォーマット（柔軟なデュレーション）

DOOH フォーマット（ピクセルディメンション）

出力フォーマットを持つ生成系フォーマット

発見パターン

フォーマット定義: `list_creative_formats()`

プレースメントの制約: `get_products()`

実装ガイドライン

クリエイティブエージェント向け

セールスエージェント向け

バイヤー向け

format_id の等価性ルール

正規化

マッチングロジック

プレースメント検証

具体フォーマットからの移行

よくあるパターン

IAB 標準ディスプレイサイズ

動画の尺バリエーション

DOOH のスクリーンサイズ

参考