← Articles

UCP Schema Validation CI: Automated Quality Gates for Agentic Commerce

Three pull requests from sakinaroufid land today adding comprehensive CI infrastructure for UCP schema validation — automated checks that ensure the specification's JSON schemas stay in sync with the source of truth and that documentation builds don't break silently.

The Author

The Pull Requests

Why Schema Validation Matters

UCP is a schema-driven protocol. The JSON schemas in the repository define the contract between AI agents and commerce providers. When those schemas drift from the canonical source (or from each other), bad things happen:

• Silent breaking changes — A schema update that doesn't regenerate client types
• Documentation/implementation mismatch — Docs show one structure, generated code expects another
• CI false positives — Tests pass against stale schemas while production breaks

Today's PRs address all three failure modes.

What Changed

1. Schema Validation Workflow (PR #230)

A new GitHub Actions workflow that validates the JSON schemas on every push and PR:

name: Schema Validation

on:
  push:
    paths:
      - 'schema/**'
  pull_request:
    paths:
      - 'schema/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate JSON Schemas
        run: npm run schema:validate

This catches malformed schemas before they merge — no more "the schema is valid JSON but not valid JSON Schema" bugs.

2. Pre-commit Schema Sync Check (PR #231)

A pre-commit hook that verifies generated schemas match the source:

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: schema-sync-check
        name: Check schema generation is in sync
        entry: npm run schema:check-sync
        language: system
        pass_filenames: false

This catches a common mistake: editing a source file that generates schemas, but forgetting to run the generator before committing.

3. Improved Workflow Path Triggers (PR #232)

Updates to the existing CI workflows to trigger on the right file paths:

• Schema changes trigger schema validation
• Documentation changes trigger doc builds
• Code changes trigger tests

Previously, some workflows ran on every commit regardless of what changed. The refined triggers reduce CI time and resource usage while ensuring the right checks run for each change type.

Technical Details

The Schema Generation Pipeline

UCP's schemas follow a generation pipeline:

1. Source definitions — TypeScript or YAML files defining the protocol structures
2. Schema generator — Transforms sources into JSON Schema files
3. Validation — Ensures generated schemas are valid JSON Schema draft-07
4. Client generation — Produces TypeScript types, Python dataclasses, etc.

The new CI infrastructure validates steps 2-3 automatically.

Error Handling Improvements

From the earlier commit (ba636a2 by Daniel Dittenhafer), error handling in the doc build was also improved:

// Before: silent failures
try {
  buildDocs();
} catch (e) {
  // ignored
}

// After: propagate errors
try {
  buildDocs();
} catch (e) {
  console.error('Doc build failed:', e);
  process.exit(1);
}

Combined with the new workflow triggers, this means documentation build failures are now visible in CI.

Why This Matters for UCP Adoption

As more organizations implement UCP, the quality of the specification becomes critical:

• Implementers need trust — When you generate client code from a schema, you need to know that schema is correct
• Breaking changes need visibility — Automated diffing catches unintentional API changes
• Documentation needs accuracy — AI agents (and their developers) rely on docs matching reality

Google's investment in CI infrastructure signals that UCP is moving from "interesting proposal" to "production specification."

What's Next

Looking at the broader UCP repository, several related improvements are in flight:

• Semantic versioning automation for schema changes
• Breaking change detection with automated changelog generation
• Cross-language client generation validation

For protocol designers and implementers, today's PRs represent best practices: automated validation, sync checks, and targeted CI triggers. These patterns apply to any schema-driven API.