AdCP — Template Format IDs

Template formats allow a single format definition to support multiple dimension or duration variants without creating separate format definitions for each variant. This eliminates format explosion when publishers support many similar variants.

The Problem: Format Explosion

Without template formats, each dimension variant requires a separate format definition and 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

Publisher with 50 placement sizes → 50 separate format definitions to create, maintain, and document.

The Solution: Template Formats with Parameters

A single template format definition (display_static) accepts dimension fields in the format_id object, allowing creatives to specify their exact dimensions.

Format Types and Format IDs

There are two types of format definitions, which produce three types of format IDs:

Format Definitions

Concrete formats - Fixed dimensions in format definition
- Have renders array with explicit dimensions
- Example: display_300x250 always means 300×250px
- Cannot accept parameters
Template formats - Accept parameters in format_id
- Have accepts_parameters array listing accepted parameters
- Example: display_static can be any dimensions
- Can be used with or without parameters

Format IDs

Concrete format_id - References a concrete format
- Example: {id: "display_300x250"}
- No parameters (none accepted)
Template format_id - References a template format without parameters
- Example: {id: "display_static"}
- Used in placements to accept any dimensions
Parameterized format_id - Template format with parameters
- Example: {id: "display_static", width: 300, height: 250}
- Used in creatives to specify exact dimensions (in pixels)

Template Format Definition

Format definition that accepts parameters:

{
  "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
    }
  ]
}

Key fields:

accepts_parameters: ["dimensions"] - Format accepts dimensions (width/height in pixels) in format_id
renders[].parameters_from_format_id: true - Render parameters come from format_id
requirements.parameters_from_format_id: true - Asset parameters must match format_id

Parameterized Format ID (Creative Manifest)

Creative specifies exact dimensions in format_id to use the template format:

{
  "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"
    }
  }
}

This format_id is parameterized: Same dimensions always produce the same format_id object, enabling deduplication and caching.

Placement Constraints

CRITICAL: Sales agents MUST always return parameterized format_ids (with specific dimensions/duration) in placements. Template format_ids without parameters are ONLY used in format definitions from list_creative_formats(). Publishers specify supported dimensions by listing all supported variants:

{
  "placement_id": "homepage_banner"
  "name": "Homepage Banner"
  "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
    }
  ]
}

Validation: Creative’s format_id must exactly match one of the placement’s parameterized format_ids. Why parameterized only in placements:

Buyers need to know exactly which dimensions are supported
No ambiguity about what will be accepted
Enables clear validation at creative submission time
Template format_ids without parameters are only for format discovery via list_creative_formats()

Benefits

✅ Scalability - One template format supports unlimited dimension variants ✅ Predictable - Same dimensions = same format_id (enables caching/deduplication) ✅ Self-contained - Creatives fully specify their format via format_id ✅ Portable - A 300×250 creative works on any placement accepting 300×250 ✅ Publisher control - Placements specify exact dimension constraints ✅ Type-safe - Width/height are numbers, not encoded strings ✅ Backward compatible - Concrete (non-template) formats work unchanged

Format ID Fields

Visual Formats (Display, DOOH, Native)

Fields:

width (integer, minimum: 1) - Width in pixels
height (integer, minimum: 1) - Height in pixels

Example:

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

Time-Based Formats (Video, Audio)

Fields:

duration_ms (number, minimum: 1) - Duration in milliseconds

Example:

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

Combined (Video with Dimensions)

Fields:

width, height (integers) - Video frame dimensions in pixels
duration_ms (number) - Video length in milliseconds

Example:

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

Format Definition Patterns

Display Format (Flexible Dimensions)

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

Video Format (Flexible Duration)

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

DOOH Format (Pixel Dimensions)

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

Creative with pixel dimensions:

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

Note: All dimensions are in pixels. Physical screen dimensions (e.g., 48 feet × 14 feet billboard) are placement metadata, not format specifications.

Generative Formats with Output Formats

Generative formats specify which output formats they can produce: Option 1: Generate specific dimensions

{
  "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}
  ]
}

Option 2: Generate any dimension (template output)

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

Use template outputs when your generation logic can handle arbitrary dimensions. Buyer specifies dimensions when calling the generative format.

Discovery Pattern

Format Definitions: `list_creative_formats()`

Both creative and sales agents can return template format definitions via list_creative_formats():

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

Purpose: Buyers discover what format types are available and what parameters they accept.

Placement Constraints: `get_products()`

REQUIREMENT: Sales agents MUST return parameterized format_ids (with specific dimensions/duration) in placements. Template format_ids without parameters are NOT allowed in placement specifications.

{
  "products": [{
    "placements": [{
      "format_ids": [
        {"agent_url": "...", "id": "display_static", "width": 300, "height": 250},
        {"agent_url": "...", "id": "display_static", "width": 728, "height": 90}
      ]
    }]
  }]
}

Purpose: Buyers discover which specific dimensions are supported for each placement. Why parameterized format_ids are required in placements:

Provides explicit list of accepted dimension variants
Eliminates ambiguity about what will be accepted
Enables clear validation at creative submission time
Buyers can match their creative dimensions against specific placement requirements

Discovery Flow:

Buyer calls list_creative_formats() on creative or sales agent → learns display_static is a template format that accepts dimensions
Buyer calls get_products() on sales agent → learns which specific dimensions are supported (300×250, 728×90)
Buyer creates creative with parameterized format_id matching one of the placement’s supported dimensions

Implementation Guidelines

For Creative Agents

Format definitions:

Set accepts_parameters: ["dimensions"] for formats with flexible dimensions
Set accepts_parameters: ["duration"] for formats with flexible duration
Set accepts_parameters: ["dimensions", "duration"] for formats with both (e.g., video with dimensions)
Omit renders array when format accepts dimensions (dimensions come from format_id)
Include renders array for concrete formats with fixed dimensions

Validation:

Validate format_id dimensions against asset dimensions
Ensure width/height/unit are present together (not partial)
Return clear errors if format_id doesn’t match assets

Format lookup/matching:

list_creative_formats() returns template formats (without dimension parameters)
Format lookup by ID matches on base format (agent_url + id), ignoring dimension parameters
Example: Request for {id: "display_static", width: 300, height: 250} matches the template format {id: "display_static"}
Dimension parameters are used for creative validation, not format discovery

For Sales Agents

Product responses - CRITICAL REQUIREMENT:

MUST always return parameterized format_ids with specific dimensions/duration in placements
NEVER return template format_ids without parameters in placement format_ids arrays

List all supported dimension/duration variants explicitly:

{
  "placements": [{
    "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}
    ]
  }]
}

Why this requirement exists:

Buyers need explicit lists of supported dimensions
No ambiguity about what will be accepted
Enables validation at creative submission time
Template format_ids without parameters are ONLY for list_creative_formats() responses

Creative validation:

Ensure creative format_id exactly matches at least one placement format_id
Match requires exact equality of all fields: agent_url, id, width, height, duration_ms
No partial matches or “close enough” dimensions

For Buyers

Creative manifest construction:

Fetch format definitions to check accepts_parameters array
Include dimension/duration fields in format_id when using template formats
Ensure asset dimensions match format_id dimensions
Validate against placement format_ids before syncing

Format ID Equality Rules

Two format_ids are identical if and only if:

agent_url matches exactly
id matches exactly
width matches exactly (if present)
height matches exactly (if present)
duration_ms matches exactly (if present)

Canonicalization

When comparing format_ids for equality or caching: Required fields:

Both width and height must be present together (cannot specify only one)
All dimensions are in pixels (integers)

Numeric precision:

Width and height are integers (300 not 300.5)
Duration can be decimal (30000.5ms for fractional seconds)

Field order:

JSON field order does NOT matter for equality
{"width": 300, "height": 250} equals {"height": 250, "width": 300}

Example equivalence:

// 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

Matching Logic

Placement Validation

IMPORTANT: Placements MUST always specify parameterized format_ids with explicit dimensions/duration. Template format_ids without parameters are NOT allowed in placements. Parameterized formats in placement (REQUIRED pattern):

// 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

Migration from Concrete Formats

Before (format explosion):

// 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

After (single template format):

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

Creative manifest change:

// 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": {...}
}

Common Patterns

IAB Standard Display Sizes

Instead of defining 15 separate formats for IAB sizes, use one template:

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

Creatives specify their size via parameters:

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}
etc.

Video Duration Variants

Instead of separate 15s, 30s, 60s format definitions:

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

Creatives specify duration: {id: "video_hosted", duration_ms: 30000}

DOOH Screen Sizes

Instead of defining formats for every billboard size:

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

Creatives specify pixel dimensions: {id: "dooh_static", width: 1920, height: 560} Note: All dimensions are in pixels. Physical screen size (e.g., 48 feet × 14 feet) is placement metadata.

Documentation

Template Format IDs

The Problem: Format Explosion

The Solution: Template Formats with Parameters

Format Types and Format IDs

Format Definitions

Format IDs

Template Format Definition

Parameterized Format ID (Creative Manifest)

Placement Constraints

Benefits

Format ID Fields

Visual Formats (Display, DOOH, Native)

Time-Based Formats (Video, Audio)

Combined (Video with Dimensions)

Format Definition Patterns

Display Format (Flexible Dimensions)

Video Format (Flexible Duration)

DOOH Format (Pixel Dimensions)

Generative Formats with Output Formats

Discovery Pattern

Format Definitions: `list_creative_formats()`

Placement Constraints: `get_products()`

Implementation Guidelines

For Creative Agents

For Sales Agents

For Buyers

Format ID Equality Rules

Canonicalization

Matching Logic

Placement Validation

Migration from Concrete Formats

Common Patterns

IAB Standard Display Sizes

Video Duration Variants

DOOH Screen Sizes

See Also

Documentation

​The Problem: Format Explosion

​The Solution: Template Formats with Parameters

​Format Types and Format IDs

​Format Definitions

​Format IDs

​Template Format Definition

​Parameterized Format ID (Creative Manifest)

​Placement Constraints

​Benefits

​Format ID Fields

​Visual Formats (Display, DOOH, Native)

​Time-Based Formats (Video, Audio)

​Combined (Video with Dimensions)

​Format Definition Patterns

​Display Format (Flexible Dimensions)

​Video Format (Flexible Duration)

​DOOH Format (Pixel Dimensions)

​Generative Formats with Output Formats

​Discovery Pattern

​Format Definitions: list_creative_formats()

​Placement Constraints: get_products()

​Implementation Guidelines

​For Creative Agents

​For Sales Agents

​For Buyers

​Format ID Equality Rules

​Canonicalization

​Matching Logic

​Placement Validation

​Migration from Concrete Formats

​Common Patterns

​IAB Standard Display Sizes

​Video Duration Variants

​DOOH Screen Sizes

​See Also

The Problem: Format Explosion

The Solution: Template Formats with Parameters

Format Types and Format IDs

Format Definitions

Format IDs

Template Format Definition

Parameterized Format ID (Creative Manifest)

Placement Constraints

Benefits

Format ID Fields

Visual Formats (Display, DOOH, Native)

Time-Based Formats (Video, Audio)

Combined (Video with Dimensions)

Format Definition Patterns

Display Format (Flexible Dimensions)

Video Format (Flexible Duration)

DOOH Format (Pixel Dimensions)

Generative Formats with Output Formats

Discovery Pattern

Format Definitions: `list_creative_formats()`

Placement Constraints: `get_products()`

Implementation Guidelines

For Creative Agents

For Sales Agents

For Buyers

Format ID Equality Rules

Canonicalization

Matching Logic

Placement Validation

Migration from Concrete Formats

Common Patterns

IAB Standard Display Sizes

Video Duration Variants

DOOH Screen Sizes

See Also