Skip to content

docs: schema-validated documentation examples #359

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
igrigorik wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: schema-validated documentation examples #359

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions docs/documentation/schema-authoring.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -156,6 +156,7 @@ Examples: `ucp.json` (entity base), `capability.json`, `service.json`, `payment_
UCP organizes capabilities, services, and handlers in **registries**—objects keyed
by `name` rather than arrays of objects with `name` fields.

<!-- ucp:example skip reason="schema authoring example" -->
```json
{
"capabilities": {
Expand Down Expand Up @@ -202,6 +203,7 @@ Each entity type defines **three variants** for different contexts:

**`platform_schema`** — Full declarations for discovery

<!-- ucp:example skip reason="schema authoring example" -->
```json
{
"dev.ucp.shopping.fulfillment": [{
Expand All @@ -217,6 +219,7 @@ Each entity type defines **three variants** for different contexts:

**`business_schema`** — Business-specific overrides

<!-- ucp:example skip reason="schema authoring example" -->
```json
{
"dev.ucp.shopping.fulfillment": [{
Expand All @@ -230,6 +233,7 @@ Each entity type defines **three variants** for different contexts:

**`response_schema`** — Minimal references in API responses

<!-- ucp:example skip reason="schema authoring example" -->
```json
{
"ucp": {
Expand All @@ -242,6 +246,7 @@ Each entity type defines **three variants** for different contexts:

Define all three in your schema's `$defs`:

<!-- ucp:example skip reason="schema authoring example" -->
```json
"$defs": {
"platform_schema": {
Expand All @@ -262,6 +267,7 @@ Prefer **open string vocabularies** with documented well-known values over close
`enum` arrays. Enums are a one-way door: adding a new value is a breaking change
for strict validators, and removing one breaks existing producers.

<!-- ucp:example skip reason="schema authoring example" -->
```json
// PREFER: open vocabulary — extensible without schema changes
"type": {
Expand Down Expand Up @@ -292,6 +298,7 @@ capabilities **may** version independently when needed.

Capabilities outside `dev.ucp.*` version fully independently:

<!-- ucp:example skip reason="schema authoring example" -->
```json
{
"name": "com.shopify.loyalty",
Expand All @@ -307,6 +314,7 @@ Vendor schemas follow the same self-describing requirements.

A capability schema defines both payload structure and declaration variants:

<!-- ucp:example skip reason="schema authoring example" -->
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
Expand Down
6 changes: 6 additions & 0 deletions docs/specification/ap2-mandates.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,7 @@ Businesses declare support by adding `dev.ucp.shopping.ap2_mandate` to their

**Business Profile Example:**

<!-- ucp:example skip reason="AP2 capability config" -->
```json
{
"capabilities": {
Expand Down Expand Up @@ -143,6 +144,7 @@ Businesses **MUST** embed their signature in the checkout response body under

**Checkout Response with Embedded Signature:**

<!-- ucp:example skip reason="invalid JSON in source" -->
```json
{
"id": "chk_abc123",
Expand Down Expand Up @@ -252,8 +254,10 @@ with `ap2.merchant_authorization` embedded in the response body.

**Example Response:**

<!-- ucp:example schema=shopping/checkout op=read -->
```json
{
"ucp": { ... },
"id": "chk_abc123",
"status": "ready_for_complete",
"currency": "USD",
Expand All @@ -273,6 +277,7 @@ with `ap2.merchant_authorization` embedded in the response body.
{"type": "tax", "amount": 400},
{"type": "total", "amount": 5400}
],
"links": [ ... ],
"ap2": {
"merchant_authorization": "eyJhbGciOiJFUzI1NiIsImtpZCI6Im1lcmNoYW50XzIwMjUifQ..<signature>"
}
Expand Down Expand Up @@ -337,6 +342,7 @@ request:

{{ extension_schema_fields('ap2_mandate.json#/$defs/ap2_with_checkout_mandate', 'ap2-mandates') }}

<!-- ucp:example skip reason="invalid JSON in source" -->
```json
{
"payment": {
Expand Down
3 changes: 3 additions & 0 deletions docs/specification/buyer-consent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@ operations.

Businesses advertise consent support in their profile:

<!-- ucp:example skip reason="discovery config" -->
```json
{
"capabilities": {
Expand Down Expand Up @@ -67,6 +68,7 @@ The platform includes consent within the `buyer` object in checkout operations:

### Example: Create Checkout with Consent

<!-- ucp:example schema=shopping/checkout op=create direction=request -->
```json
POST /checkouts

Expand Down Expand Up @@ -98,6 +100,7 @@ POST /checkouts

### Example: Checkout Response with Consent

<!-- ucp:example skip reason="invalid JSON in source" -->
```json
{
"id": "checkout_456",
Expand Down
13 changes: 13 additions & 0 deletions docs/specification/cart-mcp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ This document specifies the Model Context Protocol (MCP) binding for the
Businesses advertise MCP transport availability through their UCP profile at
`/.well-known/ucp`.

<!-- ucp:example skip reason="JSON-RPC transport binding" -->
```json
{
"ucp": {
Expand Down Expand Up @@ -66,6 +67,7 @@ Businesses advertise MCP transport availability through their UCP profile at
MCP clients **MUST** include a `meta` object in every request containing
protocol metadata:

<!-- ucp:example skip reason="JSON-RPC transport binding" -->
```json
{
"jsonrpc": "2.0",
Expand Down Expand Up @@ -127,6 +129,7 @@ Maps to the [Create Cart](cart.md#create-cart) operation.

=== "Request"

<!-- ucp:example skip reason="JSON-RPC transport binding" -->
```json
{
"jsonrpc": "2.0",
Expand Down Expand Up @@ -162,6 +165,7 @@ Maps to the [Create Cart](cart.md#create-cart) operation.

=== "Response"

<!-- ucp:example skip reason="JSON-RPC transport binding" -->
```json
{
"jsonrpc": "2.0",
Expand Down Expand Up @@ -221,6 +225,7 @@ Maps to the [Create Cart](cart.md#create-cart) operation.

All items out of stock — no cart resource is created:

<!-- ucp:example skip reason="JSON-RPC transport binding" -->
```json
{
"jsonrpc": "2.0",
Expand Down Expand Up @@ -261,6 +266,7 @@ Maps to the [Get Cart](cart.md#get-cart) operation.

=== "Request"

<!-- ucp:example skip reason="JSON-RPC transport binding" -->
```json
{
"jsonrpc": "2.0",
Expand All @@ -282,6 +288,7 @@ Maps to the [Get Cart](cart.md#get-cart) operation.

=== "Response"

<!-- ucp:example skip reason="JSON-RPC transport binding" -->
```json
{
"jsonrpc": "2.0",
Expand Down Expand Up @@ -339,6 +346,7 @@ Maps to the [Get Cart](cart.md#get-cart) operation.

=== "Not Found"

<!-- ucp:example skip reason="JSON-RPC transport binding" -->
```json
{
"jsonrpc": "2.0",
Expand Down Expand Up @@ -391,6 +399,7 @@ Maps to the [Update Cart](cart.md#update-cart) operation.

=== "Request"

<!-- ucp:example skip reason="JSON-RPC transport binding" -->
```json
{
"jsonrpc": "2.0",
Expand Down Expand Up @@ -433,6 +442,7 @@ Maps to the [Update Cart](cart.md#update-cart) operation.

=== "Response"

<!-- ucp:example skip reason="JSON-RPC transport binding" -->
```json
{
"jsonrpc": "2.0",
Expand Down Expand Up @@ -517,6 +527,7 @@ Maps to the [Cancel Cart](cart.md#cancel-cart) operation.

=== "Request"

<!-- ucp:example skip reason="JSON-RPC transport binding" -->
```json
{
"jsonrpc": "2.0",
Expand All @@ -539,6 +550,7 @@ Maps to the [Cancel Cart](cart.md#cancel-cart) operation.

=== "Response"

<!-- ucp:example skip reason="JSON-RPC transport binding" -->
```json
{
"jsonrpc": "2.0",
Expand Down Expand Up @@ -611,6 +623,7 @@ Business outcomes (including not found and validation errors) are returned as
JSON-RPC `result` with `structuredContent` containing the UCP envelope and
`messages`:

<!-- ucp:example skip reason="JSON-RPC transport binding" -->
```json
{
"jsonrpc": "2.0",
Expand Down
12 changes: 12 additions & 0 deletions docs/specification/cart-rest.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ This document specifies the REST binding for the [Cart Capability](cart.md).
Businesses advertise REST transport availability through their UCP profile at
`/.well-known/ucp`.

<!-- ucp:example skip reason="discovery profile" -->
```json
{
"ucp": {
Expand Down Expand Up @@ -101,6 +102,7 @@ All REST endpoints **MUST** be served over HTTPS with minimum TLS version 1.3.

=== "Request"

<!-- ucp:example schema=shopping/cart op=create direction=request -->
```json
POST /carts HTTP/1.1
UCP-Agent: profile="https://platform.example/profile"
Expand All @@ -125,6 +127,7 @@ All REST endpoints **MUST** be served over HTTPS with minimum TLS version 1.3.

=== "Response"

<!-- ucp:example schema=shopping/cart op=read -->
```json
HTTP/1.1 201 Created
Content-Type: application/json
Expand Down Expand Up @@ -174,6 +177,7 @@ All REST endpoints **MUST** be served over HTTPS with minimum TLS version 1.3.

All items out of stock — no cart resource is created:

<!-- ucp:example schema=shopping/types/error_response op=read -->
```json
HTTP/1.1 200 OK
Content-Type: application/json
Expand Down Expand Up @@ -206,13 +210,15 @@ All REST endpoints **MUST** be served over HTTPS with minimum TLS version 1.3.

=== "Request"

<!-- ucp:example skip reason="HTTP headers only, no JSON body" -->
```json
GET /carts/{id} HTTP/1.1
UCP-Agent: profile="https://platform.example/profile"
```

=== "Response"

<!-- ucp:example schema=shopping/cart op=read -->
```json
HTTP/1.1 200 OK
Content-Type: application/json
Expand Down Expand Up @@ -259,6 +265,7 @@ All REST endpoints **MUST** be served over HTTPS with minimum TLS version 1.3.

=== "Not Found"

<!-- ucp:example schema=shopping/types/error_response op=read -->
```json
HTTP/1.1 200 OK
Content-Type: application/json
Expand Down Expand Up @@ -299,6 +306,7 @@ All REST endpoints **MUST** be served over HTTPS with minimum TLS version 1.3.

=== "Request"

<!-- ucp:example schema=shopping/cart op=update direction=request -->
```json
PUT /carts/{id} HTTP/1.1
UCP-Agent: profile="https://platform.example/profile"
Expand Down Expand Up @@ -332,6 +340,7 @@ All REST endpoints **MUST** be served over HTTPS with minimum TLS version 1.3.

=== "Response"

<!-- ucp:example schema=shopping/cart op=read -->
```json
HTTP/1.1 200 OK
Content-Type: application/json
Expand Down Expand Up @@ -403,6 +412,7 @@ All REST endpoints **MUST** be served over HTTPS with minimum TLS version 1.3.

=== "Request"

<!-- ucp:example skip reason="HTTP headers only, no JSON body" -->
```json
POST /carts/{id}/cancel HTTP/1.1
UCP-Agent: profile="https://platform.example/profile"
Expand All @@ -413,6 +423,7 @@ All REST endpoints **MUST** be served over HTTPS with minimum TLS version 1.3.

=== "Response"

<!-- ucp:example schema=shopping/cart op=read -->
```json
HTTP/1.1 200 OK
Content-Type: application/json
Expand Down Expand Up @@ -507,6 +518,7 @@ code registry and transport binding examples.
Business outcomes (including not found and validation errors) are returned with
HTTP 200 and the UCP envelope containing `messages`:

<!-- ucp:example schema=shopping/types/error_response op=read -->
```json
{
"ucp": {
Expand Down
2 changes: 2 additions & 0 deletions docs/specification/cart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@ When the cart capability is negotiated, platforms can convert a cart to checkout
by providing `cart_id` in the Create Checkout request. The cart contents
(`line_items`, `context`, `buyer`) initialize the checkout session.

<!-- ucp:example skip reason="structural fragment" -->
```json
{
"cart_id": "cart_abc123",
Expand Down Expand Up @@ -133,6 +134,7 @@ error response instead of creating a cart resource. `ucp.status` is the
primary discriminator; the absence of `id` is a consistent secondary
indicator:

<!-- ucp:example schema=shopping/types/error_response op=read -->
```json
{
"ucp": { "version": "2026-01-15", "status": "error" },
Expand Down
4 changes: 4 additions & 0 deletions docs/specification/catalog/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -181,6 +181,7 @@ rendering contract.

When search finds no matches, return an empty array without messages.

<!-- ucp:example skip reason="catalog capability, deferred" -->
```json
{
"ucp": {...},
Expand All @@ -195,6 +196,7 @@ This is not an error - the query was valid but returned no results.
When a product is available but has delayed fulfillment, return the product with
a warning message. Use the `path` field to target specific variants.

<!-- ucp:example skip reason="catalog capability, deferred" -->
```json
{
"ucp": {...},
Expand Down Expand Up @@ -238,6 +240,7 @@ When requested identifiers don't exist, return success with the found products
(if any). The response MAY include informational messages indicating which
identifiers were not found.

<!-- ucp:example skip reason="catalog capability, deferred" -->
```json
{
"ucp": {...},
Expand All @@ -262,6 +265,7 @@ return it as a warning with `presentation: "disclosure"`. The `path` field targe
relevant component in the response — when it targets a product, the
disclosure applies to all of its variants.

<!-- ucp:example skip reason="catalog capability, deferred" -->
```json
{
"ucp": {...},
Expand Down
Loading
Loading