fix(schema): publish UCP annotated schemas

[igrigorik]

Our contract is that UCP schemas are self-describing. We define and advertise one URL in capability metadata, which agents and servers can fetch and validate against. At the moment, this contract is broken.

  "dev.ucp.shopping.fulfillment": [
    {
      "version": "2026-01-11",
      "spec": "https://ucp.dev/specification/fulfillment",
      "schema": "https://ucp.dev/schemas/shopping/fulfillment.json",  // <~ single schema
      "extends": "dev.ucp.shopping.checkout"
    }
  ]

A schema yields different shapes based on operation (e.g., create vs update vs complete) and direction (request vs response). We encode these rules via ucp_request/ucp_response annotations in our source/* schemas, but then run a preprocessor that splits them into N permutations based on operation × direction (e.g., checkout.create_req.json maps to create + request). The schema URL we advertise in UCP metadata doesn't contain all the necessary information, and we've defined a convention that off-the-shelf schema validators are not aware of and would need to be taught to understand. As is, this makes UCP validation very hard to implement.

Proposed desired state

Deliver self-describing schemas. Keep servers+agents simple: one URL. Handle complexity in shared tooling.

By count and burden: servers > agents > validators. If we require that servers dynamically resolve and return operation-specific schema refs, that's complexity multiplied across every UCP business / implementer. Same for agents, who would need to vary their profile per operation — clunky. We can eliminate and shift all of this complexity into validators: restore the single file contract, a ref to which can be passed in both directions by servers+agents, and lean on UCP-aware tooling.

Actor	Per-op files (today)	Single schema (proposed)
Spec authors	N files per capability (via preprocessor)	1 file
Server implementers	Hardcode operation→URL mapping	Return one URL
Validator	Simple fetch + validate	Resolve annotations
Discovery	Multiple URLs, custom convention	One URL serves all
Readability	Rules scattered across files	Self-documenting

Recommendation

1. Publish source schemas with ucp_request/ucp_response annotations intact
2. Remove the preprocessor and /spec/schemas/ directory
3. Adopt portable validator for linting, resolution, validation.

Prototype validator: ucp-schema

# Lint schemas in CI
ucp-schema lint schemas/

# Resolve to vanilla JSON Schema (for tools that need it)
ucp-schema resolve checkout.json --request --op create

# Validate directly (self-describing from ucp.capabilities)
ucp-schema validate response.json --op read

The validator is written in Rust for portability & re-use. We can use it for our build process, and we can provide it as official binary for validating schemas for capability developers, and for agent+server developers to validate payloads on the wire — see docs on above repo for linting, resolving, validation, etc.

This PR

Big diff, but mostly deletions and simplification of the build pipeline in favor of using the shared ucp-schema validator.

1. Integrates ucp-schema, deprecates Python preprocessor
2. Publishes source schemas with annotations intact (non-breaking: standard validators ignore unknown keywords)
3. Updates CI to use ucp-schema lint + ucp-schema validate

Big picture changes

1. Runtime schema resolution via ucp-schema CLI (main.py)

• Calls ucp-schema resolve during mkdocs build
• Caches resolved schemas per-schema to avoid redundant work
• Detects polymorphic types for correct anchor generation

2. Versioned schema publishing (hooks.py)

• Publishes source schemas to /schemas/{version}/ during build
• Rewrites $id and $ref URLs to include version path
• Sets version field in capability metadata
• Handles date versions (2026-01-26) vs. named versions (draft)

3. CI integration (.github/workflows/docs.yml)

• Installs ucp-schema via cargo install
• Runs ucp-schema lint source/ before build
• Schema errors fail the build

Before/After

Before:                              After:
source/schemas/checkout.json         source/schemas/checkout.json
       ↓                                    ↓
generate_schemas.py                  (direct publish)
       ↓                                    ↓
spec/schemas/checkout.json           https://ucp.dev/{version}/schemas/shopping/checkout.json
spec/schemas/checkout.create_req.json       (with annotations intact)
spec/schemas/checkout.update_req.json
spec/schemas/checkout_resp.json

Single schema URL, versioned. All site-generation markdown logic remains functional & intact.

---

Type of change

Please delete options that are not relevant.

• Bug fix
• New feature (non-breaking change which adds functionality)

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings

[drewolson-google]

This effectively solves the schema versioning problem, great work.

Two things to discuss at TC:

1. This requires yet another language toolchain to be locally installed when working on UCP. We would now require python, node, and rust, along with other tools for running linting and other checks mirroring Github actions. Let's make sure the benefit of introducing another toolchain outweighs the costs.

2. This makes ucp-schema a direct dependency of working on UCP. This means that we'll need to effectively be able to contribute to this tool if there are issues or bugs. While it removes a large amount of code from this repository, it does spread some of that logic of two repositories for the future contributors to this project.

[drewolson-google]

We should be able to check the executable bit into git so we don't have to run this every time.

[igrigorik]

@drewolson-google ack and +1 on toolchain.

I reached for Rust to make validator a self-contained binary that you can wget and not worry about installing an entire ecosystem — e.g. build artifacts that can be used directly. It makes authoring the validator harder, but that's pain and complexity that's localized to the ucp-schema devs, that everyone else does not and won't need to feel.

If we go forward with this path, I'd also suggest we adopt ucp-schema as official tool under UCP org -- happy to contribute and move it to the official repo.

[wry-ry]

Would it make sense to remove version from the source file completely, and add it here for all files?

[igrigorik]

👍 updated

[wry-ry]

LGTM