Interface Format

Represents a creative format with its requirements

interface Format {
    format_id: FormatReferenceStructuredObject;
    name: string;
    description?: string;
    example_url?: string;
    accepts_parameters?: FormatIDParameter[];
    renders?: (
        | {
            role: string;
            dimensions: {
                width?: number;
                height?: number;
                min_width?: number;
                min_height?: number;
                max_width?: number;
                max_height?: number;
                unit?: DimensionUnit;
                responsive?: { width: boolean; height: boolean };
                aspect_ratio?: string;
            };
        }
        | { role: string; parameters_from_format_id: true }
    )[];
    assets?: FormatAssetSlot[];
    delivery?: {};
    supported_macros?: string[];
    input_format_ids?: FormatReferenceStructuredObject[];
    output_format_ids?: FormatReferenceStructuredObject[];
    format_card?: { format_id: FormatReferenceStructuredObject; manifest: {} };
    accessibility?: {
        wcag_level: WCAGLevel;
        requires_accessible_assets?: boolean;
    };
    supported_disclosure_positions?: DisclosurePosition[];
    disclosure_capabilities?: {
        position: DisclosurePosition;
        persistence: DisclosurePersistence[];
    }[];
    format_card_detailed?: {
        format_id: FormatReferenceStructuredObject;
        manifest: {};
    };
    reported_metrics?: AvailableMetric[];
    pricing_options?: VendorPricingOption[];
    canonical?: CanonicalProjectionReference;
    canonical_parameters?: ProductFormatDeclaration;
}

Hierarchy (View Summary)

Format
- CreativeFormat

Properties

format_id

format_id: FormatReferenceStructuredObject

name

name: string

Human-readable format name

`Optional`description

description?: string

Plain text explanation of what this format does and what assets it requires

`Optional`example_url

example_url?: string

Optional URL to showcase page with examples and interactive demos of this format

`Optional`accepts_parameters

accepts_parameters?: FormatIDParameter[]

List of parameters this format accepts in format_id. Template formats define which parameters (dimensions, duration, etc.) can be specified when instantiating the format. Empty or omitted means this is a concrete format with fixed parameters.

`Optional`renders

renders?: (
    | {
        role: string;
        dimensions: {
            width?: number;
            height?: number;
            min_width?: number;
            min_height?: number;
            max_width?: number;
            max_height?: number;
            unit?: DimensionUnit;
            responsive?: { width: boolean; height: boolean };
            aspect_ratio?: string;
        };
    }
    | { role: string; parameters_from_format_id: true }
)[]

Specification of rendered pieces for this format. Most formats produce a single render. Companion ad formats (video + banner), adaptive formats, and multi-placement formats produce multiple renders. Each render specifies its role and dimensions.

Type Declaration

{
    role: string;
    dimensions: {
        width?: number;
        height?: number;
        min_width?: number;
        min_height?: number;
        max_width?: number;
        max_height?: number;
        unit?: DimensionUnit;
        responsive?: { width: boolean; height: boolean };
        aspect_ratio?: string;
    };
}
- role: string
  Semantic role of this rendered piece (e.g., 'primary', 'companion', 'mobile_variant')
- dimensions: {
      width?: number;
      height?: number;
      min_width?: number;
      min_height?: number;
      max_width?: number;
      max_height?: number;
      unit?: DimensionUnit;
      responsive?: { width: boolean; height: boolean };
      aspect_ratio?: string;
  }
  Dimensions for this rendered piece. Defaults to pixels when unit is absent.
  - Optionalwidth?: number
    Fixed width. Interpretation depends on unit (default: pixels).
  - Optionalheight?: number
    Fixed height. Interpretation depends on unit (default: pixels).
  - Optionalmin_width?: number
    Minimum width for responsive renders
  - Optionalmin_height?: number
    Minimum height for responsive renders
  - Optionalmax_width?: number
    Maximum width for responsive renders
  - Optionalmax_height?: number
    Maximum height for responsive renders
  - Optionalunit?: DimensionUnit
  - Optionalresponsive?: { width: boolean; height: boolean }
    Indicates which dimensions are responsive/fluid
  - Optionalaspect_ratio?: string
    Fixed aspect ratio constraint (e.g., '16:9', '4:3', '1:1', '1.91:1')
    
    Pattern
    ^\d+(.\d+)?:\d+(.\d+)?$
{ role: string; parameters_from_format_id: true }
- role: string
  Semantic role of this rendered piece (e.g., 'primary', 'companion', 'mobile_variant')
- parameters_from_format_id: true

`Optional`assets

assets?: FormatAssetSlot[]

Array of all assets supported for this format. Each asset is identified by its asset_id, which must be used as the key in creative manifests. Use the 'required' boolean on each asset to indicate whether it's mandatory.

`Optional`delivery

delivery?: {}

Delivery method specifications (e.g., hosted, VAST, third-party tags)

`Optional`supported_macros

supported_macros?: string[]

List of universal macros supported by this format (e.g., MEDIA_BUY_ID, CACHEBUSTER, DEVICE_ID). Used for validation and developer tooling. See docs/creative/universal-macros.mdx for full documentation.

`Optional`input_format_ids

input_format_ids?: FormatReferenceStructuredObject[]

Deprecated

DEPRECATED in 3.1. Removed at 4.0. Use list_transformers instead — a transformer declares its own input_format_ids/output_format_ids, so build capability is a property of the transformer (the unit you select and that carries pricing), not a relationship hung on a format. Discover build capability via list_transformers (optionally filtered by input_format_ids/output_format_ids).

Migration: sellers that expressed transform capability by hanging input_format_ids on a format SHOULD declare a transformer via list_transformers instead. Buyers SHOULD discover build capability via list_transformers rather than filtering formats.

Legacy behavior, retained for 3.1–3.x backward compatibility: array of format IDs this format accepts as input creative manifests; when present, indicates this format can take existing creatives in these formats as input. SDKs reading 3.1 catalogs MUST continue to honor this field when present; 4.0+ SDKs MAY reject it. New code SHOULD NOT emit this field.

`Optional`output_format_ids

output_format_ids?: FormatReferenceStructuredObject[]

Deprecated

DEPRECATED in 3.1. Removed at 4.0. Use list_transformers instead — a transformer declares its own output_format_ids, so what a builder can produce is a property of the transformer, not a relationship hung on a format. Discover via list_transformers.

Migration: sellers that expressed multi-output build capability (e.g. a multi-publisher template) by hanging output_format_ids on a format SHOULD declare a transformer via list_transformers instead.

Legacy behavior, retained for 3.1–3.x backward compatibility: array of format IDs this format can produce as output; when present, indicates this format can build creatives in these output formats. SDKs reading 3.1 catalogs MUST continue to honor this field when present; 4.0+ SDKs MAY reject it. New code SHOULD NOT emit this field.

`Optional`format_card

format_card?: { format_id: FormatReferenceStructuredObject; manifest: {} }

Optional standard visual card (300x400px) for displaying this format in user interfaces. Can be rendered via preview_creative or pre-generated.

Type Declaration

format_id: FormatReferenceStructuredObject
manifest: {}
Asset manifest for rendering the card, structure defined by the format

`Optional`accessibility

accessibility?: { wcag_level: WCAGLevel; requires_accessible_assets?: boolean }

Accessibility posture of this format. Declares the WCAG conformance level that creatives produced by this format will meet.

Type Declaration

wcag_level: WCAGLevel
Optionalrequires_accessible_assets?: boolean
When true, all assets with x-accessibility fields must include those fields. For inspectable assets (image, video, audio), this means providing accessibility metadata like alt_text or captions. For opaque assets (HTML, JavaScript), this means providing self-declared accessibility properties.

`Optional`supported_disclosure_positions

supported_disclosure_positions?: DisclosurePosition[]

Disclosure positions this format can render. Buyers use this to determine whether a format can satisfy their compliance requirements before submitting a creative. When omitted, the format makes no disclosure rendering guarantees — creative agents SHOULD treat this as incompatible with briefs that require specific disclosure positions. Values correspond to positions on creative-brief.json required_disclosures.

`Optional`disclosure_capabilities

disclosure_capabilities?: {
position: DisclosurePosition;
persistence: DisclosurePersistence[];
}[]

Structured disclosure capabilities per position with persistence modes. Declares which persistence behaviors each disclosure position supports, enabling persistence-aware matching against provenance render guidance and brief requirements. When present, supersedes supported_disclosure_positions for persistence-aware queries. The flat supported_disclosure_positions field is retained for backward compatibility. Each position MUST appear at most once; validators and agents SHOULD reject duplicates.

Type Declaration

position: DisclosurePosition
persistence: DisclosurePersistence[]
Persistence modes this position supports

`Optional`format_card_detailed

format_card_detailed?: {
format_id: FormatReferenceStructuredObject;
manifest: {};
}

Optional detailed card with carousel and full specifications. Provides rich format documentation similar to ad spec pages.

Type Declaration

format_id: FormatReferenceStructuredObject
manifest: {}
Asset manifest for rendering the detailed card, structure defined by the format

`Optional`reported_metrics

reported_metrics?: AvailableMetric[]

Metrics this format can produce in delivery reporting. Buyers receive the intersection of format reported_metrics and product available_metrics. If omitted, the format defers entirely to product-level metric declarations.

`Optional`pricing_options

pricing_options?: VendorPricingOption[]

Deprecated

DEPRECATED in 3.1. Removed at 4.0. Use transformer.pricing_options (via list_transformers) instead — pricing belongs on the transformer (the unit selected and billed), exactly as it belongs on a media-buy product. Once formats only describe output shape, format-level pricing is vestigial.

Migration: transformation/generation agents that charged via format.pricing_options SHOULD move the same vendor-pricing-option entries onto the corresponding transformer. The applied option is echoed per-leaf on the build_creative response and reconciled via report_usage, unchanged.

Legacy behavior, retained for 3.1–3.x backward compatibility: pricing options for this format, used by transformation/generation agents that charge per format adapted, per image generated, or per unit of work; present when the request included include_pricing=true and account. SDKs reading 3.1 catalogs MUST continue to honor this field when present; 4.0+ SDKs MAY reject it. New code SHOULD NOT emit this field.

`Optional`canonical

canonical?: CanonicalProjectionReference

`Optional`canonical_parameters

canonical_parameters?: ProductFormatDeclaration

Interface Format

Hierarchy (View Summary)

Index

Properties

Properties

format_id

name

Optionaldescription

Optionalexample_url

Optionalaccepts_parameters

Optionalrenders

Type Declaration

role: string

dimensions: { width?: number; height?: number; min_width?: number; min_height?: number; max_width?: number; max_height?: number; unit?: DimensionUnit; responsive?: { width: boolean; height: boolean }; aspect_ratio?: string;}

Optionalwidth?: number

Optionalheight?: number

Optionalmin_width?: number

Optionalmin_height?: number

Optionalmax_width?: number

Optionalmax_height?: number

Optionalunit?: DimensionUnit

Optionalresponsive?: { width: boolean; height: boolean }

Optionalaspect_ratio?: string

Pattern

role: string

parameters_from_format_id: true

Optionalassets

Optionaldelivery

Optionalsupported_macros

Optionalinput_format_ids

Deprecated

Optionaloutput_format_ids

Deprecated

Optionalformat_card

Type Declaration

format_id: FormatReferenceStructuredObject

manifest: {}

Optionalaccessibility

Type Declaration

wcag_level: WCAGLevel

Optionalrequires_accessible_assets?: boolean

Optionalsupported_disclosure_positions

Optionaldisclosure_capabilities

Type Declaration

position: DisclosurePosition

persistence: DisclosurePersistence[]

Optionalformat_card_detailed

Type Declaration

format_id: FormatReferenceStructuredObject

manifest: {}

Optionalreported_metrics

Optionalpricing_options

Deprecated

Optionalcanonical

Optionalcanonical_parameters

Settings

On This Page

`Optional`description

`Optional`example_url

`Optional`accepts_parameters

`Optional`renders

dimensions: {
width?: number;
height?: number;
min_width?: number;
min_height?: number;
max_width?: number;
max_height?: number;
unit?: DimensionUnit;
responsive?: { width: boolean; height: boolean };
aspect_ratio?: string;
}

`Optional`width?: number

`Optional`height?: number

`Optional`min_width?: number

`Optional`min_height?: number

`Optional`max_width?: number

`Optional`max_height?: number

`Optional`unit?: DimensionUnit

`Optional`responsive?: { width: boolean; height: boolean }

`Optional`aspect_ratio?: string

`Optional`assets

`Optional`delivery

`Optional`supported_macros

`Optional`input_format_ids

`Optional`output_format_ids

`Optional`format_card

`Optional`accessibility

`Optional`requires_accessible_assets?: boolean

`Optional`supported_disclosure_positions

`Optional`disclosure_capabilities

`Optional`format_card_detailed

`Optional`reported_metrics

`Optional`pricing_options

`Optional`canonical

`Optional`canonical_parameters