@adcp/sdk API Reference - v7.9.0
    Preparing search index...

    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[];
    }

    Hierarchy (View Summary)

    Index

    Properties

    format_id name description? example_url? accepts_parameters? renders? assets? delivery? supported_macros? input_format_ids? output_format_ids? format_card? accessibility? supported_disclosure_positions? disclosure_capabilities? format_card_detailed? reported_metrics? pricing_options?

    Properties

    format_id: FormatReferenceStructuredObject
    name: string

    Human-readable format name

    description?: string

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

    example_url?: string

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

    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.

    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')

          ^\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
    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.

    delivery?: {}

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

    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.

    input_format_ids?: FormatReferenceStructuredObject[]

    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. Omit for formats that work from raw assets (images, text, etc.) rather than existing creatives.

    output_format_ids?: FormatReferenceStructuredObject[]

    Array of format IDs that this format can produce as output. When present, indicates this format can build creatives in these output formats (e.g., a multi-publisher template format might produce standard display formats across many publishers). Omit for formats that produce a single fixed output (the format itself).

    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

    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.

    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.

    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

    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

    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.

    pricing_options?: VendorPricingOption[]

    Pricing options for this format. Used by transformation and 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. Ad servers and library-based agents expose pricing on list_creatives instead.

    Settings

    Member Visibility

    On This Page

    Properties