Skip to content

Mapping to OCI Distribution

This guide binds the Distribution Substrates contract to OCI registries, enabling content-addressed storage, signing, and replication using existing container infrastructure. OCI's data model uses container-oriented vocabulary (manifests, layers, config, digest) that does not naturally describe a catalog of AI artifacts, so tooling bridges the logical format and the OCI representation.

Of the binding invariants, the OCI binding delegates identity, content integrity, and signing to OCI's own primitives. Consequently trustManifest.subject.digest is expected to equal the OCI descriptor digest of the served artifact, and the detached JWS in the Trust Manifest MAY be omitted from the packed representation because Cosign/Notation referrers carry signing instead. Unpacking reconstitutes (or re-signs) the logical Trust Manifest from those referrers.

Conceptual Mapping

The OCI image specification (v1.1+) supports arbitrary artifact types through the artifactType field. The following table maps AI Catalog concepts to their OCI physical equivalents:

AI Catalog (Logical) OCI (Physical)
AI Catalog document OCI Image Index with artifactType: "application/ai-catalog+json"
Catalog Entry OCI Image Manifest with artifactType set to the entry's type
Entry type Manifest artifactType field
Entry artifact content Manifest layers[0] blob (the protocol-specific document)
Entry metadata (name, tags, publisher) Manifest config blob and/or annotations
Nested Catalog Entry Nested OCI Image Index referenced from the parent index
Trust Manifest OCI Referrer artifact with subject pointing to the entry manifest
Trust Manifest attestations Individual OCI Referrer artifacts per attestation
Signing Cosign / Notation signatures as OCI Referrers

Packing: AI Catalog to OCI

Tooling converts an AI Catalog JSON document into OCI artifacts:

  1. Each catalog entry becomes an OCI Image Manifest. The entry's artifact content (A2A card, MCP Server Card, skill definition) is stored as a layers[0] blob. Common metadata (name, description, publisher) is stored as the config blob or as annotations.

  2. The catalog itself becomes an OCI Image Index whose manifests array references the per-entry manifests by digest.

  3. Trust Manifests become OCI Referrer artifacts attached to their entry manifests via the subject field. Attestation documents (JWTs, PDFs, SLSA provenance) become individual referrer layers.

  4. Nested catalog entries become nested OCI Image Indexes.

oci://registry.acme.com/ai-catalog:latest          (Image Index)
  ├── manifest: finance-a2a-agent                   (Manifest)
  │     ├── config: { name, description, publisher }
  │     ├── layers[0]: a2a-card.json
  │     └── referrer: trust-manifest                (Referrer)
  │           ├── config: trust-manifest.json
  │           └── layers: [publisher.jwt, soc2.pdf]
  ├── manifest: finance-mcp-server                  (Manifest)
  │     ├── config: { name, description }
  │     └── layers[0]: mcp-server.json
  └── index: finance-suite                          (Nested Index)
        ├── manifest: suite-a2a-agent
        └── manifest: suite-mcp-server

Unpacking: OCI to AI Catalog

Tooling converts OCI artifacts back to an AI Catalog JSON document:

  1. Fetch the OCI Image Index for the catalog.
  2. For each manifest in the index, extract the config blob (entry metadata) and layers[0] blob (artifact content).
  3. Query the Referrers API for each manifest to discover Trust Manifests and attestations.
  4. Assemble the logical AI Catalog JSON with entries[] and trustManifest fields.

The result is a standard application/ai-catalog+json document indistinguishable from one authored by hand.

OCI Image Index Example

The following shows the OCI physical representation of an AI Catalog containing two entries. Note that this is generated by tooling, not authored by hand:

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "artifactType": "application/ai-catalog+json",
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:aaa111...",
      "size": 1024,
      "artifactType": "application/a2a-agent-card+json",
      "annotations": {
        "ai-catalog.identifier": "urn:air:acme.com:agent:finance-a2a",
        "ai-catalog.displayName": "Acme Finance A2A Agent"
      }
    },
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:bbb222...",
      "size": 512,
      "artifactType": "application/mcp-server-card+json",
      "annotations": {
        "ai-catalog.identifier": "urn:air:acme.com:server:finance-mcp",
        "ai-catalog.displayName": "Acme Finance MCP Server"
      }
    }
  ],
  "annotations": {
    "ai-catalog.specVersion": "1.0",
    "ai-catalog.host.displayName": "Acme Services Inc."
  }
}

Signing and Verification

Because OCI distribution uses content-addressed digests, signing is handled by existing OCI tooling rather than embedded signature fields:

# Sign an entry manifest
cosign sign registry.example.com/ai/finance-a2a@sha256:aaa111...

# Verify
cosign verify registry.example.com/ai/finance-a2a@sha256:aaa111...

# Attach SLSA provenance
cosign attest --predicate provenance.json --type slsaprovenance \
  registry.example.com/ai/finance-a2a@sha256:aaa111...

These signatures and attestations are discoverable via the OCI Referrers API and can be mapped back to Trust Manifest attestation objects during unpacking.

Relationship to OCI-Native Proposals

Some proposals (such as the AAIF AI Card OCI schema) take an OCI-native approach where the OCI Image Manifest is the data model. In that model, the AI Card is an OCI Manifest, protocol cards are OCI layers, and the catalog is an OCI Image Index consumed directly.

This specification takes a different position: the logical JSON format is the primary interface, and OCI is a distribution substrate. The tradeoffs are:

Concern Logical-first (this spec) OCI-native
Authoring Write simple JSON with domain vocabulary Write JSON conforming to OCI Manifest schema
Vocabulary entries, displayName, type, trustManifest manifests, layers, config, annotations
Minimum viable serving Static JSON file at any URL (optionally well-known) OCI registry or static OCI layout
Signing Detached JWS in logical format; Cosign/Notation in OCI Cosign/Notation only
Content integrity Optional digests in Trust Manifest Guaranteed by OCI content-addressing
Ecosystem compatibility Any HTTP server, any registry, any CDN OCI-compliant registries
Adoption barrier Low — familiar JSON Higher — requires OCI familiarity

Both approaches can coexist. A tooling bridge converts between them losslessly, allowing simple consumers to work with the logical format while infrastructure-oriented deployments leverage OCI distribution.