> ## 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.

# Template Format IDs

> AdCP のテンプレート format_id は、サイズごとに個別のフォーマットを作らずに、単一のフォーマット定義で多数のディメンションバリアントをサポートできるようにします。

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

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

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

```json theme={null}
{"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** を生成します:

### フォーマット定義

1. **具体フォーマット** - フォーマット定義に固定のディメンション
   * 明示的なディメンションを持つ `renders` 配列を持つ
   * 例: `display_300x250` は常に 300×250px を意味する
   * パラメータを受け入れられない

2. **テンプレートフォーマット** - format\_id でパラメータを受け入れる
   * 受け入れるパラメータを列挙する `accepts_parameters` 配列を持つ
   * 例: `display_static` は任意のディメンションになれる
   * パラメータありでもなしでも使える

### format\_id の種類

1. **具体 format\_id** - 具体フォーマットを参照
   * 例: `{id: "display_300x250"}`
   * パラメータなし（受け入れない）

2. **テンプレート format\_id** - パラメータなしでテンプレートフォーマットを参照
   * 例: `{id: "display_static"}`
   * 任意のディメンションを受け入れるためにプレースメントで使う

3. **パラメータ付き format\_id** - パラメータ付きのテンプレートフォーマット
   * 例: `{id: "display_static", width: 300, height: 250}`
   * 正確なディメンション（ピクセル）を指定するためにクリエイティブで使う

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

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

```json theme={null}
{
  "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 で正確なディメンションを指定します:

```json theme={null}
{
  "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()` のフォーマット定義でのみ使われます。

パブリッシャーは、サポートするすべてのバリアントを列挙して、サポートするディメンションを指定します:

```json theme={null}
{
  "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） - ピクセル単位の高さ

**例:**

```json theme={null}
{
  "agent_url": "https://creative.adcontextprotocol.org"
  "id": "display_static"
  "width": 300
  "height": 250
}
```

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

**フィールド:**

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

**例:**

```json theme={null}
{
  "agent_url": "https://creative.adcontextprotocol.org"
  "id": "video_hosted"
  "duration_ms": 30000
}
```

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

**フィールド:**

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

**例:**

```json theme={null}
{
  "agent_url": "https://creative.adcontextprotocol.org"
  "id": "video_hosted"
  "width": 1920
  "height": 1080
  "duration_ms": 30000
}
```

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

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

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

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

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

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

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

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

```json theme={null}
{
  "format_id": {
    "agent_url": "https://creative.adcontextprotocol.org"
    "id": "dooh_static"
    "width": 1920
    "height": 560
  }
  "assets": {...}
}
```

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

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

生成系フォーマットは、生成できる出力フォーマットを指定します:

**オプション 1: 特定のディメンションを生成**

```json theme={null}
{
  "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: 任意のディメンションを生成（テンプレート出力）**

```json theme={null}
{
  "format_id": {"agent_url": "...", "id": "display_generative"}
  "output_format_ids": [
    {"agent_url": "...", "id": "display_static"}
  ]
}
```

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

## 発見パターン

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

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

```json theme={null}
{
  "formats": [
    {
      "format_id": {"agent_url": "...", "id": "display_static"}
      "accepts_parameters": ["dimensions"]
      "assets": [...]
    }
  ]
}
```

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

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

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

```json theme={null}
{
  "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 が必要な理由:**

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

**発見フロー**:

1. バイヤーがクリエイティブまたはセールスエージェントで `list_creative_formats()` を呼ぶ → `display_static` がディメンションを受け入れるテンプレートフォーマットだと知る
2. バイヤーがセールスエージェントで `get_products()` を呼ぶ → どの*特定のディメンション*がサポートされるか（300×250、728×90）を知る
3. バイヤーが、プレースメントのサポートするディメンションの一つに一致するパラメータ付き 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）**
* サポートするすべてのディメンション/デュレーションのバリアントを明示的に列挙する:
  ```json theme={null}
  {
    "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}` と等しい

**等価の例:**

```json theme={null}
// 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 はプレースメントでは許可されません。

**プレースメント内のパラメータ付きフォーマット（必須のパターン）:**

```json theme={null}
// 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
```

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

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

```json theme={null}
// 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
```

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

```json theme={null}
{
  "format_id": {"agent_url": "...", "id": "display_static"}
  "accepts_parameters": ["dimensions"]
  "assets": [...]
}
```

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

```json theme={null}
// 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 つのテンプレートを使います:

```json theme={null}
{
  "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 秒のフォーマット定義の代わりに:

```json theme={null}
{
  "format_id": {"agent_url": "...", "id": "video_hosted"}
  "accepts_parameters": ["duration"]
}
```

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

### DOOH のスクリーンサイズ

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

```json theme={null}
{
  "format_id": {"agent_url": "...", "id": "dooh_static"}
  "accepts_parameters": ["dimensions"]
}
```

クリエイティブはピクセルディメンションを指定します: `{id: "dooh_static", width: 1920, height: 560}`

**注**: すべてのディメンションはピクセル単位です。物理的なスクリーンサイズ（例: 48 フィート × 14 フィート）はプレースメントメタデータです。

## 参考

* [クリエイティブマニフェスト](/docs/creative/creative-manifests) - 完全なマニフェストの構造
* [フォーマット発見](/docs/creative/formats) - バイヤーがフォーマットを発見する方法
* [プレースメントターゲティング](/docs/media-buy/creatives) - クリエイティブをプレースメントに割り当てる