# Mapping to OCI Distribution

This guide binds the [Distribution
Substrates](distribution-substrates.md) 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
`entry.digest` is expected to equal the OCI descriptor digest of the served
artifact, and the Trust Manifest signatures MAY be omitted from the packed
representation because Cosign/Notation referrers carry signing instead.
Unpacking reconstitutes (or re-signs) the logical Trust Manifests 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 |
| Contributor Trust Manifest | OCI Referrer artifact with `subject` pointing to the entry manifest; preserve the contributor identity |
| 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 OCI `subject` field, preserving their contributor
   identities. 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
   `trustManifests` and `digest` fields, including signatures within the
   Trust Manifests.

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:

```json
{
  "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`, `trustManifests` | `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 entry digests | 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.