Data Models

Data Models

Core data structures used throughout AdCP.

Product

Represents available advertising inventory.

JSON Schema: https://adcontextprotocol.org/schemas/v1/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/v1/core/media-buy.json

interface MediaBuy {
  media_buy_id: string;
  status: 'pending_activation' | 'active' | 'paused' | 'completed';
  promoted_offering: string;
  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/v1/core/package.json

interface Package {
  package_id: string;
  product_id: string;
  budget: number;
  impressions?: number;
  targeting_overlay?: Targeting;
  creative_assignments?: CreativeAssignment[];
  status: 'draft' | 'active' | 'paused' | 'completed';
}

Creative Asset

Uploaded creative content.

JSON Schema: https://adcontextprotocol.org/schemas/v1/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/v1/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/v1/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/v1/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/v1/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/v1/enums/delivery-type.json
type DeliveryType = 'guaranteed' | 'non_guaranteed';

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

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

// Pacing - Schema: /schemas/v1/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
• package-status.json - Package 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/v1/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/v1/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/v1/)
• 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/v1/index.json