docs: schema-validated documentation examples

[igrigorik]

Validation harness to ensure every JSON example in the spec docs validates against UCP schemas, with enforcement to keep it that way: when schemas change, stale examples break CI before they mislead readers.

Contract

Every ```json block in the spec MUST be preceded by an HTML comment annotation. Unannotated blocks are hard failures.

<!-- ucp:example schema=shopping/checkout op=create direction=request -->
<!-- ucp:example schema=shopping/cart target=$.discounts -->
<!-- ucp:example schema=common/loyalty def=loyalty extract=$.loyalty -->
<!-- ucp:example schema=profile def=business_schema -->
<!-- ucp:example skip reason="OAuth metadata, not UCP payload" -->

Authoring conveniences beyond strict JSON (small fixed set):

• // line comments (stripped before parse)
• {{ ucp_version }} template variable
• HTTP envelope unwrap (request/response line + headers, body extracted)
• Elision sentinels: { ... }, [ ... ], "..." mean "this field/container is present, value not asserted"

Full grammar: docs/documentation/schema-authoring.md.

Coverage

292 JSON blocks across 41 files
 253 validated (86.6%)
  39 skipped (all with precise, grep-able reasons)
   0 unannotated, 0 failed, 0 errors

The 39 skips fall into two categories:

• Meta docs (25): JSON Schema fragments teaching how to author schemas;
• Non-UCP payloads (14): third-party OAuth metadata, tokenization API responses, payment-handler templates

Capabilities now covered end-to-end: catalog (search + lookup), cart, checkout, order, discount, fulfillment, loyalty, identity-linking, profile, plus all transport bindings (REST, MCP, A2A, Embedded Protocol) and JSON-RPC envelopes.

---

Bugs caught and fixed

Schema-vs-doc drift surfaced by the validation pass:

• checkout.md: item missing required price field in disclosure example
• checkout.md: totals array missing required subtotal entry
• checkout-rest.md: business outcome used non-schema available_quantity field on line_item; replaced with message-based pattern
• discount.md (4 instances): quantity wrongly nested inside item object instead of on line_item
• discount.md: price and title shown in create requests where the request schema omits them (request: only item.id valid)
• ap2-mandates.md, checkout-rest.md, discount.md, overview.md: trailing commas masked by lenient parser, exposed when strict-JSON enforcement landed
• checkout-a2a.md: examples showed bare A2A Message payloads; rewrapped in the JSON-RPC message/send envelope they actually travel in on the wire
• Various: {...spread} JS-style pseudo-elision replaced with the validator's canonical bare-form { ... } / [ ... ]

Enforcement

• CI (.github/workflows/docs.yml): full-corpus validator + unit tests on every PR. Mandatory backstop.
• Local hooks (opt-in via pre-commit install --hook-type pre-commit --hook-type pre-push): three hooks scoped by file filter:
  • Changed docs/*.md files validated incrementally on commit
  • Full-corpus check when source/schemas/ or the validator itself changes (cross-file regression case)
  • Unit tests when validator code changes

---

Type of change

• Documentation update
• 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]

Looks good, one small comment on empty request bodies.

[wry-ry]

The scaffold approach would require that we write (and maintain) a scaffold for most types, right? An alternative approach that I was exploring was:

• Force every example to not omit any required root level properties (value can be ellipsis)
• Use ucp-schema to resolve the schema based on the annotation
• Use jsonschema library to validate the example against the schema
  • Use jsonschema's extend function to create a custom validator class that skips ellipses

May be more convoluted, but would save the extra work of maintaining additional scaffold files. Curious to hear your thoughts.

[raginpirate]

I have no issue with this PR, but I would love to also challenge the fundamental requirement to have all required top-level keys be provided in an unignored example.
We don't want to bloat every snippet with whole complete top level properties, so I feel like many docs will end up leveraging the ignore block 🤔

Can we solve this using a custom key like "...": true or "__rest__": true to ignore evaluating any other required but not present fields in that obj. And perhaps we could display that nicely in the final output docs? {"id": 1234, "...": true} => {"id": 1234, ...}

This can be viewed as non-blocking if we just want to get V0 out, but it could be nice to disallow the "skip" unless you are providing completely custom, non-ucp json 😄

[igrigorik]

@wry-ry re, scaffold maintenance + jsonschema custom validator: scaffols are now optional. I deliberately kept ucp-schema as the validation backend so docs validate against the same canonical tool every other UCP consumer uses. Ellipsis skipping is implemented in the Python wrapper.

@raginpirate re, partial-object elision: current contract supports full-object elision ({ ... }) and per-field value elision ("x": "..."), but not partial-object with "show some fields, ignore other required fields in the same object". My preference is to keep strong and simple contract: required is required; if you open an object, make it pass required.

[ihoosain]

lgtm