> ## 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.

# 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)

<Warning>
  Bundled schemas are experimental and may change or be removed in future releases. If you're using them, please [share your use case](https://github.com/adcontextprotocol/adcp/issues) so we can better understand requirements.
</Warning>

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

```javascript theme={null}
// 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:

```json theme={null}
{
  "$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

```javascript theme={null}
// 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:

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

```javascript theme={null}
// 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 version](https://img.shields.io/npm/v/@adcp/client)](https://www.npmjs.com/package/@adcp/client)

```bash theme={null}
npm install @adcp/client
```

* **NPM**: [@adcp/client](https://www.npmjs.com/package/@adcp/client)
* **GitHub**: [adcp-client](https://github.com/adcontextprotocol/adcp-client)
* **Documentation**: [Quickstart Guide](/dist/docs/2.5.3/quickstart)

### Python

[![PyPI version](https://img.shields.io/pypi/v/adcp)](https://pypi.org/project/adcp/)

```bash theme={null}
pip install adcp
```

* **PyPI**: [adcp](https://pypi.org/project/adcp/)
* **GitHub**: [adcp-python](https://github.com/adcontextprotocol/adcp-python)
* **Documentation**: [Quickstart Guide](/dist/docs/2.5.3/quickstart)

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:
   ```diff theme={null}
   - const schema = await fetch('/schemas/v2/core/product.json');
   + const schema = await fetch('/schemas/v2/core/product.json');
   ```
3. **Consider pinning** for production stability:
   ```javascript theme={null}
   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:

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

```bash theme={null}
# 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](/dist/docs/2.5.3/reference/release-notes) or [GitHub Releases](https://github.com/adcontextprotocol/adcp/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](https://adcp.org/schemas/v2/index.json))
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](#bundled-schemas) above.

## Related Resources

* [Release Notes](/dist/docs/2.5.3/reference/release-notes) - Version history and migration guides
* [CHANGELOG](https://github.com/adcontextprotocol/adcp/blob/main/CHANGELOG.md) - Detailed technical changes
* [GitHub Releases](https://github.com/adcontextprotocol/adcp/releases) - Download specific versions