Data Models - AdCP - Ad Context Protocol

Core data structures used throughout AdCP.

Product

Represents available advertising inventory. JSON Schema: https://adcontextprotocol.org/schemas/v2/core/product.json

interface Product {
  product_id: string;
  name: string;
  description: string;
  formats: Format[];
  delivery_type: 'guaranteed' | 'non_guaranteed';
  is_fixed_price: boolean;
  cpm?: number;
  min_spend?: number;
  targeting_capabilities: string[];
  measurement?: {
    type: string;
    attribution: string;
    reporting: string;
  };
}

Media Buy

Represents a purchased advertising campaign. JSON Schema: https://adcontextprotocol.org/schemas/v2/core/media-buy.json

interface MediaBuy {
  media_buy_id: string;
  status: 'pending_activation' | 'active' | 'paused' | 'completed';
  total_budget: number;
  packages: Package[];
  creative_deadline?: string;
  created_at: string;
  updated_at: string;
}

Package

A specific product within a media buy (line item). JSON Schema: https://adcontextprotocol.org/schemas/v2/core/package.json

interface Package {
  package_id: string;
  product_id: string;
  budget: number;
  impressions?: number;
  targeting_overlay?: Targeting;
  creative_assignments?: CreativeAssignment[];
  paused?: boolean; // Whether package is paused by buyer (default: false)
}

Creative Asset

Uploaded creative content. JSON Schema: https://adcontextprotocol.org/schemas/v2/core/creative-asset.json

interface CreativeAsset {
  creative_id: string;
  name: string;
  format: string;
  url?: string;
  status: 'processing' | 'approved' | 'rejected' | 'pending_review';
  compliance?: {
    status: string;
    issues?: string[];
  };
}

Creative Assignment

Assignment of a creative asset to a package. JSON Schema: https://adcontextprotocol.org/schemas/v2/core/creative-assignment.json

interface CreativeAssignment {
  creative_id: string;
  weight?: number;  // Delivery weight (0-100)
}

Targeting

Audience targeting criteria. JSON Schema: https://adcontextprotocol.org/schemas/v2/core/targeting.json

interface Targeting {
  geo_country_any_of?: string[];
  geo_region_any_of?: string[];
  audience_segment_any_of?: string[];
  signals?: string[];
  frequency_cap?: {
    suppress_minutes: number;
  };
}

Protocol Response Format

Protocol-level response wrapper (MCP/A2A). JSON Schema: https://adcontextprotocol.org/schemas/v2/core/response.json

interface ProtocolResponse {
  message: string;              // Human-readable summary (protocol level)
  context_id?: string;          // Session continuity (protocol level)
  context?: any;                // initiator-provided context (echoed back)
  data: any;                    // AdCP task-specific response data
}

Note: context is set by the tool initiator on the request and must be carried back unchanged by agents in responses and webhooks. Note: Individual AdCP task schemas contain only the application-level data that goes in the data field of the protocol response. Task-specific errors are included within each task’s response schema, not at the protocol level.

Error

Standard error structure for task-specific errors and warnings. JSON Schema: https://adcontextprotocol.org/schemas/v2/core/error.json

interface Error {
  code: string;              // Error code for programmatic handling
  message: string;           // Human-readable error message
  field?: string;            // Field path (e.g., 'packages[0].targeting')
  suggestion?: string;       // Suggested fix for the error
  retry_after?: number;      // Seconds to wait before retrying
  details?: any;             // Additional task-specific error details
}

Usage: Errors are included as optional arrays in individual task response schemas to handle partial success scenarios, validation failures, and operational warnings specific to each AdCP operation.

Common Enums

// Delivery Types - Schema: /schemas/v2/enums/delivery-type.json
type DeliveryType = 'guaranteed' | 'non_guaranteed';

// Media Buy Status - Schema: /schemas/v2/enums/media-buy-status.json
type MediaBuyStatus = 'pending_activation' | 'active' | 'paused' | 'completed';

// Creative Status - Schema: /schemas/v2/enums/creative-status.json
type CreativeStatus = 'processing' | 'approved' | 'rejected' | 'pending_review';

// Pacing - Schema: /schemas/v2/enums/pacing.json
type Pacing = 'even' | 'asap' | 'front_loaded';

Additional Enum Schemas:

delivery-type.json - guaranteed vs non_guaranteed
media-buy-status.json - Media buy lifecycle status
creative-status.json - Creative review status
pacing.json - Budget pacing strategies
frequency-cap-scope.json - Frequency cap scope

Schema Versioning

AdCP uses path-based versioning where the schema URL indicates the version, not individual fields in requests or responses.

Version in Schema Paths

The version is embedded in the schema URL path:

/schemas/v2/media-buy/create-media-buy-request.json
/schemas/v2/media-buy/create-media-buy-request.json

Single Source of Truth: The schema registry at /schemas/v2/index.json contains the current version number.

Version Format

AdCP uses semantic versioning:

Major (X.y.z): Breaking changes
Minor (x.Y.z): Backward-compatible additions
Patch (x.y.Z): Bug fixes and clarifications

Why Path-Based Versioning?

No redundancy: Version doesn’t need to be repeated in every request/response
Simpler maintenance: No need to update version fields in 30+ schema files
Clearer semantics: The schema you reference IS the version you use
Standard practice: Follows REST/HTTP conventions (version in path, not payload)

Version Negotiation

Client Behavior:

Reference the desired schema version in your implementation (e.g., /schemas/v2/)
The schema path you use determines the version you’re implementing
Check the schema registry’s adcp_version field to confirm compatibility

Server Behavior:

Implement the version indicated by the schema path
Support multiple versions simultaneously by serving different schema paths
Return errors that reference the appropriate schema version

Migration Strategy

Minor Version Updates (1.0.0 → 1.1.0):

Add optional fields or new tasks
Backward compatible - existing clients continue working
Clients can adopt new features at their own pace

Major Version Updates (1.0.0 → 2.0.0):

Breaking changes require client updates
Servers may support multiple major versions during transition
Migration guides provided for breaking changes

JSON Schema Best Practices

Discriminated Unions

AdCP schemas use discriminated unions for type safety. All discriminator fields include explicit type declarations for proper TypeScript code generation. Pattern:

{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "type": { "type": "string", "const": "platform" },
        "platform": { "type": "string" }
      },
      "required": ["type", "platform"]
    },
    {
      "type": "object",
      "properties": {
        "type": { "type": "string", "const": "agent" },
        "agent_url": { "type": "string" }
      },
      "required": ["type", "agent_url"]
    }
  ]
}

Why this matters: Including "type": "string" before "const" enables TypeScript generators to produce proper literal types (e.g., Literal["platform"]) instead of Any, improving type safety and IDE autocomplete. Examples in AdCP schemas:

deployment.json: type: "platform" | "agent"
sub-asset.json: asset_kind: "media" | "text"
vast-asset.json: delivery_type: "url" | "inline"
preview-render.json: output_format: "url" | "html" | "both"

JSON Schema Registry

View all available schemas: https://adcontextprotocol.org/schemas/v2/index.json

​Product

​Media Buy

​Package

​Creative Asset

​Creative Assignment

​Targeting

​Protocol Response Format

​Error

​Common Enums

​Schema Versioning

​Version in Schema Paths

​Version Format

​Why Path-Based Versioning?

​Version Negotiation

​Migration Strategy

​JSON Schema Best Practices

​Discriminated Unions

​JSON Schema Registry