[RFC] Proposal: UCP Open Source Unified Toolchain and SDK Generation

[cusell-google]

Field	Value
Status	Proposal
Authors	Enric Cusell (cusell-google)
Created	2026-05-20
TC Decision	Pending

---

Summary

This proposal defines a unified spec-driven toolchain roadmap for the Universal Commerce Protocol (UCP) open-source ecosystem. It shifts the UCP architecture from a fragmented, reactive downstream update model into an automated, proactive Continuous Integration (CI) pipeline.

The proposal introduces a standardized pipeline that strictly relies on the ucp-schema/ pre-processor to resolve custom UCP metadata into valid OpenAPI 3 specifications. From there, it standardizes the translation layer using open-source ecosystem tools (e.g. datamodel_code_generator for Python, quicktype/zod for JS/TS) to automatically generate SDKs. It follows a set of focused implementations: from spec-driven synchronization to SDK generation, AI context readiness and a decentralized self-certification framework for businesses.

Motivation

As UCP matures into an industry standard, the primary vector for global adoption is the open-source tooling available to developers trying to implement the protocol (specification, SDKs, samples and conformance suites). Manual SDK updates and per-language pre-processing require significant engineering overhead. To scale efficiently, we have an opportunity to transition from reactive downstream updates to a fully automated pipeline.

Problem: Version drift

Historically, downstream repositories (python-sdk/, samples/, conformance/) have relied on manual implementations and per-language pre-processing scripts and have lagged behind the ucp/ specification. For example: updating python-sdk/ to fully support version 2026-01-23 only happened ~2 months later (Universal-Commerce-Protocol/python-sdk#21).

While this reactive update model could have worked during UCP's early stages, it presents a bottleneck for the future. As the UCP ecosystem expands, the compounding maintenance burden will inevitably result in severe version drift. This leaves businesses, third-party platforms and integrators to choose between implementing raw UCP request processors from scratch or using outdated SDKs.

To future-proof UCP and ensure the community is empowered to immediately build on the newest UCP features, we must eliminate the manual overhead by transitioning to a fully automated, proactive and spec-driven CI pipeline.

Problem: Fragmented Tooling

The raw UCP specification JSONs contain custom schema parameters that standard code generators cannot natively parse. For example: see line_item.id, where a single field might have the behaviour:

"properties": {
    "id": {
      "type": "string",
      "ucp_request": {
        "create": "omit",
        "update": "optional"
      }
    },

Currently, resolving these attributes, splitting structures into operation-specific classes and flattening nested structures is done via manual processes (e.g. Python's custom preprocess_schemas.py (source)).

Local development is fragmented:

• Conformance tests rely on manual workflows involving setting up SQLite DBs with mock data, pasting bash loops into the CLI, and manually killing PIDs instead of being automated workflows. (see code)
• Python samples assume strict sibling-directory structures and rely on manually piping local relative paths (see code)

Without a unified infrastructure, the community is building decentralized alternatives. This protects against ecosystem fragmentation and allows integrators to rapidly self-certify before launching into production.

Proposed phases

Phase 1: Spec-driven pre-processing and core sync

Target: ucp, ucp-schema
Type: Architectural change (inverting the dependency graph)

Problem statement
Downstream repositories play catch-up on the core ucp spec repository.

What lands

• Standardize on ucp-schema: Adopt ucp-schema as the single source of truth for pre-processing. It will consume the raw ucp JSONs, resolve complex custom attributes (like ucp_request omitted/required states), and output standard OpenAPI 3 specifications.
  • All unit testing and correctness validation of the metadata resolution logic will live natively in this repository. This guarantees the emitted spec is deterministic and validated.
• Automated downstream tracking: GitHub Actions on the ucp repository will run ucp-schema tools against every PR. It will output two JSONs: baseline and the PR changes, generating a clear schema diff for the contributor and reviewers.

Phase 2: SDK generation: translation layer

Target: python-sdk, ucp
Type: Automation & CI infrastructure
Depends on: Phase 1

Problem statement
We need strict typing in specific languages without rewriting the ucp-schema logic natively in Python/JS.

What lands

• Industry-standard translation: Pipe the standard OpenAPI 3 or JSON Schema output from Phase 1 into state-of-the-art open-source generators. For the python-sdk, implement generation using Pydantic's datamodel_code_generator to output pure Pydantic models.
• Dynamic PR verification: During PR development on the core ucp, CI will dynamically validate the Python SDK. This means running the generation script transiently to ensure generating the typed SDK succeeds. No output files are saved or committed.
  • Because the structural correctness is guaranteed by the ucp-schema/ output, this step strictly verifies that the translation script succeeds without syntax or type errors.
  • This guarantees the version merged on main always generates a valid JSON and a valid SDK.
• No generated code in source control: Rather than storing massive generated artifacts in Git, the SDK repositories will strictly house the tooling, configuration and custom wrappers. The fully generated SDK models will be produced dynamically during CI validation and directly published to package registries (PyPI, NPM…) as part of official version releases.

Phase 3: Extended Language support & unified versioning

Target: js-sdk, python-sdk, other languages
Depends on: Phase 2

Problem statement: Javascript/Typescript (and other languages) ecosystems currently lack automated, spec-compliant SDKs, leaving a large portion of developers without native tooling, having to rely on custom or non-official forks. Additionally, the existing SDK versioning scheme is disjointed (e.g. PyPI version 0.3.0 maps to UCP spec version 2026-01-23).

What lands

• JS/TS expansion (and beyond): Extend the translation layer to use quicktype or zod schema generators to output the official NPM @ucp-js/sdk. Once validated, this exact same infrastructure can be leveraged to generate SDKs for any other high-demand languages as prioritized by the TC. Choosing the exact set of languages is out of scope for this RFC.
• Strict semantic versioning mapping: To solve the SDK version mapping, we will adopt a date-based SemVer model for the package managers: YYYYMMDD.0.patch
  • Example: UCP version 2026-01-23 would map to ucp-js/sdk version @ucp-js/sdk version 20260123.0.0.
  • PY/JS Compatibility: It is syntactically and semantically valid for both PyPI (PEP 440) and NPM (SemVer), as the date corresponds to a "Major" UCP release.
  • Risk: future languages may have different incompatible versioning standards. In that case, the language-specific best practices will take precedence and the version mapping must be documented on the language-specific UCP SDK repository.

Phase 4: Pre-onboarding self-certification

Target: conformance
Depends on: Phase 1

Problem statement
Current conformance tests are tightly coupled to sample fake stores (see source). Businesses cannot continuously assert protocol compliance against their live (or staging) integration endpoints.

What lands

• Dynamic execution framework: Evolve the conformance suite into a portable, CI-ready framework, decoupling it entirely from local mock databases. To run successfully, the framework will rely on:
  • Structured input configuration: It will accept a configuration file containing merchant-specific input data (such as offer ids, prices, titles, out of stock items, non-existent items, etc) required to execute various test scenarios. For a very simple existing example see conformance_input.json.
  • Profile-extracted server URLs: The framework will extract the target URLs from the endpoint fields defined within the merchant's /.well-known/ucp capabilities profile.
  • Authorization config: The configuration will support secure authorization parameters. In the current authorization state, businesses will be able to set API keys or inject scoped OAuth access tokens (issued by the business for the testing environment). This will be extended accordingly as the Identity capability is expanded with other authorization constructs.
• Profile-driven test orchestration: The suite will dynamically load test rules based on the merchant's declared /.well-known/ucp capabilities profile. The suite will support modular versioning even if different capabilities have different versions. Based on the specific capabilities and versions declared, the orchestrator dynamically loads only the relevant test subsets.
  • This enables merchants to self-certify programmatically on every commit inside their own local CI/CD pipelines.

Example:
Conformance versioning will no longer be needed. If a merchant's /.well-known/ucp profile declares

{
  "capabilities": {
    "dev.ucp.shopping.checkout": {
      "version": "2026-01-23",
      "endpoint": "https://business.com/ucp/checkout"
    },
    "dev.ucp.shopping.catalog.search": {
      "version": "2026-04-08",
      "endpoint": "https://business.com/ucp/catalog/search"
    }
  }
}

The conformance suite will parse this payload and execute the 2026-01-23 test assertions against the checkout endpoints, and the 2026-04-08 test assertions against the catalog search endpoint in a single automated run. This enables businesses to self-certify inside their custom release pipelines before formally onboarding with partners.

Phase 5: AI Agent Context readiness & atomic code samples

Target: All repositories
Type: Developer Experience & Documentation

Problem statement
External developers increasingly rely on AI coding agents (Claude Code, Gemini CLI, Cursor, …), which frequently hallucinate due to the fragmented UCP repository structures, dynamically generated interfaces and complex inheritance models.

The samples/ repository houses a monolithic "mock store" (a Flower Shop app). Historically this was necessary because the conformance tests were tightly coupled to it.

What lands

• Standardized llms.txt, SKILL.md and AGENTS.md files: (docs: adds descriptions to links in llms-txt #419 ) This gives explicit context boundaries and instruction sets to AI agents, minimizing hallucinations and teaching them exactly how to consume the generated SDKs and run test suites. Major updates to the UCP spec can optionally also include the relevant (human) updates on those files.
• Automated context sync: A GitHub workflow/bot that periodically sweeps through all repository content to analyze and auto-update these LLM-awareness files. This ensures they always describe the current main branch changes and repository state accurately, preventing the context from going stale without adding overhead to maintainers.
• Transition to atomic samples: With conformance testing decoupled, the samples/ repository can pivot away from a full monolithic application. Instead, it will house method specific implementation snippets organized by version, capability, language and API method.
  • Coding agents perform better when given code examples.

Implementation Sequence and Suggested PR Titles

Phase	Repo	Suggested PR title
1	ucp	ci: integrate ucp-schema action for spec pre-processing, OpenAPI 3 generation and schema diffs
2	python-sdk	feat: automated pydantic sdk generation via datamodel_code_generator
2	ucp	ci: add transient downstream SDK verification checks to PR gate
3	js-sdk	feat: implement typescript SDK generation via quicktype to validate scalable expansion framework
3	python-sdk, js-sdk	chore: align package manager releases with YYYYMMDD.0.patch semantic versioning
4	conformance	feat: decoupled dynamic test orchestration via structured config and well-known ucp profiles
5	all	docs: introduce SKILL.md and llms.txt for AI agent context
5	samples	refactor: pivot from monolithic mock store to atomic method-specific snippets

Non-goals

• Selecting exact languages for SDK expansion (as part of Phase 3): deciding which specific languages to prioritize beyond Python and Javascript/Typescript is out of scope for this RFC. This will be debated and decided during the Phase 3 "Extended Language Support" based on community, industry demand and ecosystem readiness. This RFC proposal also aims to outline a generic approach that can easily be extended to more languages.
• Changes to the core UCP JSON schema format: This proposal focuses on tooling and generating downstream artifacts. It does not propose any changes to how the core UCP specification itself is authored.
• Vertical-specific solutions: A core principle of the proposed toolchain is that it remains vertical-agnostic. All generated pre-processing, SDKs, and conformance orchestration will natively support vertical-expansion compatibility.

TC review questions

1. Acceptance of ucp-schema as a key dependency.

TC Question: Does the TC agree to standardize on the ucp-schema/ repository as the definitive, centralized pre-processing layer?

(recommended) Alternative A:
Adopt ucp-schema/

• Pros: A single, highly tested source of truth for generating both UCP documentation (already used) and OpenAPI 3 specs.
• Cons: The only piece of UCP code that is in Rust. SDK developers would need to contribute in a different language.

Sub-alternative: Re-write ucp-schema in Python.

Alternative B:
Decentralized language-specific pre-processors

• Pros: Allows SDK maintainers to build parsing logic natively in their ecosystem's language.
• Cons: Engineering overhead and duplicate complex logic across N languages. Risk of logic drift and inconsistencies between how documentation is generated and how SDKs behave.

2. PR blocking vs async tracking

TC Question: If downstream SDK compilation fails during a core ucp/ pull request, how should the CI pipeline react?

In both cases, GitHub actions generating downstream spec and SDKs run. The alternatives define how the results affect the merging of those changes.

Alternative A: Async tracking & release gating
Day-to-day PRs are allowed to merge into main even if they temporarily break downstream SDK, automatically opening tracking issues assigned to the author instead. However, a strict "release gate" ensures that no official UCP protocol version can be tagged or published to package managers until all of those associated downstream build issues are fully resolved. Automatic AI-assisted workflows can be set up to resolve some of those issues.

• Pros: Maximizes spec iteration velocity. Protocol architects are not blocked by transient code-generation errors in languages they do not maintain.
• Cons: The main branch acts as a continuous draft and might temporarily contain commits that fail to compile downstream SDKs. High risk of authors never following up with assigned issues.

(recommended) Alternative B: Strict PR blocking

• Pros: Guarantees that the main branch is 100% stable and capable of generating valid SDKs globally at every commit.
• Cons: High friction. Spec authors may experience blocked PRs due to downstream translation failures in ecosystems they may not be familiar with. Risk of slowing down protocol evolution.

3. Artifact publishing (SDK source code not being committed)

TC Question: Does the TC agree that generated SDK source code (e.g. Pydantic models, Zod schemas…) should not be committed to the main branch of their respective GitHub repositories?

Same question for the OpenAPI JSON specs for the ucp-schema/ output.

(recommended) Alternative A: Transient Generation

• Pros: The main branch of each SDK repository houses generation tooling and configuration. PR diff noise and merge conflicts are eliminated. SDKs are published directly to package registries (PyPI, NPM, etc) during releases.
• Cons: Developers cannot easily browse the latest generated SDK source code on GitHub.

Alternative B: Commit to a dedicated release/* branch

• Pros: Keeps main clear of boilerplate, while providing a Git history and explicit audit trail of exactly what was published to package managers.
• Cons: Increase in repository size and CI pipeline complexity to manage cross-branch pushes.

4. Tooling versioning scheme

TC Question: Does the TC approve the strict alignment of package manager versions with UCP protocol release tags?

(recommended) Alternative A: Date-based Semantic Versioning

• Pros: Creates a frictionless 1:1 mental map for developers mapping SDKs to protocol capabilities. Can handle language-specific ad-hoc solutions if a future language ecosystem strictly forbids this format.
• Cons: Semantic versioning with dates results in very high version integers, not supported in older languages (e.g. .NET and C# rely on 16-bit ints).

Alternative B: Custom language-native versioning with mapping tables

• Pros: Native to individual package manager standards.
• Cons: Higher cognitive load. Developers and AI Agents must reference and rely on README mapping tables (e.g. mapping 0.3.0 PyPi to UCP release 2026-01-23), increasing the risk of capability mismatches.