adcontextprotocol · bokelley · Sep 1, 2025 · Sep 1, 2025 · Sep 1, 2025 · Sep 1, 2025
diff --git a/.github/workflows/schema-validation.yml b/.github/workflows/schema-validation.yml
@@ -0,0 +1,27 @@
+name: JSON Schema Validation
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  schema-validation:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Use Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '20'
+        cache: 'npm'
+
+    - name: Install dependencies
+      run: npm ci
+
+    - name: Run all tests
+      run: npm test
diff --git a/.husky/pre-commit b/.husky/pre-commit
@@ -0,0 +1,3 @@
+#!/bin/sh
+
+npm run precommit
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -42,6 +42,58 @@ Implementation details can be mentioned as:
 - Write for an audience implementing the protocol, not using a specific implementation
 - Keep examples generic and illustrative
 
+## JSON Schema Maintenance
+
+### Schema-Documentation Consistency
+
+**GOLDEN RULE**: Documentation and JSON schemas MUST always be synchronized.
+
+### When to Update Schemas
+
+Update JSON schemas whenever you:
+- Add, remove, or rename any fields in task requests/responses
+- Change field types, constraints, or validation rules
+- Modify enum values (like status types, delivery types, etc.)
+- Add new data models or modify existing core objects
+- Change required vs optional field specifications
+
+### Schema Update Checklist
+
+When making documentation changes:
+1. ✅ Identify affected schemas in `static/schemas/v1/`
+2. ✅ Update request schemas (if changing task parameters)
+3. ✅ Update response schemas (if changing response structure)  
+4. ✅ Update core data models (if changing object definitions)
+5. ✅ Update enum schemas (if changing allowed values)
+6. ✅ Verify cross-references (`$ref` links) are still valid
+7. ✅ Test schema validation with example data
+8. ✅ Update schema descriptions to match documentation
+
+### Schema Location Map
+
+- **Task Requests**: `static/schemas/v1/media-buy/` or `static/schemas/v1/signals/`
+- **Core Objects**: `static/schemas/v1/core/`
+- **Enums**: `static/schemas/v1/enums/` 
+- **Registry**: `static/schemas/v1/index.json`
+
+### Validation Testing
+
+Always validate schemas work correctly:
+```bash
+# Use online JSON schema validators or
+# Node.js with ajv library to test schemas
+# Schemas are accessible locally at http://localhost:3000/schemas/v1/ when running npm run start
+```
+
+### Local Schema Access
+
+When running `npm run start`, all JSON schemas are accessible at:
+- Schema registry: `http://localhost:3000/schemas/v1/index.json`
+- Core schemas: `http://localhost:3000/schemas/v1/core/{name}.json`
+- Task schemas: `http://localhost:3000/schemas/v1/media-buy/{task}-{request|response}.json`
+- Signal schemas: `http://localhost:3000/schemas/v1/signals/{task}-{request|response}.json`
+- Enum schemas: `http://localhost:3000/schemas/v1/enums/{name}.json`
+
 ## Code Standards
 
 ### TypeScript/JavaScript
@@ -68,6 +120,11 @@ Implementation details can be mentioned as:
 2. Update all related documentation when making changes
 3. Ensure examples are consistent across docs
 4. Remove version numbers while in v1 development
+5. **CRITICAL: JSON Schema Synchronization**
+   - When changing any task parameters, data models, or field definitions in docs, **ALWAYS update the corresponding JSON schemas** in `static/schemas/v1/`
+   - When updating JSON schemas, **ALWAYS verify the documentation matches** the schema definitions
+   - Check both request/response schemas AND core data model schemas for affected changes
+   - Update the schema registry (`static/schemas/v1/index.json`) if adding/removing schemas
 
 ### Code Changes
 1. Follow existing patterns

diff --git a/docs/intro.md b/docs/intro.md
@@ -21,6 +21,8 @@ AdCP uses a task-first architecture where core advertising tasks (like creating
 - **A2A (Agent2Agent Protocol)**: For complex workflows and agent collaboration
 - **REST API**: Coming soon for traditional integrations
 
+All tasks and data models are defined with JSON schemas for validation and client code generation.
+
 ## Protocol Architecture
 
 AdCP operates at multiple layers, providing a clean separation between the business roles, orchestration layer, and technical execution:

diff --git a/docs/media-buy/tasks/add_creative_assets.md b/docs/media-buy/tasks/add_creative_assets.md
@@ -7,6 +7,10 @@ sidebar_position: 4
 
 Upload creative assets and assign them to packages. This task includes validation, policy review, and format adaptation suggestions.
 
+
+**Request Schema**: [`/schemas/v1/media-buy/add-creative-assets-request.json`](/schemas/v1/media-buy/add-creative-assets-request.json)  
+**Response Schema**: [`/schemas/v1/media-buy/add-creative-assets-response.json`](/schemas/v1/media-buy/add-creative-assets-response.json)
+
 ## Request Parameters
 
 | Parameter | Type | Required | Description |

diff --git a/docs/media-buy/tasks/create_media_buy.md b/docs/media-buy/tasks/create_media_buy.md
@@ -7,6 +7,10 @@ sidebar_position: 3
 
 Create a media buy from selected packages. This task handles the complete workflow including validation, approval if needed, and campaign creation.
 
+
+**Request Schema**: [`/schemas/v1/media-buy/create-media-buy-request.json`](/schemas/v1/media-buy/create-media-buy-request.json)  
+**Response Schema**: [`/schemas/v1/media-buy/create-media-buy-response.json`](/schemas/v1/media-buy/create-media-buy-response.json)
+
 ## Request Parameters
 
 | Parameter | Type | Required | Description |

diff --git a/docs/media-buy/tasks/get_media_buy_delivery.md b/docs/media-buy/tasks/get_media_buy_delivery.md
@@ -7,6 +7,10 @@ sidebar_position: 6
 
 Retrieve comprehensive delivery metrics and performance data for reporting.
 
+
+**Request Schema**: [`/schemas/v1/media-buy/get-media-buy-delivery-request.json`](/schemas/v1/media-buy/get-media-buy-delivery-request.json)  
+**Response Schema**: [`/schemas/v1/media-buy/get-media-buy-delivery-response.json`](/schemas/v1/media-buy/get-media-buy-delivery-response.json)
+
 ## Request Parameters
 
 | Parameter | Type | Required | Description |

diff --git a/docs/media-buy/tasks/get_products.md b/docs/media-buy/tasks/get_products.md
@@ -4,6 +4,10 @@ sidebar_position: 1
 ---
 # get_products
 Discover available advertising products based on campaign requirements, using natural language briefs or structured filters.
+
+**Request Schema**: [`/schemas/v1/media-buy/get-products-request.json`](/schemas/v1/media-buy/get-products-request.json)  
+**Response Schema**: [`/schemas/v1/media-buy/get-products-response.json`](/schemas/v1/media-buy/get-products-response.json)
+
 ## Request Parameters
 
 | Parameter | Type | Required | Description |

diff --git a/docs/media-buy/tasks/list_creative_formats.md b/docs/media-buy/tasks/list_creative_formats.md
@@ -7,6 +7,10 @@ sidebar_position: 2
 
 Discover all supported creative formats in the system.
 
+
+**Request Schema**: [`/schemas/v1/media-buy/list-creative-formats-request.json`](/schemas/v1/media-buy/list-creative-formats-request.json)  
+**Response Schema**: [`/schemas/v1/media-buy/list-creative-formats-response.json`](/schemas/v1/media-buy/list-creative-formats-response.json)
+
 ## Request Parameters
 
 | Parameter | Type | Required | Description |

diff --git a/docs/media-buy/tasks/update_media_buy.md b/docs/media-buy/tasks/update_media_buy.md
@@ -7,6 +7,10 @@ sidebar_position: 7
 
 Update campaign and package settings. This task supports partial updates and handles any required approvals.
 
+
+**Request Schema**: [`/schemas/v1/media-buy/update-media-buy-request.json`](/schemas/v1/media-buy/update-media-buy-request.json)  
+**Response Schema**: [`/schemas/v1/media-buy/update-media-buy-response.json`](/schemas/v1/media-buy/update-media-buy-response.json)
+
 ## Request Parameters
 
 | Parameter | Type | Required | Description |

diff --git a/docs/reference/data-models.md b/docs/reference/data-models.md
@@ -11,6 +11,8 @@ Core data structures used throughout AdCP.
 
 Represents available advertising inventory.
 
+**JSON Schema**: [`/schemas/v1/core/product.json`](/schemas/v1/core/product.json)
+
 ```typescript
 interface Product {
   product_id: string;
@@ -34,6 +36,8 @@ interface Product {
 
 Represents a purchased advertising campaign.
 
+**JSON Schema**: [`/schemas/v1/core/media-buy.json`](/schemas/v1/core/media-buy.json)
+
 ```typescript
 interface MediaBuy {
   media_buy_id: string;
@@ -51,6 +55,8 @@ interface MediaBuy {
 
 A specific product within a media buy (line item).
 
+**JSON Schema**: [`/schemas/v1/core/package.json`](/schemas/v1/core/package.json)
+
 ```typescript
 interface Package {
   package_id: string;
@@ -67,6 +73,8 @@ interface Package {
 
 Uploaded creative content.
 
+**JSON Schema**: [`/schemas/v1/core/creative-asset.json`](/schemas/v1/core/creative-asset.json)
+
 ```typescript
 interface CreativeAsset {
   creative_id: string;
@@ -85,6 +93,8 @@ interface CreativeAsset {
 
 Audience targeting criteria.
 
+**JSON Schema**: [`/schemas/v1/core/targeting.json`](/schemas/v1/core/targeting.json)
+
 ```typescript
 interface Targeting {
   geo_country_any_of?: string[];
@@ -102,6 +112,8 @@ interface Targeting {
 
 Standard response structure (MCP).
 
+**JSON Schema**: [`/schemas/v1/core/response.json`](/schemas/v1/core/response.json)
+
 ```typescript
 interface Response {
   message: string;           // Human-readable summary
@@ -116,6 +128,8 @@ interface Response {
 
 Standard error structure.
 
+**JSON Schema**: [`/schemas/v1/core/error.json`](/schemas/v1/core/error.json)
+
 ```typescript
 interface Error {
   code: string;
@@ -129,15 +143,27 @@ interface Error {
 ## Common Enums
 
 ```typescript
-// Delivery Types
+// Delivery Types - Schema: /schemas/v1/enums/delivery-type.json
 type DeliveryType = 'guaranteed' | 'non_guaranteed';
 
-// Media Buy Status
+// Media Buy Status - Schema: /schemas/v1/enums/media-buy-status.json
 type MediaBuyStatus = 'pending_activation' | 'active' | 'paused' | 'completed';
 
-// Creative Status  
+// Creative Status - Schema: /schemas/v1/enums/creative-status.json
 type CreativeStatus = 'processing' | 'approved' | 'rejected' | 'pending_review';
 
-// Pacing
+// Pacing - Schema: /schemas/v1/enums/pacing.json
 type Pacing = 'even' | 'asap' | 'front_loaded';
-```
+```
+
+**Additional Enum Schemas**:
+- [`delivery-type.json`](/schemas/v1/enums/delivery-type.json) - guaranteed vs non_guaranteed
+- [`media-buy-status.json`](/schemas/v1/enums/media-buy-status.json) - Media buy lifecycle status
+- [`package-status.json`](/schemas/v1/enums/package-status.json) - Package lifecycle status
+- [`creative-status.json`](/schemas/v1/enums/creative-status.json) - Creative review status
+- [`pacing.json`](/schemas/v1/enums/pacing.json) - Budget pacing strategies
+- [`frequency-cap-scope.json`](/schemas/v1/enums/frequency-cap-scope.json) - Frequency cap scope
+
+## JSON Schema Registry
+
+View all available schemas: [`/schemas/v1/index.json`](/schemas/v1/index.json)
diff --git a/docs/signals/tasks/activate_signal.md b/docs/signals/tasks/activate_signal.md
@@ -7,6 +7,9 @@ title: activate_signal
 
 **Task**: Activate a signal for use on a specific platform/account.
 
+**Request Schema**: [`/schemas/v1/signals/activate-signal-request.json`](/schemas/v1/signals/activate-signal-request.json)  
+**Response Schema**: [`/schemas/v1/signals/activate-signal-response.json`](/schemas/v1/signals/activate-signal-response.json)
+
 The `activate_signal` task handles the entire activation lifecycle, including:
 - Initiating the activation request
 - Monitoring activation progress

diff --git a/docs/signals/tasks/get_signals.md b/docs/signals/tasks/get_signals.md
@@ -7,6 +7,9 @@ title: get_signals
 
 **Task**: Discover signals based on description, with details about where they are deployed.
 
+**Request Schema**: [`/schemas/v1/signals/get-signals-request.json`](/schemas/v1/signals/get-signals-request.json)  
+**Response Schema**: [`/schemas/v1/signals/get-signals-response.json`](/schemas/v1/signals/get-signals-response.json)
+
 The `get_signals` task returns both signal metadata and real-time deployment status across platforms, allowing agents to understand availability and guide the activation process.
 
 ## Request Parameters

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -12,7 +12,12 @@
     "serve": "docusaurus serve",
     "write-translations": "docusaurus write-translations",
     "write-heading-ids": "docusaurus write-heading-ids",
-    "typecheck": "tsc"
+    "typecheck": "tsc",
+    "test:schemas": "node tests/schema-validation.test.js",
+    "test:examples": "node tests/example-validation-simple.test.js",
+    "test": "npm run test:schemas && npm run test:examples && npm run typecheck",
+    "precommit": "npm test",
+    "prepare": "husky"
   },
   "dependencies": {
     "@docusaurus/core": "3.8.1",
@@ -29,7 +34,10 @@
     "@docusaurus/module-type-aliases": "3.8.1",
     "@docusaurus/tsconfig": "3.8.1",
     "@docusaurus/types": "3.8.1",
-    "typescript": "~5.6.2"
+    "typescript": "~5.6.2",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "husky": "^9.0.11"
   },
   "browserslist": {
     "production": [