fix!: repair profile schemas to pass validation & endpoint contract

[igrigorik]

Our schema validation and lint infrastructure exercises the services / payload surface — request roundtrips, codegen, fixture validation. The profile / discovery schemas and the MCP openrpc meta block have no equivalent validation pass:

• The prose examples in docs/specification/ are not validated against their corresponding schemas.
• No fixture roundtrips a real profile document through the top-level discovery schema.
• The openrpc meta block is not cross-checked against the canonical Message Signatures spec.

As a result, a few schema issues snuck in undetected. Worse, our published profiles schemas are effectively broken / can't be validated due to broken oneOf and misplaced requires. See individual commits for specifics

• c5fa47c: service.json platform_schema: drop over-strict endpoint requirement
• 0100ed4: profile_schema.json: top-level oneOf → anyOf (was unsatisfiable)
• 78ea9b3: mcp.openrpc.json: remove stale RFC 7515 signature field

Technically, both oneOf and requires are breaking changes to the profile schemas, but they are un-breaking the current broken state, and so I propose we land and backport this to both 04-08 and previous releases.

---

Checklist

• Core Protocol: Changes to the base communication layer, global context, or breaking refactors.
• UCP Schema: Changes to the ucp-schema tool (resolver, linter, validator). (Requires Maintainer approval)
• I have followed the Contributing Guide.
• I have updated the documentation (if applicable).
• My changes pass all local linting and formatting checks.

[amithanda]

Suggested change

	"description": "Full service declaration for platform-level discovery. All
	transports require `version`, `spec`, and `transport`. REST, MCP, and embedded
	additionally require `schema`."

[amithanda]

Thanks for catching this @igrigorik. I was wondering if there is a way for us to catch
these types of issues proactively in future via our existing ucp-schema based CI checks.

All three bugs in this PR lived in the same uncovered space: schema logic for
discovery and profile documents. ucp-schema is already the right tool and already
wired into CI — the lint job in docs.yml runs ucp-schema lint source/ on every
PR touching source/**. But lint checks schema files for syntax, broken $ref
chains, and annotation errors only; it does not exercise schema logic. ucp-schema validate
covers the service payload surface (checkout, cart, order) via
--op create|update|read — profile documents have no operation concept and are not
covered.

The result: ucp-schema lint source/ passes profile_schema.json and service.json
cleanly both before and after this PR, with no signal that either had a bug. I verified
this locally by applying the PR diff, running lint against both states, and getting
identical clean output each time.

---

Suggestion: close the discovery/profile validation blind spot in ucp-schema and CI

Recommended approach — Embed examples in schemas, extend ucp-schema lint to validate them

JSON Schema 2020-12 includes a standard examples keyword (meta-data annotation
vocabulary), and this repo already uses it — error_code.json, warning_code.json,
and card_credential.json all carry examples arrays today. However, examples is
annotation-only by spec: entries are never validated against the declaring schema
automatically. I confirmed this by injecting an integer into a type: string schema's
examples array — ucp-schema lint passes it cleanly with no error.

The recommendation is therefore to extend ucp-schema lint to add what the spec does
not: explicitly validate each entry in an examples array against the schema or
$defs sub-schema that declares it. Once that capability exists, adding examples to
profile_schema.json and service.json turns the existing lint CI step into a live
correctness check — no new files, no new CI steps.

For profile_schema.json, examples would be added at the top level and within each
$defs branch:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ucp.dev/schemas/discovery/profile.json",
  "anyOf": [
    { "$ref": "#/$defs/platform_profile" },
    { "$ref": "#/$defs/business_profile" }
  ],

  "examples": [
    {
      "ucp": {
        "version": "2026-01-23",
        "services": {
          "dev.ucp.shopping": [{
            "version": "2026-01-23",
            "transport": "rest",
            "schema": "https://ucp.dev/2026-01-23/services/shopping/rest.openapi.json"
          }]
        },
        "capabilities": {
          "dev.ucp.shopping.checkout": [{ "version": "2026-01-23" }]
        },
        "payment_handlers": {}
      },
      "signing_keys": [{ "kid": "key-1", "kty": "EC", "crv": "P-256" }]
    }
  ],

  "$defs": {
    "platform_profile": {
      "examples": [
        { "ucp": { "version": "2026-01-23", "services": { "...": "..." }, "payment_handlers": {} } },
        { "ucp": { "...": "..." }, "signing_keys": [{ "kid": "key-1", "kty": "EC" }] }
      ]
    },
    "business_profile": {
      "examples": [
        { "ucp": { "version": "2026-01-23", "services": { "...": "..." }, "payment_handlers": {} } }
      ]
    }
  }
}

The top-level example with signing_keys and capabilities populated is the exact
document that exposed this PR's oneOf bug — it satisfies both platform_profile and
business_profile branches simultaneously, which oneOf rejects and anyOf accepts.
Had lint been validating this example when oneOf was introduced, CI would have failed
on that PR rather than this one.

What this requires from ucp-schema (two additions to lint):

1. Validate examples during lint — when processing a schema file, validate each
   entry in examples arrays (both top-level and within $defs) against the schema or
   sub-schema that declares it. Report failures as errors, not warnings.

2. Require examples on discovery/meta schemas — add a lint rule that flags
   profile_schema.json, service.json, capability.json, and payment_handler.json
   as errors if they carry no examples. This makes it structurally impossible to ship
   a schema change without coverage: you either update an existing example that breaks,
   or lint blocks the PR.

What this requires in this repo:

Add examples entries to source/discovery/profile_schema.json,
source/schemas/service.json, and their $defs branches. The existing
ucp-schema lint source/ CI step picks up coverage automatically once the tool
validates them — no new files, no new CI configuration.

Why this is more failure-proof than the two other alternatives that I considered:

External fixture files (tests/fixtures/profile/) and annotated spec examples
(<!-- ucp-schema: validate-against ... --> in docs/specification/*.md) both work
but share the same structural weakness: the tests live in a different file from the
schema. A contributor opening profile_schema.json to make a change has no
in-their-face signal that something elsewhere needs updating. The coupling is social,
not structural — the same conditions that let these bugs through.

With embedded examples the tests and schema are in the same file. You cannot miss
them, and a lint rule that requires examples on discovery schemas means you cannot
ship a change without coverage.

What do you think?

[ptiper]

Thanks Ilya. @amithanda, agree we need CI to catch this. I opened a new issue in the .github repo to track: Universal-Commerce-Protocol/.github#21

[igrigorik]

@amithanda good catch on the prose -- ty! Pushed a fix.

I agree that we need to validate and enforce this in CI. Worth nothing that all of the above bugs have associated examples inlined in our spec text, but today we do not validate them — the examples were shaped right, the schemas did not match the intent. As a first pass, I'd suggest we finish and land the pattern we're exploring in #359.

  <!-- ucp-schema: validate discovery/profile.json#/$defs/platform_profile -->
  { "ucp": { ... }, "signing_keys": [...] }

I think above would have caught these bugs. We can certainly explore adding and validating examples in the schemas as you suggested as followup as well. That said, I would not block this PR on either, let's run them in parallel?

[amithanda]

@amithanda good catch on the prose -- ty! Pushed a fix.

I agree that we need to validate and enforce this in CI. Worth nothing that all of the above bugs have associated examples inlined in our spec text, but today we do not validate them — the examples were shaped right, the schemas did not match the intent. As a first pass, I'd suggest we finish and land the pattern we're exploring in #359.

  <!-- ucp-schema: validate discovery/profile.json#/$defs/platform_profile -->
  { "ucp": { ... }, "signing_keys": [...] }

I think above would have caught these bugs. We can certainly explore adding and validating examples in the schemas as you suggested as followup as well. That said, I would not block this PR on either, let's run them in parallel?

@igrigorik - Yes, Agree that validating and enforcing via CI checks can come in a follow up PR and we should move ahead with the changes in this PR.

I am also open to back porting these to previous versions given this is more of a bug.