> ## Documentation Index
> Fetch the complete documentation index at: https://agenticadvertisingorg-snap-format-preview-links.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Models

Core data structures used throughout AdCP.

## Product

Represents available advertising inventory.

**JSON Schema**: [`https://adcontextprotocol.org/schemas/v2/core/product.json`](https://adcontextprotocol.org/schemas/v2/core/product.json)

```typescript theme={null}
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`](https://adcontextprotocol.org/schemas/v2/core/media-buy.json)

```typescript theme={null}
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`](https://adcontextprotocol.org/schemas/v2/core/package.json)

```typescript theme={null}
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`](https://adcontextprotocol.org/schemas/v2/core/creative-asset.json)

```typescript theme={null}
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`](https://adcontextprotocol.org/schemas/v2/core/creative-assignment.json)

```typescript theme={null}
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`](https://adcontextprotocol.org/schemas/v2/core/targeting.json)

```typescript theme={null}
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`](https://adcontextprotocol.org/schemas/v2/core/response.json)

```typescript theme={null}
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`](https://adcontextprotocol.org/schemas/v2/core/error.json)

```typescript theme={null}
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

```typescript theme={null}
// 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`](https://adcontextprotocol.org/schemas/v2/enums/delivery-type.json) - guaranteed vs non\_guaranteed
* [`media-buy-status.json`](https://adcontextprotocol.org/schemas/v2/enums/media-buy-status.json) - Media buy lifecycle status
* [`creative-status.json`](https://adcontextprotocol.org/schemas/v2/enums/creative-status.json) - Creative review status
* [`pacing.json`](https://adcontextprotocol.org/schemas/v2/enums/pacing.json) - Budget pacing strategies
* [`frequency-cap-scope.json`](https://adcontextprotocol.org/schemas/v2/enums/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](https://semver.org/):

* **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:**

```json theme={null}
{
  "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`](https://adcontextprotocol.org/schemas/v2/index.json)