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 Manifests' signatures and the entry's digest. These 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-local <SINGULAR>id and xid, with the complete URI preserved in the ai-catalog.identifier label
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
Contributor Trust Manifests	An array in an extension attribute on the Resource, or related Resources referenced by xref
Content integrity (entry.digest)	Carried in a Resource extension attribute (xRegistry has no native digest)
Signing	Trust Manifest signatures retained in a Resource extension attribute (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. The complete entry identifier URI is preserved in the ai-catalog.identifier label. Multiple entry versions map to Versions.

3. Trust Manifests are carried as an array in a Resource extension attribute (for example aicatalog_trustmanifests), or as related Resources referenced from meta.xref, preserving each manifest, including its contributor, subject, and signature. Carry entry.digest separately, for example as aicatalog_digest. Preserve the signed manifest contents so signature payloads can be reconstructed unchanged.

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, reconstruct entry.identifier from the ai-catalog.identifier label, read its document (inline or via <RESOURCE>url) and contenttype to recover the entry's artifact content and type, and map name, description, and remaining labels back to entry metadata.
3. Restore trustManifests and digest from their extension attributes or related Resources, then verify the signatures and signed artifact bindings against the reconstructed entry and 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:air:acme.com:agent:finance-a2a"
      },
      "entryurl": "https://cards.acme.com/finance/a2a-card.json",
      "aicatalog_digest": "sha256:aaa111...",
      "aicatalog_trustmanifests": [
        {
          "contributor": "did:web:acme.com",
          "subject": {
            "identifier": "urn:air:acme.com:agent:finance-a2a",
            "type": "application/a2a-agent-card+json",
            "digest": "sha256:aaa111..."
          },
          "signature": {
            "signer": "did:web:acme.com",
            "profile": "did-web-v1",
            "issuedAt": "2025-01-01T00:00:00Z",
            "jws": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImRpZDp3ZWI6YWNtZS5jb20jcmVsZWFzZS1zaWduaW5nLWtleSIsInR5cCI6ImFpLWNhdGFsb2ctdHJ1c3QtbWFuaWZlc3QrandzIn0..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 carries the entry digest and signed Trust Manifests. Verification uses the reconstructed logical entry and the served Resource document during unpacking, as in plain-HTTP distribution. Resource extension attribute names are transport details; signatures authenticate the logical Trust Manifests, not the xRegistry representation.