Schema Versioning

Understanding AdCP schema versioning and how to reference schemas in your applications

AdCP uses semantic versioning for schemas with multiple access patterns to balance stability and convenience.

Version Paths

All AdCP schemas are available at multiple paths:

Path Pattern	Example	Updates With	Best For
/schemas/{version}/	/schemas/2.5.0/	Never	Production, SDK generation
/schemas/v{major}.{minor}/	/schemas/v2.5/	Patch releases only	Stable development
/schemas/v{major}/	/schemas/v2/	Minor + patch releases	Active development, docs
/schemas/latest/	/schemas/latest/	All releases	Prototyping only

Exact Version (Recommended for Production)

/schemas/2.5.0/core/product.json

• Pin to specific release - URL never changes
• Guaranteed stability - Schema won’t update unexpectedly
• Best for: Production applications, SDK generation, CI/CD validation

Major Version Alias (Recommended for Documentation)

/schemas/v2/core/product.json

• Tracks latest 2.x release - Automatically updates with minor/patch releases
• Backward compatible - No breaking changes within major version
• Best for: Documentation examples, development, staying current

Minor Version Alias (Recommended for Stable Development)

/schemas/v2.5/core/product.json

• Tracks latest 2.5.x patch - Automatically updates with patch releases only
• More stable than major alias - Only receives bug fixes, no new features
• Backward compatible - No breaking changes within minor version
• Best for: Applications wanting automatic security/bug fixes without new features

Latest Alias (Use with Caution)

/schemas/latest/core/product.json

• Always current - Points to newest release
• May include breaking changes - Can jump major versions
• Best for: Exploration, prototyping, bleeding edge development

Legacy Compatibility (v1)

/schemas/v1/core/product.json

• Backward compatibility - Alias to latest 2.x for existing clients
• Deprecated - Use /schemas/v2/ for new code
• Best for: Maintaining existing integrations during migration

Bundled Schemas (Experimental)

Bundled schemas are experimental and may change or be removed in future releases. If you’re using them, please share your use case so we can better understand requirements.

For tools that don’t support $ref resolution (some API clients, code generators, or desktop applications), AdCP provides bundled schemas with all references resolved inline:

/schemas/2.5.0/bundled/media-buy/create-media-buy-request.json
/schemas/2.5.0/bundled/media-buy/get-products-response.json

What’s Bundled

Bundled schemas are generated for all request/response schemas (*-request.json, *-response.json). These are the “root” schemas that tools validate against. Core data models like product.json are already embedded inside response schemas when bundled, so they don’t need separate bundled versions.

When to Use Bundled Schemas

Use Case	Bundled	Modular
Postman/Insomnia collections	✅	❌ May not resolve refs
Code generators (quicktype, json-schema-to-typescript)	✅ Recommended	⚠️ Depends on tool
IDE autocomplete (VS Code JSON validation)	✅	⚠️ May need configuration
AJV validation with custom resolver	❌	✅ Smaller files
Understanding schema structure	❌	✅ Clear separation

Example: Using Bundled Schemas

// Bundled - self-contained, no ref resolution needed
const schema = await fetch('https://adcp.org/schemas/2.5.0/bundled/media-buy/create-media-buy-request.json');
const validate = ajv.compile(await schema.json());

// Modular - requires $ref resolution
const schema = await fetch('https://adcp.org/schemas/2.5.0/media-buy/create-media-buy-request.json');
// This schema contains $ref to other schemas that must be resolved

Bundled Schema Metadata

Bundled schemas include a _bundled field with generation metadata:

{
  "$id": "/schemas/2.5.0/bundled/core/product.json",
  "title": "Product",
  "_bundled": {
    "generatedAt": "2024-12-17T10:30:00.000Z",
    "note": "This is a bundled schema with all $ref resolved inline..."
  }
}

Choosing the Right Path

For Application Code

// Production - pin exact version
const SCHEMA_VERSION = '2.5.0';
const schema = await fetch(`https://adcp.org/schemas/${SCHEMA_VERSION}/core/product.json`);

// Stable development - track minor version (patch updates only)
const schema = await fetch('https://adcp.org/schemas/v2.5/core/product.json');

// Active development - track major version (minor + patch updates)
const schema = await fetch('https://adcp.org/schemas/v2/core/product.json');

For SDK Generation

Always use exact versions to ensure generated types match your target protocol version:

# TypeScript SDK generation
npx json-schema-to-typescript \
  https://adcp.org/schemas/2.5.0/core/product.json \
  --output types/product.d.ts

# Python SDK generation
datamodel-codegen \
  --url https://adcp.org/schemas/2.5.0/core/product.json \
  --output models/product.py

For Validation

// Validate against specific version
import Ajv from 'ajv';
const ajv = new Ajv();

const schema = await fetch('https://adcp.org/schemas/2.5.0/core/product.json');
const validate = ajv.compile(await schema.json());

if (!validate(data)) {
  console.error('Validation failed:', validate.errors);
}

Client Libraries

AdCP provides official client libraries for JavaScript/TypeScript and Python:

JavaScript/TypeScript

npm install @adcp/client

• NPM: @adcp/client
• GitHub: adcp-client
• Documentation: Quickstart Guide

Python

pip install adcp

• PyPI: adcp
• GitHub: adcp-python
• Documentation: Quickstart Guide

Client libraries automatically handle schema version compatibility. Always use the latest client library version for the best experience.

Schema Updates and Breaking Changes

Within a Major Version (2.x)

Minor and patch updates are backward compatible:

• ✅ New optional fields
• ✅ New enum values (append-only)
• ✅ Documentation improvements
• ✅ Bug fixes in validation

Safe to use: /schemas/v2/ will track these automatically.

Major Version Changes (2.x → 3.x)

Breaking changes require a new major version:

• ⚠️ Removing fields
• ⚠️ Changing field types
• ⚠️ Making optional fields required
• ⚠️ Removing enum values

Requires migration: Must update to /schemas/v3/ explicitly.

Migration Guide

From v1 to v2

If you’re currently using /schemas/v2/:

1. No immediate action required - v1 is an alias to v2
2. Update references when convenient:
   - const schema = await fetch('/schemas/v2/core/product.json');
   + const schema = await fetch('/schemas/v2/core/product.json');
   
3. Consider pinning for production stability:
   const schema = await fetch('/schemas/2.5.0/core/product.json');
   

From Exact Version to Major Alias

If you want to track the latest 2.x:

- const schema = await fetch('/schemas/2.4.0/core/product.json');
+ const schema = await fetch('/schemas/v2/core/product.json');

Trade-off: Automatic updates vs. explicit control.

Best Practices

1. Production Applications

• Pin exact versions in production config
• Test before upgrading to new minor versions
• Review changelogs for each update

2. Development Workflow

• Use major version alias (/schemas/v2/) during development
• Pin exact version before production deployment
• Document version in README and package.json

3. SDK Generation

• Always use exact versions for type generation
• Regenerate types when upgrading protocol versions
• Commit generated files to track changes

4. Documentation and Examples

• Use major version aliases to stay current
• Show exact versions in production examples
• Document compatibility requirements

Version Discovery

Check Current Version

# Get schema registry with version info
curl https://adcp.org/schemas/v2/index.json | jq '.adcp_version'
# Output: "2.5.0"

# Get version from specific release
curl https://adcp.org/schemas/2.5.0/index.json | jq '.adcp_version'
# Output: "2.5.0"

List Available Versions

Check the Release Notes or GitHub Releases for all available versions.

FAQ

Q: Will /schemas/v2/ stop working?

A: No. It’s now a permanent alias to the latest 2.x release for backward compatibility.

Q: Should I use /schemas/latest/?

A: Only for exploration and development. Never in production—it may include breaking changes.

Q: How often do schemas update?

A: Following semantic versioning:

• Patch (2.5.1): Bug fixes, no API changes
• Minor (2.6.0): New features, backward compatible
• Major (3.0.0): Breaking changes

Q: Can I host schemas myself?

A: Yes! Schemas are open source. Clone the repository and serve from your own CDN.

Q: What if a schema URL returns 404?

A: Check that:

1. The version exists (see release notes)
2. The path is correct (check schema registry)
3. You’re using the correct domain (adcp.org or adcontextprotocol.org)

Q: My tool doesn’t support $ref - what should I do?

A: Use the bundled schemas at /schemas/{version}/bundled/. These have all $ref resolved inline and work with any JSON Schema tool. See Bundled Schemas above.

Related Resources

• Release Notes - Version history and migration guides
• CHANGELOG - Detailed technical changes
• GitHub Releases - Download specific versions