feat(proto): let an Exchange publish and enforce a registration schema (RAMP-217)

[noxlesh]

Why

An agent integrating the SDK directly signs and sends Register itself and passes through no registration front-end, so a check only a front-end performs is a suggestion, not a rule. The same agent also had nowhere to learn which business fields a given Exchange expects. Both gaps resolve against the manifest the agent already fetches to find the Exchange's endpoint.

This is the protocol half of the multi-Exchange accounts work. The consumers land separately: the Exchange publishing and enforcing the schema, and the identity adapter's pre-check.

What changed

WellKnownManifest.registration_schema (field 29) — a JSON Schema (draft 2020-12, max 16KB) describing the registration_data object the Exchange expects on Register. Publication and enforcement are one decision:

• Present → the Exchange validates registration_data against it and refuses a non-conforming payload.
• Absent → the payload is accepted uninspected and passed to the system of record exactly as before.

Existing Exchanges therefore stay conformant with no change.

REGISTRATION_FAILURE_REASON_INVALID_REGISTRATION_DATA (value 6), plus RegistrationFailure.field_errors (field 2, ≤64 items) carrying the new top-level RegistrationFieldError {path, error}:

{
  "message": "registration_data does not match the published registration_schema",
  "domain": "ramp.v1.ExchangeService",
  "registration_failure": {
    "reason": "REGISTRATION_FAILURE_REASON_INVALID_REGISTRATION_DATA",
    "field_errors": [
      { "path": "/vat_id",              "error": "must match ^[A-Z]{2}[0-9]+$" },
      { "path": "/address/postal_code", "error": "required" }
    ]
  }
}

Contract text. The unconditional "the Exchange passes it through to its system of record without inspecting it" is now conditioned on the manifest — on both the Agent Account Registration banner and RegisterRequest.registration_data.

Design notes

Why free text and not a closed kind enum. JSON Schema's composite keywords (oneOf, anyOf, if/then, minProperties, dependentSchemas) attach to no single member, so a {path, kind} pair degrades to a useless {"", OTHER} for exactly the cases a reader most needs explained. The standard is also extensible by design, so a closed vocabulary in the contract could not stay complete. A machine-readable kind can join at field 3 later without a wire break.

Why RFC 6901 pointers. registration_data is arbitrary JSON and nests; a bare member name cannot address /address/postal_code. The empty string is a legal root pointer and is how whole-object failures are reported — hence no min_len on path.

Leakage. error is developer-facing and NON-authoritative (wording is validator-defined and varies across Exchanges; clients branch on reason). Like ErrorDetail.message, it states the violated constraint and never the submitted value, so a refusal cannot echo an agent's business data back over the wire.

Tooling change worth a look

field_errors is the contract's first repeated message field carrying its own repeated.max_items, which conformance/corpusgen could not build — it produced valid list items for scalars only and panicked appending an unset Value for a message. It now constructs a message item the same way it builds a top-level baseline: from the seed map when one exists, otherwise auto-filled. The corpus gains RegistrationFailure/field_errors/too_many plus the path/error length edges.

Verification

./scripts/ci-local.sh passes end to end — lint, generate + gen/ drift, corpus regen + drift, build/vet/test, doc conformance, parity matrix, docs guards, Pydantic/Zod export + drift, canonical round-trip. buf breaking is clean; the change is purely additive.

Hand-written cases added to conformance/validate_test.go: a refusal carrying field errors, the valid empty root path, an empty error rejected on min_len, and the max_items boundary.

Open for review

1. Schema dialect and size cap. Pinned as draft 2020-12, max 16KB in the field comment. The design doc deliberately left this open; I took it as a working assumption because without a fixed dialect the Exchange and the adapter can validate the same payload differently, and a schema read from a third-party manifest is attacker-influenced input. Worth an explicit call.
2. Local buf version trap (pre-existing, not introduced here). scripts/ci-local.sh flags a mismatched buf but then continues and regenerates gen/ with the wrong version, silently corrupting byte-exact artifacts. Consider making that check fatal.

🤖 Generated with Claude Code