key ordering for UCP map registries

[igrigorik]

UCP represents extensible registries as JSON objects keyed by reverse-DNS identifiers. One limitation of this contract is that JSON object member order is not guaranteed, and we've run into cases where we want to declare the preferred traversal order of their keys — e.g. payment handlers, identity providers, etc.

{
  "payment_handlers": {
    "com.google.pay": [{"id": "gpay", "version": "2026-01-11"}],
    "dev.shopify.shop_pay": [{"id": "shop_pay", "version": "2026-01-11"}]
  },
  "providers": {
    "app.example.login": [{"type": "oauth2", ... }],
    "com.google": [{"type": "oauth2", ...}]
  }
}

Note: this shape is intentional. Reverse-DNS keys provide decentralized namespace governance, JSON object keys provide uniqueness by construction, and schemas can enforce key shape with propertyNames / patternProperties. However, JSON object member order is not semantically reliable. Canonicalization, signing, intermediaries, and ordinary JSON tooling may reorder object keys.

---

Proposal

Introduce a reserved local companion object named $order.

{
  "providers": {
    "app.example.login": [{"type": "oauth2"}],
    "com.google": [{"type": "oauth2"}]
  },
  "$order": {
    "providers": ["app.example.login", "com.google"]
  }
}

$order is an object scoped to its containing object. Each property of $order names a sibling map-valued field. The value is an array of keys from that sibling map and defines ordered traversal of those keys.

$order defines key order only. It does not, by itself, define display priority, selection priority, trust level, negotiation preference, endorsement, or fallback behavior. The referenced field’s specification must state what ordered traversal means in that context.

Normative rules

For a sibling map field <field> and companion array $order.<field>:

1. Producers MUST NOT rely on JSON object member order for UCP map-valued registries.
2. $order.<field> contains keys from <field> in preferred traversal order.
3. The order array MAY be partial. Listed keys are traversed first, in array order.
4. Unlisted map keys remain valid and available. They are appended after listed keys using the field-defined fallback, or lexicographic order if no fallback is defined.
5. The order array is not a whitelist. Omission from $order.<field> MUST NOT mean removal, ineligibility, or reduced support.
6. Producers SHOULD only list keys present in the sibling map. Robust consumers SHOULD ignore keys that are not present.
7. Duplicate keys are invalid. Robust consumers SHOULD honor the first occurrence and ignore later duplicates.
8. If $order or $order.<field> is absent, no order is declared. Consumers MUST NOT use object member order as fallback.
9. A parent field’s specification MUST state what the ordered traversal is used for.

Examples

Identity providers

If identity provider ordering is later desired, the shape can order provider namespaces without changing the current providers map:

{
  "config": {
    "providers": {
      "app.example.login": [
        {"type": "oauth2", "auth_url": "https://accounts.example-login.app/"},
        {"type": "wallet"}
      ],
      "com.google": [
        {"type": "oauth2", "auth_url": "https://accounts.google.com/"}
      ]
    },
    "$order": {
      "providers": ["app.example.login", "com.google"]
    }
  }
}

This orders provider buckets. It does not define mechanism selection order inside app.example.login; that remains local to the providers["app.example.login"] array and the identity-linking spec.

Payment handlers

If the desired question is “which payment handler / wallet namespace should be promoted first?” then the order belongs to payment_handlers keys:

{
  "ucp": {
    "payment_handlers": {
      "dev.shopify.shop_pay": [
        {"id": "shop_pay", "version": "2026-01-11"}
      ],
      "com.google.pay": [
        {"id": "gpay", "version": "2026-01-11"}
      ]
    },
    "$order": {
      "payment_handlers": ["dev.shopify.shop_pay", "com.google.pay"]
    }
  }
}

This does not rank concrete payment instruments such as “card” vs “bank”, that order can be derived directly from the instruments array: JSON arrays are ordered sequences; JSON canonicalization preserves array element order even while sorting object keys.

Schema sketch

Each schema declares $order entries for the sibling maps that support ordering:

{
  "type": "object",
  "properties": {
    "providers": {
      "type": "object",
      "propertyNames": {"$ref": "types/reverse_domain_name.json"},
      "additionalProperties": {
        "type": "array",
        "items": {"$ref": "#/$defs/provider"}
      }
    },
    "$order": {
      "type": "object",
      "properties": {
        "providers": {
          "type": "array",
          "items": {"$ref": "types/reverse_domain_name.json"},
          "uniqueItems": true
        }
      },
      "additionalProperties": false
    }
  }
}

Standard JSON Schema can validate the shape, item syntax, and uniqueness. It generally cannot validate “every ordered key is present in the sibling map” without custom validation. That rule should live in UCP conformance tooling and tolerant consumer behavior.

Compatibility and trade-offs

This is additive. Existing map values remain unchanged, existing consumers that ignore unknown properties can continue to read the map as is and the registry map itself remains pure and homogeneous.

Costs:

• reserves $order as structural UCP metadata in object scopes that use it;
• requires prose/custom validation for cross-reference integrity;
• introduces a new $-prefixed instance-field convention;
• parent field specs must be disciplined about semantics.

---

Alternatives

This proposal is intentionally narrow. It orders reverse-DNS map buckets without changing the existing map value shape. Other ordering shapes remain useful, but solve different problems or break compatibility.

Why not display_order?

display_order is not wrong; it solves a different level of the model. PR #176 explored adding display_order to available_instruments[] entries:

{
  "payment_handlers": {
    "com.google.pay": [
      {
        "id": "gpay",
        "available_instruments": [
          {"type": "card", "display_order": 0}
        ]
      }
    ],
    "com.example.tokenizer": [
      {
        "id": "tokenizer",
        "available_instruments": [
          {"type": "card", "display_order": 1},
          {"type": "bank", "display_order": 2}
        ]
      }
    ]
  }
}

First, because instruments is an array, display_order is unnecessary. Also, it does not / cannot solve order of the parent map. Further, if we can solve order of the parent map, then it's also possible to derive relative ordering of cross-handler instruments based on parent rank and instrument rank within each handler.

Finally, display_order cannot be added as a peer inside a reverse-DNS map without breaking the map invariant. Here display_order is not a reverse-DNS key, not a payment handler entry, and would break existing clients:

{
  "payment_handlers": {
    "display_order": 0,
    "com.google.pay": [...]
  }
}

Other shapes

Option	Works for	Why not sufficient here
Embedded rank (display_order: 0)	A concrete value object or child entry that is itself being ordered	Cannot attach cleanly to a parent map bucket when the map value is an array.
Array of keyed entries	Greenfield ordered registries	Cleanest standard pattern, but breaking for existing UCP maps — see above.
In-map reserved order key	Locality inside the map	Breaks the invariant that every map property is an entry; old validators reject it; typed maps become unions.
Per-field sibling (providers_order)	Backward-compatible key order	Safe, but creates per-field naming sprawl.

$order is the best compromise I've found so far: it preserves the existing map shape, keeps maps homogeneous, avoids dotted fixed property names, groups ordering metadata for multiple sibling maps, and visibly marks the data as structural metadata. Would love to hear alt proposals and ideas.

p.s. if we go down this round we can also later formalize this for UCP-aware tooling with a custom JSON Schema vocabulary, e.g. a schema annotation such as ucp_orderable_map. That annotation could tell UCP tooling that $order.providers orders the keys of providers, enabling linting and helper generation. This is useful but not in the critical path. $order is the wire convention; a custom vocabulary would be tooling metadata layered on top.

[amithanda]

Thanks for starting this. I evaluated the proposal through the lenses an implementer actually feels, and come up with an alternate suggestion which is a stronger argument in support of your comment - later formalize this for UCP-aware tooling with a custom JSON Schema vocabulary, e.g. a schema annotation such as ucp_orderable_map.

Lenses:

• Canonicalization / protocol: order cannot live in object keys (JCS sorts them), so an array value is the only JCS-safe carrier. This validates the core of the proposal.
• Developer confusion: a separate order list is an easy "added a handler, forgot the order entry" footgun unless an SDK hides it, and a $-prefixed field surfaces under a mangled name in generated code.
• Schema generation: $ is a clean identifier only in TypeScript; Pydantic, Go, Java, and Quicktype have to mangle and alias it.
• SDK and tooling: a small UCP annotation lets the UCP-owned generator close the gap plain JSON Schema cannot (referential integrity) and emit an ordered accessor.
• Implementation and testing: every suggestion here stays additive and backward-compatible; nothing requires reshaping a shipped registry.

The three reasons you give for the map shape (reverse-DNS for decentralized governance, object keys for uniqueness by construction, propertyNames / patternProperties for key-shape enforcement) are exactly why arrays are not the answer for the already-shipped registries, so keeping the map and layering an explicit order on top is the right call. And the reordering risk is not hypothetical in UCP: AP2 signing and discovery negotiation both canonicalize with JCS (RFC 8785), which sorts object member names, so any order in key position is destroyed the moment a profile is signed or negotiated. Carrying order in an array value (which JCS preserves) is the only shape that survives, and rules 3 through 8 are well chosen.

Worth noting the companion array-of-keys is already a proven shape: Gemini structured output uses a sibling propertyOrdering array (and falls back to alphabetical without it, your JCS problem restated), and react-jsonschema-form uses ui:order with a * wildcard that matches rules 3 and 4. One contrast worth citing as rationale: ui:order drops unlisted keys, while your rule 5 deliberately keeps them, which is the safer reading.

The one thing I would reconsider is the $ prefix, mainly on code-generation grounds. UCP schemas are designed to generate typed classes (the authoring guide calls out Quicktype, Go structs, Java enums, and the repo generates TS via json-schema-to-typescript and Python via datamodel-code-generator). $ is a legal identifier only in TypeScript; Pydantic, Go, Java, and Quicktype all have to mangle and alias a $-prefixed field, which splits the wire name from the field name and, in Pydantic, makes it easy to serialize field_order instead of $order and emit a non-conforming profile. On top of that, $order would be the first $-prefixed instance field in UCP (today $ref, $schema, $id, $defs are all schema keywords), and stores like MongoDB special-case $-prefixed names. The disambiguation the $ buys is also already free from the schema, since propertyNames rejects any non-reverse-DNS key, and $order, key_order, and propertyOrdering all fail that pattern equally.

Given that, would it be worth pairing a plain snake_case companion with a small UCP annotation rather than a sigil? Something like:

"payment_handlers": {
  "type": "object",
  "propertyNames": { "$ref": "common/types/reverse_domain_name.json" },
  "additionalProperties": { "type": "array", "items": { "$ref": "payment_handler.json#/$defs/base" } },
  "ucp_orderable_map": { "order_field": "payment_handlers_order", "fallback": "lexicographic" }
},
"payment_handlers_order": {
  "type": "array",
  "items": { "$ref": "common/types/reverse_domain_name.json" },
  "uniqueItems": true,
  "ucp_request": "omit"
}

This follows the existing ucp_request / ucp_response precedent (annotations ucp-schema already resolves), and it lets the generator do the two things plain JSON Schema cannot: lint that every listed key exists in the map (closing the referential-integrity gap your spec notes), and emit an OrderedMap accessor so SDKs hand back ordered iteration plus O(1) keyed lookup and consumers never hand-correlate the array with the map. It stays additive, JCS-safe, and clean for every code generator, and your normative rules 3 through 8 become the OrderedMap traversal contract. Is that effectively the ucp_orderable_map vocabulary from your postscript, promoted into the proposal rather than left for later?

On convention going forward, would it be worth writing the principle down so future capabilities inherit the default? Concretely: UCP keeps registries as reverse-DNS maps (for governance, uniqueness, and O(1) lookup) and reaches for ucp_orderable_map when order matters, rather than reshaping a map into an array just to get ordering. New registries should default to maps for the same reasons. The symmetric case is worth reserving in the same write-up: if a collection has already shipped as an array and later needs key-like O(1) access or uniqueness, we would not want to break it into a map either. A parallel ucp_keyed_list annotation could retrofit keyed access the same way ucp_orderable_map retrofits order, for example on an array whose callers already look entries up by a field:

"signing_keys": {
  "type": "array",
  "items": { ... },
  "ucp_keyed_list": { "key": "kid" }
}

ucp-schema would lint kid uniqueness and generate a by_kid() accessor, leaving the wire shape (an ordered array) untouched. Net convention: maps stay maps and gain order via ucp_orderable_map; arrays stay arrays and gain keyed access via ucp_keyed_list. Each annotation adds the single capability its shape is missing, so we never have to break a shipped registry to change its access pattern.

[igrigorik]

Closing, let's continue in: #657.