Module adcp.types.domains.core.impairment

Classes

class Impairment (**data: Any)

Expand source code

class Impairment(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    impairment_id: Annotated[
        str,
        Field(
            description="Stable identifier for this impairment, used as the notification_id when the impairment fires via webhook. Stable across re-emissions of the same open impairment (e.g., the seller re-fires after the buyer's receiver was down) and across the closing fire that signals resolution. A new impairment for the same resource_id after closure receives a new impairment_id. Distinct from the per-fire idempotency_key issued at the webhook transport layer — see snapshot-and-log Rule 1. Receivers correlate webhook fires to current impairments[] state by impairment_id; receivers suppress duplicate transport-layer retries by idempotency_key. Seeing the same impairment_id with different idempotency_keys is a re-emission signal, not a retry — the buyer should treat it as a notice that something may have been missed."
        ),
    ]
    resource_type: Annotated[
        ResourceType,
        Field(
            description="The kind of upstream dependency that transitioned to an offline state. Values are drawn from the x-entity vocabulary (see core/x-entity-types.json) and identify a buyer-referenced object with its own lifecycle that the seller can take offline. This is the subset of x-entity types for which a media buy's serving depends on the resource — not a new typology, just the impairment-relevant slice."
        ),
    ]
    resource_id: Annotated[
        str,
        Field(
            description="Seller's identifier for the specific resource that transitioned. References the same id space as the corresponding sync_/list_ task responses (e.g., audience_id, creative_id)."
        ),
    ]
    package_ids: Annotated[
        list[str],
        Field(
            description="Packages within this media buy whose delivery is degraded by the impairment. MUST list at least one package — cosmetic effects that do not degrade any package's ability to serve MUST NOT be reported as impairments.",
            min_length=1,
        ),
    ]
    transition: Annotated[
        Transition,
        Field(description='The resource-level status transition that triggered this impairment.'),
    ]
    reason_code: Annotated[
        impairment_reason_code.ImpairmentReasonCode,
        Field(
            description='Categorical reason for the offline transition. Drives buyer-side remediation logic.'
        ),
    ]
    reason: Annotated[
        str | None,
        Field(
            description='Human-readable explanation. Supplements reason_code with seller-specific detail.',
            max_length=500,
        ),
    ] = None
    observed_at: Annotated[
        AwareDatetime,
        Field(
            description='ISO 8601 timestamp when the seller observed the resource transition to its offline state.'
        ),
    ]
    remediation: Annotated[
        str | None,
        Field(
            description='Action the buyer can take to clear the impairment, if any. Free text. Absent when no buyer-side remediation is possible (e.g., seller-initiated withdrawal pending re-publication).',
            max_length=500,
        ),
    ] = None

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 impairment_id : str

var model_config

var observed_at : pydantic.types.AwareDatetime

var package_ids : list[str]

var reason : str | None

var reason_code : ImpairmentReasonCode

var remediation : str | None

var resource_id : str

var resource_type : ResourceType

var transition : Transition

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ResourceType (*args, **kwds)

Expand source code

class ResourceType(StrEnum):
    audience = 'audience'
    creative = 'creative'
    catalog_item = 'catalog_item'
    event_source = 'event_source'
    property = 'property'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var audience

var catalog_item

var creative

var event_source

var property

class Transition (**data: Any)

Expand source code

class Transition(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    from_: Annotated[
        str | None,
        Field(
            alias='from',
            description="Prior status of the resource (e.g., 'ready', 'approved', 'good'). Optional — sellers SHOULD include when known, MAY omit when the resource was discovered already in an offline state (e.g., a property depublished via brand.json crawl with no prior snapshot). Open string at the schema layer because each resource_type has its own serviceable-state vocabulary; the pattern constraint blocks free-form garbage, and the impairment.coherence assertion validates that 'from' is a known serviceable value for the resource_type.",
            pattern='^[a-z][a-z0-9_]*$',
        ),
    ] = None
    to: Annotated[
        impairment_offline_state.ImpairmentOfflineState,
        Field(
            description="Current (offline) status of the resource. Drawn from the resource_type's canonical lifecycle enum; see impairment-offline-state for per-value resource_type pairing. The pairing is validated by impairment.coherence."
        ),
    ]

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 from_ : str | None

var model_config

var to : ImpairmentOfflineState

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary