An OCI image manifest is a JSON document describing a single image variant: it references a config object (JSON with runtime metadata like entrypoint, env, diff IDs) and an ordered list of layer descriptors (blobs with mediaType, size, digest). An image index (manifest list) is a higher-level OCI index that points to multiple platform-specific manifests (each a descriptor), with optional annotations and platform fields (os/arch).Key fields:- manifest: { schemaVersion, mediaType, config: {digest, size, mediaType}, layers: [ {digest,size,mediaType, annotations?} ], annotations? }- index: { schemaVersion, mediaType: application/vnd.oci.image.index.v1+json, manifests: [ {digest, size, mediaType, platform:{os,arch}, annotations?} ], annotations? }Using annotations:- Attach SBOM/provenance by adding annotations either on the index (global to the multi-arch image) or on an individual manifest (per-platform): - e.g. "org.opencontainers.image.source", "io.cncf.notary.signature", or custom keys like "io.example.sbom": "https://sbom.example.com/artifact.cdx.json"- For signed provenance, point to a checksumed SBOM blob digest rather than an external URL.Programmatic queries:- Use the OCI Distribution API: GET /v2/<name>/manifests/<reference> with Accept header for manifest or index media types. Response body is the manifest/index JSON; annotations are in the JSON.- Example with curl + jq:bash
curl -s -H "Accept: application/vnd.oci.image.index.v1+json, application/vnd.oci.image.manifest.v1+json" \
-u user:pass \
"https://registry.example.com/v2/myrepo/myimage/manifests/latest" | jq '.annotations, .manifests[]?.annotations'
- Tools: skopeo inspect, crane manifest, oras/oci packages (Go) expose descriptors and annotations programmatically.- In Go (github.com/opencontainers/image-spec/specs-go/v1) you can Unmarshal into v1.Index/v1.Manifest and read Descriptor.Annotations.Best practices:- Use stable annotation keys (reverse-domain), include digests for integrity, prefer storing SBOMs as registry blobs (referenced by digest) rather than fragile external URLs, and place annotations at the appropriate level (index vs manifest) depending on whether SBOM is global or platform-specific.