Module `adcp.types.domains.trusted_match`

Types the AdCP trusted_match schemas declare.

Importing from the domain says which variant you mean, where the flat adcp.types namespace can only bind one class per name:

from adcp.types.domains.trusted_match import <Type>

A type this domain declares in more than one schema is not here: import it from its own schema's module, adcp.types.domains.trusted_match.<schema>. Nothing here is renamed.

Auto-generated from the generated domain tree. DO NOT EDIT MANUALLY. Generation date: 2026-10-04 18:45:11 UTC

Sub-modules

adcp.types.domains.trusted_match.available_package
adcp.types.domains.trusted_match.context_match_request
adcp.types.domains.trusted_match.context_match_response
adcp.types.domains.trusted_match.error
adcp.types.domains.trusted_match.identity_match_request
adcp.types.domains.trusted_match.identity_match_response
adcp.types.domains.trusted_match.offer
adcp.types.domains.trusted_match.offer_price
adcp.types.domains.trusted_match.provider_context_match_response
adcp.types.domains.trusted_match.provider_identity_match_response
adcp.types.domains.trusted_match.provider_registration
adcp.types.domains.trusted_match.publisher_targeting_kv_config
adcp.types.domains.trusted_match.publisher_tmpx_config
adcp.types.domains.trusted_match.tmpx_chunk

Classes

class ArtifactRef (**data: Any)

Expand source code

class ArtifactRef(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    type: Annotated[
        Type,
        Field(
            description="Identifier type. 'url' for web pages, 'url_hash' for URL-addressable content the publisher prefers not to share directly (buyer matches against pre-crawled index), 'eidr' for film/TV (EIDR DOI), 'gracenote' for music/TV (Gracenote TMS ID), 'isrc' for music recordings (International Standard Recording Code), 'gtin' for products (Global Trade Item Number — UPC, EAN, ISBN-13), 'rss_guid' for podcast episodes (RSS GUID), 'isbn' for books, 'custom' for publisher-defined identifiers."
        ),
    ]
    value: Annotated[
        str,
        Field(
            description="The identifier value. For 'url': the canonical content URL — MUST NOT contain user-specific path segments, query parameters, or fragments; use 'url_hash' when the publisher prefers not to reveal the URL. For 'url_hash': Blake3 hash of the canonicalized URL, base64-encoded (canonicalization: strip scheme, strip www./m./amp. prefixes, lowercase, strip trailing slash, strip query params and fragments). For 'eidr': the EIDR DOI (e.g., '10.5240/xxxx'). For 'gracenote': the Gracenote TMS ID (e.g., 'SH032541890000'). For 'isrc': the ISRC code (e.g., 'USRC17607839'). For 'gtin': the GTIN (e.g., '00012345678905'). For 'rss_guid': the episode GUID from the RSS feed. For 'isbn': the ISBN (e.g., '978-0-123456-78-9'). For 'custom': a publisher-defined identifier."
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var type : Type
var value : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Attestation (**data: Any)

Expand source code

class Attestation(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    issuer: Annotated[
        brand_ref.BrandReference,
        Field(
            description='Attestation authority / identity issuer, referenced as a vendor BrandRef (e.g. {"domain": "world.org"}) — the same vendor-reference shape AdCP uses for measurement and signals vendors. The issuer\'s canonical domain is the anchor; brand.json hosting is optional. `scheme` selects the verifier version within the issuer.'
        ),
    ]
    scheme: Annotated[
        str,
        Field(
            description='Proof scheme and version, e.g. "world_id_v4". Selects how `proof` is verified.'
        ),
    ]
    relying_party_id: Annotated[
        str | None,
        Field(
            description="Relying-party id the proof was minted for. The receiver checks this against the relying_party_id's published owner (brand.json `identity_relying_parties[]`) so a forwarded proof cannot be replayed under a different owner."
        ),
    ] = None
    action: Annotated[
        str | None,
        Field(
            description='Issuer action/scope the proof was bound to (e.g. "humanity-check-for-ads").'
        ),
    ] = None
    claims: Annotated[
        list[attestation_claim.AttestationClaim],
        Field(
            description='Claims this attestation establishes. Closed, issuer-agnostic set.',
            max_length=16,
            min_length=1,
        ),
    ]
    verification_level: Annotated[
        VerificationLevel | None,
        Field(
            description='Credential strength (e.g. World ID Orb = biometric unique-human; Device = weaker; Document = passport/NFC).'
        ),
    ] = None
    signal_binding: Annotated[
        str | None,
        Field(
            description='Hash of the signal the proof commits to. The receiver MUST verify it matches the context the receiver expects (e.g. a buyer-issued nonce or the request_id) and that the attestation is within its freshness window; this, plus nullifier-reuse tracking, is the replay defense.'
        ),
    ] = None
    proof: Annotated[
        dict[str, Any],
        Field(
            description="Scheme-specific verifiable proof material. Opaque to this schema; validated by the scheme's verifier. MUST carry only scheme-defined verification material — never page context or additional user identifiers."
        ),
    ]
    expires_at: Annotated[
        AwareDatetime | None,
        Field(description='Attestation validity horizon. Receivers MUST reject when past.'),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var action : str | None
var claims : list[AttestationClaim]
var expires_at : pydantic.types.AwareDatetime | None
var issuer : BrandReference
var model_config
var proof : dict[str, typing.Any]
var relying_party_id : str | None
var scheme : str
var signal_binding : str | None
var verification_level : VerificationLevel | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AvailablePackage (**data: Any)

Expand source code

class AvailablePackage(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    package_id: Annotated[str, Field(description='Unique identifier for the package')]
    media_buy_id: Annotated[str, Field(description='Media buy that this package belongs to')]
    seller_agent: Annotated[
        seller_agent_ref.SellerAgentReference,
        Field(
            description="The seller agent that owns this package. `agent_url` MUST match one of `authorized_agents[].url` in the publisher's adagents.json authoritative for every property this package may serve. Providers SHOULD validate at sync time and reject mismatches with `seller_not_authorized`. Cached alongside the package and used for offer attribution, per-seller observability, and dispute resolution — not for request-time filtering."
        ),
    ]
    format_ids: Annotated[
        list[format_id.FormatReferenceStructuredObject] | None,
        Field(
            deprecated=True,
            description='Deprecated in AdCP 3.2; removed in AdCP 4.0. Legacy named-format identifiers eligible for this package. Use canonical `format_options`.',
        ),
    ] = None
    format_options: Annotated[
        list[package_format_snapshot.PackageFormatSnapshot] | None,
        Field(
            description='Immutable seller-resolved PackageFormatSnapshots eligible for this package. A sender projects this field only when the Trusted Match transport profile supports the highest AdCP release version of every field in every snapshot. It MUST NOT strip an unsupported selector or digest field from a snapshot; for an older or version-unknown provider, omit the entire contract-bearing snapshot and do not claim production-path evidence from a legacy projection.',
            min_length=1,
        ),
    ] = None
    catalogs: Annotated[
        list[catalog.Catalog] | None,
        Field(
            description="The buyer's catalogs attached to this package, with selectors (ids, gtins, tags, category, query) scoping which items are in play. References synced catalogs by catalog_id. The provider resolves items from its cached copy."
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var catalogs : list[Catalog] | None
var format_ids : list[FormatReferenceStructuredObject] | None
var format_options : list[PackageFormatSnapshot18 | PackageFormatSnapshot19 | PackageFormatSnapshot20 | PackageFormatSnapshot21 | PackageFormatSnapshot22 | PackageFormatSnapshot23 | PackageFormatSnapshot24 | PackageFormatSnapshot25 | PackageFormatSnapshot26 | PackageFormatSnapshot27 | PackageFormatSnapshot28 | PackageFormatSnapshot29 | PackageFormatSnapshot30 | PackageFormatSnapshot31 | PackageFormatSnapshot32 | PackageFormatSnapshot33] | None
var media_buy_id : str
var model_config
var package_id : str
var seller_agent : SellerAgentReference

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Code (*args, **kwds)

Expand source code

class Code(StrEnum):
    invalid_request = 'invalid_request'
    unknown_package = 'unknown_package'
    seller_not_authorized = 'seller_not_authorized'
    rate_limited = 'rate_limited'
    timeout = 'timeout'
    internal_error = 'internal_error'
    provider_unavailable = 'provider_unavailable'

Enum where members are also (and must be) strings

Ancestors

enum.StrEnum
builtins.str
enum.ReprEnum
enum.Enum

Class variables

var internal_error
var invalid_request
var provider_unavailable
var rate_limited
var seller_not_authorized
var timeout
var unknown_package

class Consent (**data: Any)

Expand source code

class Consent(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    gdpr: Annotated[
        StrictBool | None, Field(description='Whether GDPR applies to this request.')
    ] = None
    tcf_consent: Annotated[
        str | None, Field(description='IAB TCF v2.2 consent string. Present when gdpr is true.')
    ] = None
    gpp: Annotated[str | None, Field(description='IAB Global Privacy Platform string.')] = None
    us_privacy: Annotated[
        str | None,
        Field(
            deprecated=True,
            description='US Privacy string (CCPA). Deprecated in favor of GPP but still widely used.',
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var gdpr : bool | None
var gpp : str | None
var model_config
var tcf_consent : str | None
var us_privacy : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ContextMatchRequest (**data: Any)

Expand source code

class ContextMatchRequest(AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='forbid',
    )
    field_schema: Annotated[
        AnyUrl | None,
        Field(
            alias='$schema', description='Optional schema URI for validation. Ignored at runtime.'
        ),
    ] = None
    type: Annotated[
        Literal['context_match_request'],
        Field(description='Message type discriminator for deserialization.'),
    ] = 'context_match_request'
    protocol_version: Annotated[
        str | None,
        Field(
            description='TMP protocol version. Allows receivers to handle semantic differences across versions.'
        ),
    ] = '1.0'
    request_id: Annotated[
        str,
        Field(
            description='Unique request identifier. MUST NOT correlate with any identity match request_id.'
        ),
    ]
    property_rid: Annotated[
        UUID,
        Field(
            description='Property catalog UUID (UUID v7). Globally unique, stable identifier assigned by the property catalog. The primary key for TMP matching and property list targeting.'
        ),
    ]
    property_id: Annotated[
        property_id_1.PropertyId | None,
        Field(
            description="Publisher's human-readable property slug (e.g., 'cnn_homepage'). Optional when property_rid is present. Useful for logging and debugging."
        ),
    ] = None
    property_type: Annotated[
        property_type_1.PropertyType, Field(description='Type of the publisher property')
    ]
    placement_id: Annotated[
        str,
        Field(
            description="Placement identifier from the publisher's placement registry in adagents.json. Identifies where on the property this ad opportunity exists. One placement per request."
        ),
    ]
    seller_agent_url: Annotated[
        AnyUrl,
        Field(
            description="API endpoint URL of the seller agent issuing this request. The provider uses this to resolve the active package set it has synced for this seller; when `package_ids` is omitted, evaluation occurs against that full set. If `seller_agent_url` does not match any seller the provider has synced packages for, the provider MUST return an empty offer set — it MUST NOT fall back to another seller's active set. The value identifies the asking seller, is identical for every user on a given placement, and carries no user identity, so it neither varies the request per user nor weakens the context/identity decorrelation boundary. Compared using the AdCP URL canonicalization rules, not byte-equality — see docs/reference/url-canonicalization. Consistent with `seller_agent_url` on the identity match request, `seller_agent.agent_url` on `AvailablePackage`, and `agent_url` in `adagents.json`."
        ),
    ]
    artifact: Annotated[
        artifact_1.Artifact | None,
        Field(
            description='Full content artifact adjacent to this ad opportunity. Same schema used for content standards evaluation. The publisher sends the artifact when they want the buyer to evaluate the full content. Contractual protections govern buyer use. TEE deployment upgrades contractual trust to cryptographic verification. Because the router fans out to multiple buyer agents, publishers MUST NOT include bearer tokens, service-account credentials, or signed URLs in this artifact. Routers MUST remove every asset `access` object and remove or replace every credential-bearing asset `url` before forwarding; only public asset URLs that recipients can resolve independently may remain.'
        ),
    ] = None
    artifact_refs: Annotated[
        list[ArtifactRef] | None,
        Field(
            description='Public content references adjacent to this ad opportunity. Each artifact identifies content via a public identifier the buyer can resolve independently — no private registry sync required.',
            max_length=20,
            min_length=1,
        ),
    ] = None
    geo: Annotated[
        Geo | None,
        Field(
            description='Coarse geographic location of the viewer. Publisher controls granularity — country is sufficient for regulatory compliance and volume filtering, region or metro helps with campaign targeting and valuation. Coarsened to prevent user identification: no postcode, no coordinates. All fields optional.'
        ),
    ] = None
    context_signals: Annotated[
        ContextSignals | None,
        Field(
            description="Pre-computed classifier outputs for the content environment. Use when the publisher wants to provide privacy-reduced context without sharing content or public references. Can supplement artifact_refs or replace them entirely. Ephemeral content that many users encounter (a trending query, a syndicated segment) is shared content; one user's turn or query is not. For non-public content attributable to a single user or session, only the field-specific privacy-reduced outputs permitted below may be sent. Raw content MUST NOT be included. The publisher is the classifier and privacy boundary."
        ),
    ] = None
    package_ids: Annotated[
        list[str] | None,
        Field(
            description='Restrict evaluation to specific packages. When omitted, the provider evaluates all eligible packages for this placement (the common case). MUST NOT vary by user — the same package_ids must be sent for every user on a given placement. User-dependent filtering leaks identity into the context path.',
            max_length=500,
            min_length=1,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var artifact : Artifact | None
var artifact_refs : list[ArtifactRef] | None
var context_signals : ContextSignals | None
var field_schema : pydantic.networks.AnyUrl | None
var geo : Geo | None
var model_config
var package_ids : list[str] | None
var placement_id : str
var property_id : PropertyId | None
var property_rid : uuid.UUID
var property_type : PropertyType
var protocol_version : str | None
var request_id : str
var seller_agent_url : pydantic.networks.AnyUrl
var type : Literal['adcp.types.domains.trusted_match.context_match_request']

Inherited members

AdcpVersionEnvelope:
- model_dump
- model_dump_json
- model_summary

class ContextMatchResponseProviderRouter (**data: Any)

Expand source code

class ContextMatchResponseProviderRouter(AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    type: Annotated[
        Literal['context_match_response'],
        Field(
            description='Message type discriminator for deserialization. Same const as the router→publisher variant so decoders can key off type before dispatching on hop shape.'
        ),
    ] = 'context_match_response'
    request_id: Annotated[
        str, Field(description='Echoed request identifier from the context match request.')
    ]
    offers: Annotated[
        list[offer.Offer],
        Field(
            description='Offers from this provider, one per activated package. An empty array means no packages matched. For simple activation, each offer has just package_id. For richer responses, offers include brand, price, summary, and creative manifest.'
        ),
    ]
    cache_ttl: Annotated[
        SchemaInt | None,
        Field(
            description="Optional override for the router's default 5-minute response cache TTL, in seconds. When present, the router MUST use this value instead of its default. Set to 0 to disable caching.",
            ge=0,
            le=86400,
        ),
    ] = None
    signals: Annotated[
        Signals | None,
        Field(
            description="Provider-origin response-level signals. Targeting pairs use the provider's local key vocabulary; the router preserves and attributes them rather than passing them through as flattened publisher targeting."
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

Class variables

var cache_ttl : int | None
var model_config
var offers : list[adcp.types._forward_compat._ReadbackOffer]
var request_id : str
var signals : Signals | None
var type : Literal['adcp.types.domains.trusted_match.context_match_response']

Instance variables

var adcp_major_version : int | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes
-----=
msg: The deprecation message to be emitted.
wrapped_property: The property instance if the deprecated field is a computed field, or None.
field_name: The name of the field being deprecated.

Inherited members

AdcpVersionEnvelope:
- model_dump
- model_dump_json
- model_summary

class ContextMatchResponseRouterPublisher (**data: Any)

Expand source code

class ContextMatchResponseRouterPublisher(AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    type: Annotated[
        Literal['context_match_response'],
        Field(description='Message type discriminator for deserialization.'),
    ] = 'context_match_response'
    request_id: Annotated[
        str, Field(description='Echoed request identifier from the context match request.')
    ]
    offers: Annotated[
        list[offer.Offer],
        Field(
            description='Offers collected across the provider fan-out, one per activated package. An empty array means no packages matched. For simple activation, each offer has just package_id. For richer responses, offers include brand, price, summary, and creative manifest.'
        ),
    ]
    signals: Annotated[
        Signals | None,
        Field(
            description='Merged non-keyed response-level signals. Provider-local targeting pairs do not pass through this object; the router emits them only in signals_by_provider.'
        ),
    ] = None
    signals_by_provider: Annotated[
        dict[Annotated[str, StringConstraints(pattern=r'^[A-Za-z0-9_]+$', min_length=1, max_length=64)], SignalsByProvider]
        | None,
        Field(
            description="Router-authored map of provider targeting pairs, keyed by the publisher-assigned provider_id from provider registration. For every provider response containing a non-empty signals.targeting_kvs list, the router copies the complete list unchanged into that provider's bucket. The router derives the map key from its registration and MUST ignore or reject provider-supplied signals_by_provider data. A provider with no targeting pairs is omitted. Publishers resolve each (provider_id, key) tuple to a local ad-server destination and drop tuples that have no local mapping.",
            min_length=1,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

Class variables

var model_config
var offers : list[adcp.types._forward_compat._ReadbackOffer]
var request_id : str
var signals : Signals | None
var signals_by_provider : dict[str, SignalsByProvider] | None
var type : Literal['adcp.types.domains.trusted_match.context_match_response']

Instance variables

var adcp_major_version : int | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes
-----=
msg: The deprecation message to be emitted.
wrapped_property: The property instance if the deprecated field is a computed field, or None.
field_name: The name of the field being deprecated.

Inherited members

AdcpVersionEnvelope:
- model_dump
- model_dump_json
- model_summary

class ContextSignals (**data: Any)

Expand source code

class ContextSignals(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    topics: Annotated[
        list[str] | None,
        Field(
            description="Content topic identifiers. Use IAB Content Taxonomy 3.0 IDs (e.g., '632' for Food & Drink) when taxonomy_id is 7, or bounded human-readable category labels (e.g., 'cooking.pasta') for custom taxonomies. For non-public content attributable to a single user or session, publishers MUST use standardized taxonomy identifiers or bounded custom category labels; custom topic strings MUST NOT reproduce distinctive verbatim phrasing and MUST NOT include PII or uniquely identifying details.",
            max_length=50,
        ),
    ] = None
    taxonomy_source: Annotated[
        str | None,
        Field(
            description="Organization that defines the topic taxonomy. Use 'iab' for IAB Content Taxonomy. Publishers may use other values for custom taxonomies."
        ),
    ] = 'iab'
    taxonomy_id: Annotated[
        SchemaInt | None,
        Field(
            description='Taxonomy version within the source. For IAB, follows the AdCOM cattax enum: 7 = Content Taxonomy 3.0. Default: 7.'
        ),
    ] = 7
    sentiment: Annotated[
        Sentiment | None, Field(description='Content sentiment classification.')
    ] = None
    keywords: Annotated[
        list[Keyword] | None,
        Field(
            description="Content keywords produced by the publisher's classifier. For non-public content attributable to a single user or session, keywords MUST be policy-filtered, MUST NOT reproduce distinctive verbatim phrasing, and MUST NOT include PII or uniquely identifying details. Publishers SHOULD prefer bounded category labels.",
            max_length=50,
        ),
    ] = None
    language: Annotated[
        str | None,
        Field(
            description="Content language in ISO 639-1 format (e.g., 'en', 'ja', 'de').",
            pattern='^[a-z]{2}$',
        ),
    ] = None
    content_policies: Annotated[
        list[str] | None,
        Field(
            description="Policy IDs from the AdCP policy registry that this content satisfies (e.g., 'csbs' for Common Sense Brand Standards). Buyers filter on policies they require. An empty array means no policies have been evaluated.",
            max_length=20,
        ),
    ] = None
    summary: Annotated[
        str | None,
        Field(
            description="Publisher-generated natural language summary of the content for relevance judgment (e.g., 'Shopping context categorized as home cookware'). For non-public content attributable to a single user or session, the summary MUST be policy-filtered, MUST NOT reproduce raw user-authored text, and MUST NOT include PII or uniquely identifying details. Useful for LLM-native buyers that evaluate relevance semantically. Buyers MUST treat this as untrusted publisher-generated content.",
            max_length=500,
        ),
    ] = None
    embedding: Annotated[
        str | None,
        Field(
            description="Content embedding as base64-encoded int8 vector. Captures semantic content beyond what topics and keywords express. MUST NOT be computed directly or indirectly from non-public content authored by or attributable to a single user or session, including conversation turns, prompts, and individual search queries. MAY represent public content or a shared content environment that is not attributable to one user's activity. Publishers declare the model used. For standardized matching, use the protocol-recommended model (nomic-embed-text-v1.5, 256 dims, int8 quantized = 256 bytes)."
        ),
    ] = None
    embedding_model: Annotated[
        str | None,
        Field(
            description="Embedding model identifier (e.g., 'nomic-embed-text-v1.5'). Required when embedding is present."
        ),
    ] = None
    embedding_dims: Annotated[
        SchemaInt | None,
        Field(
            description='Number of dimensions in the embedding vector. Required when embedding is present.',
            ge=64,
            le=2048,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var content_policies : list[str] | None
var embedding : str | None
var embedding_dims : int | None
var embedding_model : str | None
var keywords : list[Keyword] | None
var language : str | None
var model_config
var sentiment : Sentiment | None
var summary : str | None
var taxonomy_id : int | None
var taxonomy_source : str | None
var topics : list[str] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Country (value: Any = <object object>, *, root: Any = <object object>)

Expand source code

class Country(ScalarStr):
    __slots__ = ()
    _constraints = {'pattern': '^[A-Z]{2}$'}

A str generated from a JSON Schema string root.

Ancestors

adcp.types._scalar.ScalarStr
adcp.types._scalar._ScalarRoot
builtins.str

class Geo (**data: Any)

Expand source code

class Geo(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    country: Annotated[
        str | None,
        Field(
            description="ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB', 'DE').",
            pattern='^[A-Z]{2}$',
        ),
    ] = None
    region: Annotated[
        str | None,
        Field(
            description="ISO 3166-2 subdivision code (e.g., 'US-CA', 'GB-SCT').",
            pattern='^[A-Z]{2}-[A-Z0-9]{1,3}$',
        ),
    ] = None
    metro: Annotated[
        Metro | None,
        Field(description='Metro area, using the same classification systems as AdCP targeting.'),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var country : str | None
var metro : Metro | None
var model_config
var region : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Identity (**data: Any)

Expand source code

class Identity(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    user_token: Annotated[
        str,
        Field(
            description='Opaque token from an identity provider (ID5, LiveRamp, UID2) or publisher-generated. Buyer may map to internal identity graph but cannot reverse to PII.'
        ),
    ]
    uid_type: Annotated[
        uid_type_1.UidType,
        Field(
            description='Type of the user identifier. Tells the buyer which identity graph to resolve against, avoiding trial-and-error matching.'
        ),
    ]
    attestation: Annotated[
        Attestation | None,
        Field(
            description="Optional verifiable proof ABOUT this identity (e.g. World ID proof-of-personhood and/or age). The receiver MUST verify it (see conformance) and MUST treat an absent-or-unverifiable attestation as 'no attestation' — never as an asserted-true claim. Issuer-agnostic: World ID is the first scheme; mDL / VC-style issuers use the same shape. Receivers MUST bound attestation size to prevent DoS."
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var attestation : Attestation | None
var model_config
var uid_type : UidType
var user_token : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class IdentityMatchRequest (**data: Any)

Expand source code

class IdentityMatchRequest(AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='forbid',
    )
    field_schema: Annotated[
        AnyUrl | None,
        Field(
            alias='$schema', description='Optional schema URI for validation. Ignored at runtime.'
        ),
    ] = None
    type: Annotated[
        Literal['identity_match_request'],
        Field(description='Message type discriminator for deserialization.'),
    ] = 'identity_match_request'
    protocol_version: Annotated[
        str | None,
        Field(
            description='TMP protocol version. Allows receivers to handle semantic differences across versions.'
        ),
    ] = '1.0'
    request_id: Annotated[
        str,
        Field(
            description='Unique request identifier. MUST NOT correlate with any context match request_id.'
        ),
    ]
    seller_agent_url: Annotated[
        AnyUrl,
        Field(
            description="API endpoint URL of the seller agent issuing this request. The buyer's identity-match service uses this to resolve the active package set it has registered for this seller; when `package_ids` is omitted, evaluation occurs against that full set. If `seller_agent_url` does not match any seller for which the buyer has registered active packages, the buyer MUST return an empty `eligible_package_ids` set — it MUST NOT fall back to evaluating against another seller's active set. Compared using the AdCP URL canonicalization rules, not byte-equality — see docs/reference/url-canonicalization. Consistent with `seller_agent.agent_url` on `AvailablePackage` and `agent_url` in `adagents.json`."
        ),
    ]
    identities: Annotated[
        list[Identity],
        Field(
            description='Identity tokens for the user, each tagged with its type. Publishers SHOULD include every token they have available — the buyer resolves on whichever graph matches. Entry order is not semantically significant; buyers use their own preference order when multiple entries resolve. Duplicate `(uid_type, user_token)` pairs MUST NOT appear; routers MAY reject or dedupe. `maxItems: 3` matches the TMPX plaintext budget (~120 bytes after HPKE overhead fits three 32-byte tokens); exceeding it forces buyer-side truncation.',
            max_length=3,
            min_length=1,
        ),
    ]
    consent: Annotated[
        Consent | None,
        Field(
            description='Privacy consent signals. Buyers in regulated jurisdictions MUST NOT process the user token without consent information.'
        ),
    ] = None
    package_ids: Annotated[
        list[str] | None,
        Field(
            description="Optional. When omitted, the buyer evaluates eligibility against the full set of active packages it has registered for `seller_agent_url`. When provided, the composition of `package_ids` MUST be statistically independent of the current placement — sending only the page-specific subset would let the buyer correlate Identity Match with Context Match by comparing package sets. Two acceptable modes: (a) **all-active** — include every active package this buyer has at this publisher; (b) **fuzzed** — include a random sample of active packages, optionally padded with synthetic non-existent IDs, drawn from a distribution that does not depend on the current placement. The buyer's silent-drop behavior on unknown IDs (specified below) is what makes synthetic-ID padding safe — they do not affect the response shape and cannot leak registry membership. When both `seller_agent_url` and `package_ids` are present, the buyer evaluates against the intersection of its registered active set and `package_ids`; IDs in `package_ids` that the buyer has not registered for this seller MUST be silently ignored (not surfaced as errors) to avoid leaking registry membership back to the publisher.",
            min_length=1,
        ),
    ] = None
    country: Annotated[
        str | None,
        Field(
            description='ISO 3166-1 alpha-2 country code. Routing directive for the TMP Router — used to select the correct regional provider. The router MUST strip this field before forwarding the request to the buyer agent. Not an identity signal.',
            pattern='^[A-Z]{2}$',
        ),
    ] = None
    sealed_credentials: Annotated[
        list[SealedCredential] | None,
        Field(
            description='Optional HPKE-sealed credentials addressed to specific audiences — the network-as-RP ("issuer-as-RP"/Mechanism B) carrier. Each payload is opaque to the publisher, who relays it untouched; the inner plaintext is an `attestation` (see identities[].attestation) scoped to the audience\'s relying party. Reuses the TMPX envelope format. Router handling (normative — see docs/trusted-match/specification.mdx): the router forwards each entry only to the provider that owns its `audience_kid` (not broadcast), folds `sealed_credentials` into the per-provider re-signature canonical bytes so an injected/swapped blob breaks the signature, and includes a `sealed_credentials_hash` in the dedup cache key. Receivers decrypt only entries whose `audience_kid` they hold a key for and ignore the rest. Receivers MUST bound count and size to prevent DoS amplification.',
            max_length=8,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var consent : Consent | None
var country : str | None
var field_schema : pydantic.networks.AnyUrl | None
var identities : list[Identity]
var model_config
var package_ids : list[str] | None
var protocol_version : str | None
var request_id : str
var sealed_credentials : list[SealedCredential] | None
var seller_agent_url : pydantic.networks.AnyUrl
var type : Literal['adcp.types.domains.trusted_match.identity_match_request']

Inherited members

AdcpVersionEnvelope:
- model_dump
- model_dump_json
- model_summary

class IdentityMatchResponseProviderRouter (**data: Any)

Expand source code

class IdentityMatchResponseProviderRouter(AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    type: Annotated[
        Literal['identity_match_response'],
        Field(
            description='Message type discriminator for deserialization. Same const as the router→publisher variant so publisher-facing decoders can key off type before dispatching on shape.'
        ),
    ] = 'identity_match_response'
    request_id: Annotated[
        str, Field(description='Echoed request identifier from the identity match request.')
    ]
    eligible_package_ids: Annotated[
        list[str],
        Field(
            description='Package IDs the user is eligible for. Packages not listed are ineligible.'
        ),
    ]
    serve_window_sec: Annotated[
        SchemaInt,
        Field(
            description="Per-package single-shot fcap window, in seconds. After serving the user one impression on each eligible package within this window, the publisher MUST re-query Identity Match before serving from those packages again. Not a router response cache TTL — it is a buyer-asserted serve throttle. Multi-impression frequency caps are handled separately by the buyer's impression tracker. Maximum 300.",
            ge=1,
            le=300,
        ),
    ]
    tmpx_chunks: Annotated[
        list[tmpx_chunk.TmpxChunk] | None,
        Field(
            description="Ordered TMPX chunk/value pairs this identity agent mints. Each entry names the provider-local `slot_id` the value fills (from the provider's registered `tmpx_slots` in provider-registration.json). Ordered-prefix invariant: a response that carries fewer chunks than the provider registered MUST emit an ordered prefix of the registered `tmpx_slots` — routers MUST NOT reorder or fill gaps. The router MUST validate this contract before forwarding: if the provider has no `tmpx_slots` registration, or if the chunk `slot_id` sequence is not an exact non-empty ordered prefix of the registered list (duplicate, reordered, sparse, or unregistered slot IDs), the router MUST drop that provider's chunks atomically and MUST NOT forward them into `tmpx_providers`. Cap of 2 chunks in v1 aligned with the GAM macro-slot budget; the cap MAY rise without a shape change. Omitted when this provider mints no TMPX (e.g. no eligible packages).",
            max_length=2,
            min_length=1,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

Class variables

var eligible_package_ids : list[str]
var model_config
var request_id : str
var serve_window_sec : int
var tmpx_chunks : list[TmpxChunk] | None
var type : Literal['adcp.types.domains.trusted_match.identity_match_response']

Inherited members

AdcpVersionEnvelope:
- model_dump
- model_dump_json
- model_summary

class IdentityMatchResponse (**data: Any)

Expand source code

class IdentityMatchResponseRouterPublisher(AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    type: Annotated[
        Literal['identity_match_response'],
        Field(description='Message type discriminator for deserialization.'),
    ] = 'identity_match_response'
    request_id: Annotated[
        str, Field(description='Echoed request identifier from the identity match request')
    ]
    eligible_package_ids: Annotated[
        list[str],
        Field(
            description='Package IDs the user is eligible for. Packages not listed are ineligible.'
        ),
    ]
    serve_window_sec: Annotated[
        SchemaInt,
        Field(
            description="Per-package single-shot fcap window, in seconds. After serving the user one impression on each eligible package within this window, the publisher MUST re-query Identity Match before serving from those packages again. This is NOT a router response cache TTL — it is a buyer-asserted serve throttle. Multi-impression frequency caps are handled separately by the buyer's impression tracker, which writes cap-fire events to the IdentityMatch cap-state store at the boundary regardless of this window. Maximum 300 — longer windows reduce IdentityMatch load but coarsen fcap granularity below what most campaigns require.",
            ge=1,
            le=300,
        ),
    ]
    tmpx: Annotated[
        str | None,
        Field(
            deprecated=True,
            description='DEPRECATED in favor of tmpx_providers. Routers MAY continue to populate this field for back-compat with consumers that only know the single-token shape; when both fields are present, tmpx_providers is authoritative. Single HPKE-encrypted exposure token containing the resolved user identity tokens. Wire format: kid.base64url_nopad(ciphertext) — unpadded base64url per RFC 4648 section 5 (no = characters). Publishers MUST treat this value as opaque pass-through data. Removed in 4.0.',
        ),
    ] = None
    tmpx_providers: Annotated[
        dict[Annotated[str, StringConstraints(pattern=r'^[A-Za-z0-9_]+$', min_length=1, max_length=64)], TmpxProviders] | None,
        Field(
            description="Router-populated: ordered TMPX chunk/value pairs grouped by the originating identity provider's `provider_id`. Each entry's `chunks[]` is a copy of the provider's emitted `tmpx_chunks` list, in the same order. Each chunk carries a provider-local `slot_id` (from the provider's registered `tmpx_slots`) and an opaque URL-safe `value`; the publisher's deployment configuration (see publisher-tmpx-config.json) resolves each `(provider_id, slot_id)` pair to the ad-server macro name, targeting key, VAST substitution, or play-log field for that surface. The protocol carries values and attribution only. Required by router conformance when any identity provider emitted TMPX in this request; collapsing per-provider tokens into a single string loses attribution and breaks per-provider impression accounting. Map keys MUST match the provider_id charset registered in provider-registration.json (enforced by `propertyNames`). Publishers MUST NOT parse, decode, or transform any chunk's `value` — each is an opaque URL-safe wire string substituted verbatim into the mapped destination."
        ),
    ] = None

    @model_validator(mode='after')
    def _validate_tmpx_provider_ids(self) -> IdentityMatchResponseRouterPublisher:
        if self.tmpx_providers is None:
            return self
        invalid = [
            provider_id
            for provider_id in self.tmpx_providers
            if not _PROVIDER_ID_PATTERN.fullmatch(provider_id)
        ]
        if invalid:
            raise ValueError('tmpx_providers keys must be valid provider_id values')
        return self

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

Class variables

var eligible_package_ids : list[str]
var model_config
var request_id : str
var serve_window_sec : int
var tmpx : str | None
var tmpx_providers : dict[str, TmpxProviders] | None
var type : Literal['adcp.types.domains.trusted_match.identity_match_response']

class IdentityMatchResponseRouterPublisher (**data: Any)

Expand source code

class IdentityMatchResponseRouterPublisher(AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    type: Annotated[
        Literal['identity_match_response'],
        Field(description='Message type discriminator for deserialization.'),
    ] = 'identity_match_response'
    request_id: Annotated[
        str, Field(description='Echoed request identifier from the identity match request')
    ]
    eligible_package_ids: Annotated[
        list[str],
        Field(
            description='Package IDs the user is eligible for. Packages not listed are ineligible.'
        ),
    ]
    serve_window_sec: Annotated[
        SchemaInt,
        Field(
            description="Per-package single-shot fcap window, in seconds. After serving the user one impression on each eligible package within this window, the publisher MUST re-query Identity Match before serving from those packages again. This is NOT a router response cache TTL — it is a buyer-asserted serve throttle. Multi-impression frequency caps are handled separately by the buyer's impression tracker, which writes cap-fire events to the IdentityMatch cap-state store at the boundary regardless of this window. Maximum 300 — longer windows reduce IdentityMatch load but coarsen fcap granularity below what most campaigns require.",
            ge=1,
            le=300,
        ),
    ]
    tmpx: Annotated[
        str | None,
        Field(
            deprecated=True,
            description='DEPRECATED in favor of tmpx_providers. Routers MAY continue to populate this field for back-compat with consumers that only know the single-token shape; when both fields are present, tmpx_providers is authoritative. Single HPKE-encrypted exposure token containing the resolved user identity tokens. Wire format: kid.base64url_nopad(ciphertext) — unpadded base64url per RFC 4648 section 5 (no = characters). Publishers MUST treat this value as opaque pass-through data. Removed in 4.0.',
        ),
    ] = None
    tmpx_providers: Annotated[
        dict[Annotated[str, StringConstraints(pattern=r'^[A-Za-z0-9_]+$', min_length=1, max_length=64)], TmpxProviders] | None,
        Field(
            description="Router-populated: ordered TMPX chunk/value pairs grouped by the originating identity provider's `provider_id`. Each entry's `chunks[]` is a copy of the provider's emitted `tmpx_chunks` list, in the same order. Each chunk carries a provider-local `slot_id` (from the provider's registered `tmpx_slots`) and an opaque URL-safe `value`; the publisher's deployment configuration (see publisher-tmpx-config.json) resolves each `(provider_id, slot_id)` pair to the ad-server macro name, targeting key, VAST substitution, or play-log field for that surface. The protocol carries values and attribution only. Required by router conformance when any identity provider emitted TMPX in this request; collapsing per-provider tokens into a single string loses attribution and breaks per-provider impression accounting. Map keys MUST match the provider_id charset registered in provider-registration.json (enforced by `propertyNames`). Publishers MUST NOT parse, decode, or transform any chunk's `value` — each is an opaque URL-safe wire string substituted verbatim into the mapped destination."
        ),
    ] = None

    @model_validator(mode='after')
    def _validate_tmpx_provider_ids(self) -> IdentityMatchResponseRouterPublisher:
        if self.tmpx_providers is None:
            return self
        invalid = [
            provider_id
            for provider_id in self.tmpx_providers
            if not _PROVIDER_ID_PATTERN.fullmatch(provider_id)
        ]
        if invalid:
            raise ValueError('tmpx_providers keys must be valid provider_id values')
        return self

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

Class variables

var eligible_package_ids : list[str]
var model_config
var request_id : str
var serve_window_sec : int
var tmpx : str | None
var tmpx_providers : dict[str, TmpxProviders] | None
var type : Literal['adcp.types.domains.trusted_match.identity_match_response']

Inherited members

AdcpVersionEnvelope:
- model_dump
- model_dump_json
- model_summary

class Keyword (value: Any = <object object>, *, root: Any = <object object>)

Expand source code

class Keyword(ScalarStr):
    __slots__ = ()
    _constraints = {'max_length': 100}

A str generated from a JSON Schema string root.

Ancestors

adcp.types._scalar.ScalarStr
adcp.types._scalar._ScalarRoot
builtins.str

class Metro (**data: Any)

Expand source code

class Metro(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    system: Annotated[
        metro_system.MetroAreaSystem,
        Field(description="Metro area classification system (e.g., 'nielsen_dma', 'uk_itl2')."),
    ]
    value: Annotated[
        str, Field(description="Metro code within the system (e.g., '501' for New York DMA).")
    ]

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var system : MetroAreaSystem
var value : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Model (*args, **kwds)

Expand source code

class Model(StrEnum):
    cpm = 'cpm'
    cpc = 'cpc'
    cpcv = 'cpcv'
    cpa = 'cpa'
    flat = 'flat'

Enum where members are also (and must be) strings

Ancestors

enum.StrEnum
builtins.str
enum.ReprEnum
enum.Enum

Class variables

var cpa
var cpc
var cpcv
var cpm
var flat

class Offer (**data: Any)

Expand source code

class Offer(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    package_id: Annotated[str, Field(description='Package identifier from the media buy.')]
    seller_agent: Annotated[
        seller_agent_ref.SellerAgentReference | None,
        Field(
            description="Optional echo of the package's seller agent from sync-time metadata. Provided for publisher-side observability so log pipelines can attribute offers to sellers without round-tripping to the media-buy store. Non-authoritative: the binding on the cached AvailablePackage is source of truth. When omitted, the router MAY stamp this field from its cached package→seller map."
        ),
    ] = None
    brand: Annotated[
        brand_ref.BrandReference | None,
        Field(
            description='Brand for this offer. Required when the product allows dynamic brands (brand selected at match time rather than fixed on the package). For single-brand packages, the brand is already known from the media buy.'
        ),
    ] = None
    price: Annotated[
        offer_price.OfferPrice | None,
        Field(
            description='Price for this offer. Only present when the product supports variable pricing. For fixed-price packages, price is already set on the media buy.'
        ),
    ] = None
    summary: Annotated[
        str | None,
        Field(
            description="Buyer-generated description of the offer, for the publisher to judge relevance. E.g., '50% off Goldenfield mayo — recipe integration'. The publisher (or their AI assistant) uses this to decide whether the offer fits the context."
        ),
    ] = None
    creative_manifest: Annotated[
        creative_manifest_1.CreativeManifest | None,
        Field(
            description='Full creative details, inline. When present, the publisher has everything needed to render. Inline for small creatives (markdown, product card). For large creatives (VAST, video), the manifest references external assets via URLs.'
        ),
    ] = None
    creative_data: Annotated[
        dict[str, str] | None,
        Field(
            description="Optional free-form string enhancements for dynamic creative rendering, such as sponsor labels and promotion codes. The map has no protocol-level key registry or required keys: meanings are package-local, receivers MUST ignore unknown keys, and a missing key MUST NOT make an otherwise renderable offer fail. Required renderable content belongs in creative_manifest assets, so creative_data may complement but never replace a manifest's required assets. This is not ad-server macro substitution or attribution tracking; tracker URLs belong in creative_manifest assets and per-user exposure tracking uses TMPX."
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var brand : BrandReference | None
var creative_data : dict[str, str] | None
var creative_manifest : CreativeManifest | None
var model_config
var package_id : str
var price : OfferPrice | None
var seller_agent : SellerAgentReference | None
var summary : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class OfferPrice (**data: Any)

Expand source code

class OfferPrice(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    amount: Annotated[
        StrictFloat, Field(description='Price amount in the specified currency', ge=0.0)
    ]
    currency: Annotated[
        str | None, Field(description='ISO 4217 currency code', pattern='^[A-Z]{3}$')
    ] = 'USD'
    model: Annotated[Model, Field(description='Pricing model for this offer')]

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var amount : float
var currency : str | None
var model : Model
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PublisherTargetingKvMapping (**data: Any)

Expand source code

class PublisherTargetingKvMapping(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    targeting_kv_mapping: Annotated[
        dict[Annotated[str, StringConstraints(pattern=r'^[A-Za-z0-9_]+$', min_length=1, max_length=64)], dict[str, str]],
        Field(
            description="Map from the publisher-assigned `provider_id` to that provider's key-to-destination mapping for this surface. Outer keys use the `provider_id` charset from provider-registration.json. Inner keys are exact provider-local targeting keys from `signals_by_provider[provider_id].targeting_kvs`; no separator, prefix, or case normalization is applied. Values are publisher-local ad-server targeting destinations. At serve time, the publisher applies a mapping only when both the provider and key are own properties of their respective maps. Missing providers and missing keys are dropped independently, without falling back to the provider-local key. Multiple tuples may intentionally map to one destination; each mapped tuple contributes its value and MUST NOT overwrite another value. Publishers SHOULD warn at startup when this map names a provider that is not registered."
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var targeting_kv_mapping : dict[str, dict[str, str]]

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PublisherTmpxMacroMapping (**data: Any)

Expand source code

class PublisherTmpxMacroMapping(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    tmpx_macro_mapping: Annotated[
        dict[
            Annotated[str, StringConstraints(pattern=r'^[A-Za-z0-9_]+$', min_length=1, max_length=64)],
            dict[Annotated[str, StringConstraints(pattern=r'^[a-zA-Z][a-zA-Z0-9_]*$', min_length=1, max_length=64)], str],
        ],
        Field(
            description="Map from `provider_id` to a slot-keyed map of ad-server destinations (macro names, GAM key-values, VAST URL macro tokens, DOOH play-log field identifiers) for that provider on this surface. The inner map's keys are the provider-local `slot_id` values the provider registered in `tmpx_slots` (see provider-registration.json). At serve time, the publisher's adapter reads `tmpx_providers[provider_id].chunks[]` from the identity-match response and, for each chunk, substitutes the chunk's `value` into `tmpx_macro_mapping[provider_id][chunk.slot_id]`. Publishers use the outer map's keys plus the inner map's keys to validate the mapping at startup — every `slot_id` a provider registered in `tmpx_slots` SHOULD have a corresponding entry in that provider's inner map, and publishers SHOULD surface any missing entry as a startup warning so the operator can add it before responses begin carrying the unmapped slot. The exact destination string is publisher-local: GAM adopters typically use uppercase snake-case macro names, VAST surfaces use URL macro tokens, DOOH surfaces use play-log field identifiers. Outer-map key charset matches `provider_id` in provider-registration.json (enforced by `propertyNames`). Inner-map key charset matches `slot_id` in tmpx-chunk.json. When a response carries a `slot_id` for a provider that this mapping has no entry for — the mapping is missing the whole provider, OR the provider is present but the specific `slot_id` is unknown to this surface — the publisher's adapter MUST fail closed for that provider on that impression: none of that provider's chunks are fired into the ad-serving path and the adapter logs a configuration error. Other providers on the same response are unaffected. A `provider_id` absent from this mapping entirely (e.g. a newly onboarded provider not yet trafficked on this surface) is the same case — the adapter drops that provider's chunks on this surface rather than firing them into an unconfigured destination. Startup validation and serve-time fail-closed are two stages of a single rule: the warning at startup is the operator's chance to fix the mapping before the serve-time rule catches the missing slot."
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var tmpx_macro_mapping : dict[str, dict[str, str]]

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SealedCredential (**data: Any)

Expand source code

class SealedCredential(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    audience_kid: Annotated[
        str,
        Field(
            description='Key id identifying the recipient (network / relying party) whose HPKE private key opens `payload`.',
            max_length=128,
        ),
    ]
    payload: Annotated[
        str,
        Field(
            description='HPKE-sealed attestation in the TMPX envelope format: `kid.base64url_nopad(ciphertext)` — unpadded base64url per RFC 4648 §5. Opaque pass-through for the publisher.',
            max_length=8192,
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var audience_kid : str
var model_config
var payload : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Sentiment (*args, **kwds)

Expand source code

class Sentiment(StrEnum):
    positive = 'positive'
    negative = 'negative'
    neutral = 'neutral'
    mixed = 'mixed'

Enum where members are also (and must be) strings

Ancestors

enum.StrEnum
builtins.str
enum.ReprEnum
enum.Enum

Class variables

var mixed
var negative
var neutral
var positive

class SignalsByProvider (**data: Any)

Expand source code

class SignalsByProvider(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    targeting_kvs: TargetingKvs

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var targeting_kvs : TargetingKvs

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Status (*args, **kwds)

Expand source code

class Status(StrEnum):
    active = 'active'
    inactive = 'inactive'
    draining = 'draining'

Enum where members are also (and must be) strings

Ancestors

enum.StrEnum
builtins.str
enum.ReprEnum
enum.Enum

Class variables

var active
var draining
var inactive

class TmpError (**data: Any)

Expand source code

class TmpError(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    type: Annotated[
        Literal['error'], Field(description='Message type discriminator for deserialization.')
    ] = 'error'
    request_id: Annotated[
        str, Field(description='Echoed request identifier from the original request')
    ]
    code: Annotated[
        Code,
        Field(
            description="Machine-readable error code. `seller_not_authorized` is returned by providers at sync time when an AvailablePackage declares a `seller_agent.agent_url` that is not present in the `authorized_agents` list of the publisher's adagents.json for a property the package claims to serve."
        ),
    ]
    message: Annotated[
        str | None, Field(description='Human-readable error description for debugging')
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var code : Code
var message : str | None
var model_config
var request_id : str
var type : Literal['adcp.types.domains.trusted_match.error']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class TmpProviderRegistration1 (**data: Any)

Expand source code

class TmpProviderRegistration1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    provider_id: Annotated[
        str,
        Field(
            description="Stable identifier for this provider registration. Used in logs, metrics, cache keys, as the key in `signals_by_provider` on Context Match responses and `targeting_kv_mapping` in publisher configuration, and as the key in `tmpx_providers` on Identity Match responses and `tmpx_macro_mapping` in publisher configuration. Publishers assign this — it is not the provider's agent_url. Charset is constrained to a safe alphanumeric/underscore set so the value can appear in operational surfaces (logs, metrics, dashboards) without quoting. See publisher-targeting-kv-config.json and publisher-tmpx-config.json.",
            max_length=64,
            min_length=1,
            pattern='^[A-Za-z0-9_]+$',
        ),
    ]
    endpoint: Annotated[
        AnyUrl,
        Field(
            description='Base URL the router calls. The router appends /context for Context Match and /identity for Identity Match. MUST be HTTPS in production, validated against the canonical reserved IPv4 and IPv6 ranges, with the TCP connection pinned to the validated IP (DNS re-resolution alone is insufficient against rebinding). Publishers comparing two provider registrations for the same `endpoint` MUST canonicalize both per the AdCP URL canonicalization rules; two registrations differing only in case, default port, or path-slash collapsing are the same provider. See docs/trusted-match/specification#provider-registration-security, docs/building/implementation/security#webhook-url-validation-ssrf, and docs/reference/url-canonicalization.'
        ),
    ]
    context_match: Annotated[
        Literal[True], Field(description='Provider handles Context Match requests (POST /context).')
    ]
    identity_match: Annotated[
        StrictBool | None,
        Field(description='Provider handles Identity Match requests (POST /identity).'),
    ] = None
    countries: Annotated[
        list[Country] | None,
        Field(
            description="ISO 3166-1 alpha-2 country codes this provider serves. The router filters Identity Match providers by the request's country field. MUST be present and non-empty when identity_match is true.",
            min_length=1,
        ),
    ] = None
    uid_types: Annotated[
        list[uid_type.UidType] | None,
        Field(
            description="Identity types this provider can resolve. The router selects Identity Match providers whose uid_types overlaps with any uid_type in the request's identities array. MUST be present and non-empty when identity_match is true.",
            min_length=1,
        ),
    ] = None
    properties: Annotated[
        list[UUID] | None,
        Field(
            description='Property RIDs (UUID v7) this provider serves. When present, the router only sends requests from these properties to this provider. When absent, the provider serves all properties.',
            min_length=1,
        ),
    ] = None
    timeout_ms: Annotated[
        SchemaInt | None,
        Field(
            description="Per-provider timeout in milliseconds. The router skips this provider if it does not respond within this budget. Must be less than or equal to the router's overall latency_budget_ms. The router may further reduce this based on adaptive timeout allocation.",
            ge=5,
            le=5000,
        ),
    ] = 50
    priority: Annotated[
        SchemaInt | None,
        Field(
            description='Provider ordering for Context Match offer conflict resolution. Lower values have higher priority. When two providers return offers for the same package_id (a configuration error), the router keeps the offer from the higher-priority provider; equal priorities are broken by first response received. Identity Match eligibility remains a responder-scoped union because silent omission is not a negative vote. Also used for adaptive timeout allocation — higher-priority providers receive a larger share of the latency budget.',
            ge=0,
        ),
    ] = 0
    tmpx_slots: Annotated[
        list[TmpxSlot] | None,
        Field(
            description='Stable provider-local slot identifiers for the ordered TMPX chunks this provider mints. Slot IDs are opaque provider-namespaced tokens (e.g. `["primary","secondary"]`), NOT ad-server macro names — publishers map `(provider_id, slot_id)` → local destination via `tmpx_macro_mapping` in publisher-tmpx-config.json, so the destination namespace stays publisher-owned and the router never accepts a destination name from an untrusted provider. Distinct providers MAY reuse the same slot_id without collision because publisher lookup is keyed on `(provider_id, slot_id)`. Publishers use this list at startup to validate `tmpx_macro_mapping` covers every slot the provider mints and to detect config drift when the provider\'s slot contract changes. Ordering carries the ordered-prefix invariant: a provider that emits fewer chunks than it registered MUST emit an ordered prefix of this list — chunks map to slots in registration order and MUST NOT be shifted, sparse, or reordered. Cap of 2 slots in v1 aligned with the GAM macro-slot budget; the cap MAY rise without a shape change. A provider that emits TMPX (populates `tmpx_chunks` on its identity-match response) MUST register this list; a provider that does not emit TMPX omits it. Schema cannot enforce that predicate because "emits TMPX" is not schema-visible.',
            max_length=2,
            min_length=1,
        ),
    ] = None
    status: Annotated[
        Status | None,
        Field(
            description='Provider lifecycle status. Active providers receive requests. Inactive providers are skipped entirely. Draining providers stop receiving new requests but in-flight requests complete normally.'
        ),
    ] = Status.active


    @field_validator('endpoint')
    @classmethod
    def _require_https_endpoint(cls, value: AnyUrl) -> AnyUrl:
        if value.scheme != 'https':
            raise ValueError('endpoint must use https')
        return value

    @model_validator(mode='after')
    def _require_identity_match_dimensions(self) -> TmpProviderRegistration1:
        if self.identity_match is True:
            if not self.countries:
                raise ValueError('countries is required when identity_match is true')
            if not self.uid_types:
                raise ValueError('uid_types is required when identity_match is true')
        return self

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context_match : Literal[True]
var countries : list[Country] | None
var endpoint : pydantic.networks.AnyUrl
var identity_match : bool | None
var model_config
var priority : int | None
var properties : list[uuid.UUID] | None
var provider_id : str
var status : Status | None
var timeout_ms : int | None
var tmpx_slots : list[TmpxSlot] | None
var uid_types : list[UidType] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class TmpProviderRegistration2 (**data: Any)

Expand source code

class TmpProviderRegistration2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    provider_id: Annotated[
        str,
        Field(
            description="Stable identifier for this provider registration. Used in logs, metrics, cache keys, as the key in `signals_by_provider` on Context Match responses and `targeting_kv_mapping` in publisher configuration, and as the key in `tmpx_providers` on Identity Match responses and `tmpx_macro_mapping` in publisher configuration. Publishers assign this — it is not the provider's agent_url. Charset is constrained to a safe alphanumeric/underscore set so the value can appear in operational surfaces (logs, metrics, dashboards) without quoting. See publisher-targeting-kv-config.json and publisher-tmpx-config.json.",
            max_length=64,
            min_length=1,
            pattern='^[A-Za-z0-9_]+$',
        ),
    ]
    endpoint: Annotated[
        AnyUrl,
        Field(
            description='Base URL the router calls. The router appends /context for Context Match and /identity for Identity Match. MUST be HTTPS in production, validated against the canonical reserved IPv4 and IPv6 ranges, with the TCP connection pinned to the validated IP (DNS re-resolution alone is insufficient against rebinding). Publishers comparing two provider registrations for the same `endpoint` MUST canonicalize both per the AdCP URL canonicalization rules; two registrations differing only in case, default port, or path-slash collapsing are the same provider. See docs/trusted-match/specification#provider-registration-security, docs/building/implementation/security#webhook-url-validation-ssrf, and docs/reference/url-canonicalization.'
        ),
    ]
    context_match: Annotated[
        StrictBool | None,
        Field(description='Provider handles Context Match requests (POST /context).'),
    ] = None
    identity_match: Annotated[
        Literal[True],
        Field(description='Provider handles Identity Match requests (POST /identity).'),
    ]
    countries: Annotated[
        list[Country] | None,
        Field(
            description="ISO 3166-1 alpha-2 country codes this provider serves. The router filters Identity Match providers by the request's country field. MUST be present and non-empty when identity_match is true.",
            min_length=1,
        ),
    ] = None
    uid_types: Annotated[
        list[uid_type.UidType] | None,
        Field(
            description="Identity types this provider can resolve. The router selects Identity Match providers whose uid_types overlaps with any uid_type in the request's identities array. MUST be present and non-empty when identity_match is true.",
            min_length=1,
        ),
    ] = None
    properties: Annotated[
        list[UUID] | None,
        Field(
            description='Property RIDs (UUID v7) this provider serves. When present, the router only sends requests from these properties to this provider. When absent, the provider serves all properties.',
            min_length=1,
        ),
    ] = None
    timeout_ms: Annotated[
        SchemaInt | None,
        Field(
            description="Per-provider timeout in milliseconds. The router skips this provider if it does not respond within this budget. Must be less than or equal to the router's overall latency_budget_ms. The router may further reduce this based on adaptive timeout allocation.",
            ge=5,
            le=5000,
        ),
    ] = 50
    priority: Annotated[
        SchemaInt | None,
        Field(
            description='Provider ordering for Context Match offer conflict resolution. Lower values have higher priority. When two providers return offers for the same package_id (a configuration error), the router keeps the offer from the higher-priority provider; equal priorities are broken by first response received. Identity Match eligibility remains a responder-scoped union because silent omission is not a negative vote. Also used for adaptive timeout allocation — higher-priority providers receive a larger share of the latency budget.',
            ge=0,
        ),
    ] = 0
    tmpx_slots: Annotated[
        list[TmpxSlot] | None,
        Field(
            description='Stable provider-local slot identifiers for the ordered TMPX chunks this provider mints. Slot IDs are opaque provider-namespaced tokens (e.g. `["primary","secondary"]`), NOT ad-server macro names — publishers map `(provider_id, slot_id)` → local destination via `tmpx_macro_mapping` in publisher-tmpx-config.json, so the destination namespace stays publisher-owned and the router never accepts a destination name from an untrusted provider. Distinct providers MAY reuse the same slot_id without collision because publisher lookup is keyed on `(provider_id, slot_id)`. Publishers use this list at startup to validate `tmpx_macro_mapping` covers every slot the provider mints and to detect config drift when the provider\'s slot contract changes. Ordering carries the ordered-prefix invariant: a provider that emits fewer chunks than it registered MUST emit an ordered prefix of this list — chunks map to slots in registration order and MUST NOT be shifted, sparse, or reordered. Cap of 2 slots in v1 aligned with the GAM macro-slot budget; the cap MAY rise without a shape change. A provider that emits TMPX (populates `tmpx_chunks` on its identity-match response) MUST register this list; a provider that does not emit TMPX omits it. Schema cannot enforce that predicate because "emits TMPX" is not schema-visible.',
            max_length=2,
            min_length=1,
        ),
    ] = None
    status: Annotated[
        Status | None,
        Field(
            description='Provider lifecycle status. Active providers receive requests. Inactive providers are skipped entirely. Draining providers stop receiving new requests but in-flight requests complete normally.'
        ),
    ] = Status.active


    @field_validator('endpoint')
    @classmethod
    def _require_https_endpoint(cls, value: AnyUrl) -> AnyUrl:
        if value.scheme != 'https':
            raise ValueError('endpoint must use https')
        return value

    @model_validator(mode='after')
    def _require_identity_match_dimensions(self) -> TmpProviderRegistration2:
        if self.identity_match is True:
            if not self.countries:
                raise ValueError('countries is required when identity_match is true')
            if not self.uid_types:
                raise ValueError('uid_types is required when identity_match is true')
        return self

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context_match : bool | None
var countries : list[Country] | None
var endpoint : pydantic.networks.AnyUrl
var identity_match : Literal[True]
var model_config
var priority : int | None
var properties : list[uuid.UUID] | None
var provider_id : str
var status : Status | None
var timeout_ms : int | None
var tmpx_slots : list[TmpxSlot] | None
var uid_types : list[UidType] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class TmpxChunk (**data: Any)

Expand source code

class TmpxChunk(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    slot_id: Annotated[
        str,
        Field(
            description="Provider-local slot identifier from the emitting provider's registered `tmpx_slots` (provider-registration.json). Opaque provider-namespaced token; publishers map `(provider_id, slot_id)` → local destination via `tmpx_macro_mapping`. NOT an ad-server macro name.",
            max_length=64,
            min_length=1,
            pattern='^[a-zA-Z][a-zA-Z0-9_]*$',
        ),
    ]
    value: Annotated[
        str,
        Field(
            description="Opaque, URL-safe wire string the publisher substitutes verbatim into the destination the publisher's mapping resolves for this `(provider_id, slot_id)` pair. Publishers MUST NOT parse, decode, or transform this value.",
            max_length=1024,
            min_length=1,
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var slot_id : str
var value : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class TmpxProviders (**data: Any)

Expand source code

class TmpxProviders(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    chunks: Annotated[
        list[tmpx_chunk.TmpxChunk],
        Field(
            description="Ordered TMPX chunks for this provider. Each entry is a `{slot_id, value}` pair copied verbatim from the provider's `tmpx_chunks`. Ordered-prefix invariant: the sequence of `slot_id`s MUST equal an ordered prefix of the provider's registered `tmpx_slots` — publishers MAY reject responses whose slot_ids or ordering diverge. Cap of 2 chunks in v1; the cap MAY rise without a shape change.",
            max_length=2,
            min_length=1,
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var chunks : list[TmpxChunk]
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class TmpxSlot (value: Any = <object object>, *, root: Any = <object object>)

Expand source code

class TmpxSlot(ScalarStr):
    __slots__ = ()
    _constraints = {'max_length': 64, 'min_length': 1, 'pattern': '^[a-zA-Z][a-zA-Z0-9_]*$'}

A str generated from a JSON Schema string root.

Ancestors

adcp.types._scalar.ScalarStr
adcp.types._scalar._ScalarRoot
builtins.str

class Type (*args, **kwds)

Expand source code

class Type(StrEnum):
    url = 'url'
    url_hash = 'url_hash'
    eidr = 'eidr'
    gracenote = 'gracenote'
    isrc = 'isrc'
    gtin = 'gtin'
    rss_guid = 'rss_guid'
    isbn = 'isbn'
    custom = 'custom'

Enum where members are also (and must be) strings

Ancestors

enum.StrEnum
builtins.str
enum.ReprEnum
enum.Enum

Class variables

var custom
var eidr
var gracenote
var gtin
var isbn
var isrc
var rss_guid
var url
var url_hash

class VerificationLevel (*args, **kwds)

Expand source code

class VerificationLevel(StrEnum):
    orb = 'orb'
    device = 'device'
    document = 'document'

Enum where members are also (and must be) strings

Ancestors

enum.StrEnum
builtins.str
enum.ReprEnum
enum.Enum

Class variables

var device
var document
var orb