How to validate a UCP implementation before production

A UCP validation plan for discovery, negotiation, schemas, states, signatures, idempotency, security, and end-to-end tests.

Published 24 September 2026 . Part of the UCP implementation guide.

A UCP implementation is not validated because one happy-path checkout succeeds. It must prove discovery, negotiation, schema compliance, state transitions, retries, and the security of every advertised transport.

Key takeaways

Test every advertised capability, not only the nominal journey.

Validate profiles and messages against each negotiated version.

Prove that a timeout or duplicate webhook cannot create a second effect.

1. Is the profile usable?

Serve /.well-known/ucp over HTTPS with valid JSON. Verify version, services, capabilities, payment_handlers, and the canonical keys field. Every spec, schema, and endpoint URL must resolve and match the implementation.

Tests should cover a missing, malformed, unreachable, or incorrectly signed profile. The expected statuses are documented in the field-by-field UCP manifest guide.

2. Does negotiation remove incompatible entries?

Build matrices for common versions, disjoint versions, orphaned extensions, and multi-parent extensions. The intersection should select the highest common version and repeat pruning until no dependency is missing.

An empty intersection is a business result, not always an HTTP error. Tests must inspect the UCP body even when REST returns 200.

3. Do payloads match composed schemas?

Fetch base and active extension schemas, check their version constraints, compose them with allOf, and validate requests and responses. Cover required fields, formats, enums, minor-unit amounts, and unknown fields.

For Catalog, confirm ID stability through Checkout. For Cart, confirm full replacement on Update. For Checkout, test all six states and message severities. For Order, ensure every response contains the full current snapshot.

4. Are state-changing operations idempotent?

Send the same request twice with one idempotency key. The second response must come from cache without another payment or order. Then change the payload with the same key: the server must reject it with HTTP 409.

Simulate a lost response after processing, 429, 503, and a Complete Checkout timeout. The client must reuse the key and honor retry timing. The full policy is in UCP errors, retries, and idempotency.

5. Are signatures verified over received bytes?

Test a valid signature, modified digest, changed path, unknown key, and removed key. Content-Digest must be computed over raw bytes. Order webhooks must be rejected when a signature is absent or invalid.

Also test rotation with two simultaneous kid values. The complete algorithm is in UCP Message Signatures.

6. Do handoffs protect the user?

A requires_buyer_input or requires_buyer_review error must open an approved continue_url. Embedded transport must validate origin, require the handshake, and stop all communication after a security error.

Credentials must never appear in URLs, logs, or error text. OAuth scopes should be minimal, and access to personal orders must require user authorization.

7. Is a human fallback still available?

Test cases the API cannot represent: unavailable products, mandatory disclosures, authentication, bank checks, or complex returns. The agent should explain the handoff, preserve session state, and resume without duplicating the action.

Minimum acceptance matrix

Area	Nominal case	Required failure case
discovery	valid profile	424 unreachable profile
negotiation	common version	orphaned extension
Catalog	Search and Lookup	unknown ID
Cart	conversion	checkout already exists
Checkout	completed	escalation and timeout
Order	read and webhook	duplicate or unsigned webhook
OAuth	consent granted	insufficient scope

Release criterion

Production is ready when every advertised capability has compliance evidence, every state-changing operation is idempotent, every webhook is authenticated, and each known error leads to a deterministic action. Remove any untested capability from the profile until it passes.

Sources

Back to the UCP implementation guide · All notes · Lire en français