Skip to content

CHANGELOG.md

Latest commit

 

History

History
270 lines (199 loc) · 10.9 KB

CHANGELOG.md

File metadata and controls

270 lines (199 loc) · 10.9 KB

Changelog

2.2.0

Minor Changes

  • 727463a: Align build_creative with transformation model and consistent naming

    Breaking changes:

    • build_creative now uses creative_manifest instead of source_manifest parameter
    • build_creative request no longer accepts promoted_offerings as a task parameter (must be in manifest assets)
    • preview_creative request no longer accepts promoted_offerings as a task parameter (must be in manifest assets)
    • build_creative response simplified to return just creative_manifest (removed complex nested structure)

    Improvements:

    • Clear transformation model: manifest-in → manifest-out
    • Format definitions drive requirements (e.g., promoted_offerings is a format asset requirement)
    • Consistent naming across build_creative and preview_creative
    • Self-contained manifests that flow through build → preview → sync
    • Eliminated redundancy and ambiguity about where to provide inputs

    This change makes the creative generation workflow much clearer and more consistent. Generative formats that require promoted_offerings should specify it as a required asset in their format definition, and it should be included in the creative_manifest.assets object.

Patch Changes

  • eeb9967: Automate schema version synchronization with package.json

    Implemented three-layer protection to ensure schema registry version stays in sync with package.json:

    1. Auto-staging: update-schema-versions.js now automatically stages changes to git
    2. Verification gate: New verify-version-sync.js script prevents releases when versions don't match
    3. Pre-push validation: Git hook checks version sync before any push

    Also fixed v2.1.0 schema registry version (was incorrectly showing 2.0.0) and removed duplicate creative-manifest entry.

  • 7d0c8c8: Improve documentation visibility and navigation

    Documentation Improvements:

    1. Added Changelog Page

      • Created comprehensive /docs/reference/changelog with v2.1.0 and v2.0.0 release notes
      • Includes developer migration guide with code examples
      • Documents breaking changes and versioning policy
      • Added to sidebar navigation in Reference section

    2. Improved Pricing Documentation Visibility

      • Added Pricing Models to sidebar navigation (Media Buy Protocol > Advanced Topics)
      • Added pricing information callouts to key task documentation
      • Enhanced get_products with pricing_options field description
      • Added missing pricing_option_id field to create_media_buy Package Object
      • Added prominent tip box linking to pricing guide in media-products.md

    3. Added Release Banner

      • Homepage now displays v2.1.0 release announcement with link to changelog
      • Makes new releases immediately visible to documentation readers

    Why These Changes:

    • Users reported difficulty finding changelog and version history
    • Pricing documentation was comprehensive but hidden from navigation
    • Critical fields like pricing_option_id were not documented in API reference
    • Release announcements need better visibility on homepage

    These are documentation-only changes with no code or schema modifications.

2.1.0

Minor Changes

  • ae091dc: Simplify asset schema architecture by separating payload from requirements

    Breaking Changes:

    1. Removed asset_type field from creative manifest wire format

      • Asset payloads no longer include redundant type information
      • Asset types are determined by format specification, not declared in manifest
      • Validation is format-aware using asset_id lookup

    2. Deleted /creative/asset-types/*.json individual schemas

      • 11 duplicate schema files removed (image, video, audio, vast, daast, text, url, html, css, javascript, webhook)
      • Asset type registry now references /core/assets/ schemas directly
      • Schema path changed: /creative/asset-types/image.json → /core/assets/image-asset.json

    3. Removed constraint fields from core asset payloads

      • vast-asset.json: Removed max_wrapper_depth (format constraint, not payload data)
      • text-asset.json: Removed max_length (format constraint, not payload data)
      • webhook-asset.json: Removed fallback_required (format requirement, not asset property)
      • Constraint fields belong in format specification requirements, not asset schemas

    Why These Changes:

    • Format-aware validation: Creative manifests are always validated in the context of their format specification. The format already defines what type each asset_id should be, making asset_type in the payload redundant.
    • Single source of truth: Each asset type now defined once in /core/assets/, eliminating 1,797 lines of duplicate code.
    • Clear separation of concerns: Payload schemas describe data structure; format specifications describe constraints and requirements.
    • Reduced confusion: No more wondering which schema to reference or where to put constraints.

    Migration Guide:

    Code Changes

    // Schema references
- const schema = await fetch('/schemas/v1/creative/asset-types/image.json')
+ const schema = await fetch('/schemas/v1/core/assets/image-asset.json')

// Creative manifest structure (removed asset_type)
{
  "assets": {
    "banner_image": {
-     "asset_type": "image",
      "url": "https://cdn.example.com/banner.jpg",
      "width": 300,
      "height": 250
    }
  }
}

// Validation changes - now format-aware
- // Old: Standalone asset validation
- validate(assetPayload, imageAssetSchema)

+ // New: Format-aware validation
+ const format = await fetchFormat(manifest.format_id)
+ const assetRequirement = format.assets_required.find(a => a.asset_id === assetId)
+ const assetSchema = await fetchAssetSchema(assetRequirement.asset_type)
+ validate(assetPayload, assetSchema)

    Validation Flow

    1. Read format_id from creative manifest
    2. Fetch format specification from format registry
    3. For each asset in manifest:
      • Look up asset_id in format's assets_required
      • If not found → error "unknown asset_id"
      • Get asset_type from format specification
      • Validate asset payload against that asset type's schema
    4. Check all required assets are present
    5. Validate type-specific constraints from format requirements

    Constraint Migration

    Constraints moved from asset schemas to format specification requirements field:

    // Format specification assets_required
{
  "asset_id": "video_file",
  "asset_type": "video",
  "required": true,
  "requirements": {
    "width": 1920,
    "height": 1080,
    "duration_ms": 15000,
+   "max_file_size_bytes": 10485760,
+   "acceptable_codecs": ["h264", "h265"]
  }
}

    These constraints are validated against asset payloads but are not part of the payload schema itself.

Patch Changes

  • 4be4140: Add Ebiquity as founding member

  • f99a4a7: Clarify asset_id usage in creative manifests

    Previously ambiguous: The relationship between asset_id in format definitions and the keys used in creative manifest assets objects was unclear.

    Now explicit:

    • Creative manifest keys MUST exactly match asset_id values from the format's assets_required array
    • asset_role is optional/documentary—not used for manifest construction
    • Added validation guidance: what creative agents should do with mismatched keys

    Example: If a format defines asset_id: "banner_image", your manifest must use:

    {
  "assets": {
    "banner_image": { ... }  // ← Must match asset_id
  }
}

    Changes: Updated creative-manifest.json, format.json schemas and creative-manifests.md documentation.

  • 67d7994: Fix format_id documentation to match schema specification

All notable changes to the AdCP specification will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

2.0.0 - 2025-10-15

Added

  • Production Release: AdCP v2.0.0 is the first production-ready release of the Advertising Context Protocol
  • Media Buy Tasks: Core tasks for advertising workflow
    • get_products - Discover advertising inventory
    • list_creative_formats - Discover supported creative formats
    • create_media_buy - Create advertising campaigns
    • sync_creatives - Synchronize creative assets
    • list_creatives - Query creative library
    • update_media_buy - Update campaign settings
    • get_media_buy_delivery - Retrieve delivery metrics
    • list_authorized_properties - Discover authorized properties
    • provide_performance_feedback - Share performance data
  • Creative Tasks: AI-powered creative generation
    • build_creative - Generate creatives from briefs
    • preview_creative - Generate creative previews
    • list_creative_formats - Discover format specifications
  • Signals Tasks: First-party data integration
    • get_signals - Discover available signals
    • activate_signal - Activate signals for campaigns
  • Standard Formats: Industry-standard creative formats
    • Display formats (banner, mobile, interstitial)
    • Video formats (standard, skippable, stories)
    • Native formats (responsive native)
    • Standard asset types for multi-asset creatives
  • Protocol Infrastructure:
    • JSON Schema validation for all tasks
    • MCP (Model Context Protocol) support
    • A2A (Agent-to-Agent) protocol support
    • Task management with async workflows
    • Human-in-the-loop approval system
  • Documentation: Comprehensive documentation
    • Protocol specification
    • Task reference guides
    • Integration guides for MCP and A2A
    • Standard formats documentation
    • Error handling documentation
  • Version Management:
    • Changesets for automated version management
    • Single source of truth for version (schema registry only)
    • Simplified versioning: version indicated by schema path (/schemas/v1/)

Changed

  • Initial release, no changes from previous versions

Design Decisions

  • Simplified Versioning: Version is maintained only in the schema registry (/schemas/v1/index.json) and indicated by schema path. Individual request/response schemas and documentation do not contain version fields, reducing maintenance burden while maintaining clear version semantics.

Technical Details

  • Schema Version: 2.0.0
  • Standard Formats Version: 1.0.0
  • Protocol Support: MCP, A2A
  • Node Version: >=18.0

Notes

This is the first production-ready release of AdCP. Future releases will follow semantic versioning:

  • Patch versions (2.0.x): Bug fixes and clarifications
  • Minor versions (2.x.0): New features and enhancements (backward compatible)
  • Major versions (x.0.0): Breaking changes

We use Changesets for version management. All changes should include a changeset file.