Mapping to xRegistry

This guide binds the Distribution Substrates contract to [[xRegistry]], a hierarchical registry model organized as Registry → Groups → Resources → Versions. xRegistry contributes structure, identity, versioning, cross-referencing, and a registry API; it has no native content-addressing or signature primitive.

Of the binding invariants, the xRegistry binding delegates entry identity, catalog structure, artifact content, and manifest discovery to xRegistry's own primitives, but carries content integrity and signing in the Trust Manifest. The detached JWS and subject.digest remain authoritative exactly as in plain-HTTP distribution, because xRegistry cannot express either guarantee natively.

Conceptual Mapping

An AI Catalog document maps to an xRegistry Group whose Resources are the catalog entries; each entry's artifact is the Resource document.

AI Catalog (Logical)	xRegistry (Physical)
AI Catalog document	A Group instance (e.g. in a aicatalogs Group type), or the Registry root when serving a single catalog
Catalog Entry	A Resource within that Group
Entry identifier	Resource <SINGULAR>id and xid
Entry type	Version contenttype (with format when a named format applies)
Entry artifact content	Resource document — inline (<RESOURCE> / <RESOURCE>base64) or external (<RESOURCE>url)
Entry metadata (displayName, description, tags)	name, description, labels
Entry version	Version versionid
Nested Catalog Entry	A nested Group referenced from the entry's Resource via meta.xref
Trust Manifest	An extension attribute on the Resource (an object), or a related Resource referenced by xref
Content integrity (subject.digest)	Carried in the Trust Manifest (xRegistry has no native digest)
Signing	Detached JWS retained in the Trust Manifest (xRegistry has no native signature)

Packing: AI Catalog to xRegistry

Tooling converts an AI Catalog JSON document into xRegistry resources:

1. The catalog becomes a Group instance. Catalog-level metadata maps to Group attributes: displayName to name, host identity and other metadata to labels or extension attributes.

2. Each catalog entry becomes a Resource in that Group. The entry's artifact content is stored as the Resource document — inline via <RESOURCE> / <RESOURCE>base64, or by reference via <RESOURCE>url. type maps to contenttype; entry metadata maps to name, description, and labels. Multiple entry versions map to Versions.

3. Trust Manifests are carried as an extension attribute on the Resource (for example aicatalog_trustmanifest), or as a related Resource referenced from meta.xref. The detached JWS and subject.digest are retained unchanged because xRegistry provides no native signing or content-addressing to delegate to.

4. Nested catalog entries become nested Groups; the parent entry's Resource references the nested Group through meta.xref.

Unpacking: xRegistry to AI Catalog

Tooling converts xRegistry resources back to an AI Catalog JSON document:

1. Retrieve the Group in document view (the xRegistry ?doc projection), which returns a single self-contained JSON document analogous to ai-catalog.json.
2. For each Resource, read its document (inline or via <RESOURCE>url) and contenttype to recover the entry's artifact content and type; map name, description, and labels back to entry metadata.
3. Read the Trust Manifest from the extension attribute or xref'd Resource, and verify its detached JWS and subject.digest against the served bytes.
4. Resolve xref'd nested Groups into nested catalog entries.
5. Assemble the logical application/ai-catalog+json document.

xRegistry Document Example

The following shows the xRegistry document-view representation of a Group holding two entries. This is generated by tooling, not authored by hand:

{
  "aicatalogid": "acme-services",
  "self": "https://registry.acme.com/aicatalogs/acme-services",
  "xid": "/aicatalogs/acme-services",
  "epoch": 1,
  "name": "Acme Services Inc.",
  "entriesurl": "https://registry.acme.com/aicatalogs/acme-services/entries",
  "entriescount": 2,
  "entries": {
    "finance-a2a": {
      "entryid": "finance-a2a",
      "xid": "/aicatalogs/acme-services/entries/finance-a2a",
      "name": "Acme Finance A2A Agent",
      "contenttype": "application/a2a-agent-card+json",
      "labels": {
        "ai-catalog.identifier": "urn:acme:agent:finance-a2a"
      },
      "entryurl": "https://cards.acme.com/finance/a2a-card.json",
      "aicatalog_trustmanifest": {
        "issuedAt": "2025-01-01T00:00:00Z",
        "subject": {
          "type": "application/a2a-agent-card+json",
          "digest": "sha256:aaa111..."
        },
        "signature": "eyJhbGciOiJFUzI1NiJ9..detached-JWS.."
      }
    },
    "finance-mcp": {
      "entryid": "finance-mcp",
      "xid": "/aicatalogs/acme-services/entries/finance-mcp",
      "name": "Acme Finance MCP Server",
      "contenttype": "application/mcp-server-card+json",
      "labels": {
        "ai-catalog.identifier": "urn:acme:server:finance-mcp"
      },
      "entryurl": "https://cards.acme.com/finance/mcp-server.json"
    }
  }
}

Content Integrity and Signing

Because xRegistry has no native content-addressing or signature primitive, this binding does not delegate those invariants: the Trust Manifest's detached JWS and subject.digest remain the source of truth, verified against the served Resource document during unpacking — the same model as plain-HTTP distribution. An implementation MAY additionally expose the digest as an extension attribute for discovery convenience, but that copy is advisory; the Trust Manifest remains authoritative.