# opencontainers/image-spec architecture

> Architecture diagram of the GitHub repository opencontainers/image-spec, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/opencontainers/image-spec
- Repository: https://github.com/opencontainers/image-spec

## Overview

This repository defines the OCI image format rather than implementing an image-building or distribution service. Its primary workflow is for an image implementation to produce a layout containing an index that references manifests and their configuration and layer content; validators can check format documents. The graph includes documented runtime and distribution handoffs, plus Go types and identity helpers. The tree and README support these capabilities, but the sampled code does not show an end-to-end image producer or consumer, so those implementation links are omitted.

Main entry points: [`specs-go/v1/manifest.go`](https://github.com/opencontainers/image-spec/blob/main/specs-go/v1/manifest.go) (Image manifest), [`specs-go/v1/index.go`](https://github.com/opencontainers/image-spec/blob/main/specs-go/v1/index.go) (Image index), [`image-layout.md`](https://github.com/opencontainers/image-spec/blob/main/image-layout.md) (Image layout), [`spec.md`](https://github.com/opencontainers/image-spec/blob/main/spec.md) (Format specification)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_format["Image format"]
  node_format_spec["Format specification<br/>[spec.md]"]
  node_layout["Image layout<br/>[image-layout.md]"]
  node_layer["Image layers<br/>[layer.md]"]
end

subgraph group_types["Go types"]
  node_index["Image index<br/>[index.go]"]
  node_manifest["Image manifest<br/>[manifest.go]"]
  node_config["Image config<br/>[config.go]"]
  node_descriptor["Content descriptor<br/>[descriptor.go]"]
  node_media_types["Media types<br/>[mediatype.go]"]
  node_annotations["Annotations<br/>[annotations.go]"]
  node_versioned["Schema version<br/>[versioned.go]"]
end

subgraph group_validation["Validation"]
  node_schema_validator["Schema validator<br/>[validator.go]"]
  node_json_schemas["JSON schemas"]
end

subgraph group_identity["Identity helpers"]
  node_chain_id["Layer ChainID<br/>[chainid.go]"]
end

node_implementer(("Image implementation"))
node_runtime_spec(("OCI runtime"))
node_distribution(("OCI distribution"))

node_implementer -->|"follows"| node_format_spec
node_format_spec -->|"defines"| node_layout
node_layout -->|"contains"| node_index
node_index -->|"references"| node_manifest
node_manifest -->|"references"| node_config
node_manifest -->|"references"| node_layer
node_index -->|"uses"| node_descriptor
node_manifest -->|"uses"| node_descriptor
node_implementer -->|"validates documents"| node_schema_validator
node_schema_validator -->|"validates against"| node_json_schemas
node_manifest -->|"embeds"| node_versioned
node_index -->|"embeds"| node_versioned
node_implementer -->|"calculates layer identity"| node_chain_id
node_layout -->|"unpacks for"| node_runtime_spec
node_implementer -.->|"pushes or pulls via"| node_distribution

click node_format_spec "https://github.com/opencontainers/image-spec/blob/main/spec.md"
click node_layout "https://github.com/opencontainers/image-spec/blob/main/image-layout.md"
click node_index "https://github.com/opencontainers/image-spec/blob/main/specs-go/v1/index.go"
click node_manifest "https://github.com/opencontainers/image-spec/blob/main/specs-go/v1/manifest.go"
click node_config "https://github.com/opencontainers/image-spec/blob/main/specs-go/v1/config.go"
click node_descriptor "https://github.com/opencontainers/image-spec/blob/main/specs-go/v1/descriptor.go"
click node_layer "https://github.com/opencontainers/image-spec/blob/main/layer.md"
click node_media_types "https://github.com/opencontainers/image-spec/blob/main/specs-go/v1/mediatype.go"
click node_annotations "https://github.com/opencontainers/image-spec/blob/main/specs-go/v1/annotations.go"
click node_versioned "https://github.com/opencontainers/image-spec/blob/main/specs-go/versioned.go"
click node_schema_validator "https://github.com/opencontainers/image-spec/blob/main/schema/validator.go"
click node_json_schemas "https://github.com/opencontainers/image-spec/tree/main/schema"
click node_chain_id "https://github.com/opencontainers/image-spec/blob/main/identity/chainid.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_format_spec,node_layout,node_layer toneBlue
class node_index,node_manifest,node_config,node_descriptor,node_media_types,node_annotations,node_versioned toneAmber
class node_schema_validator,node_json_schemas toneMint
class node_chain_id toneRose
class node_implementer,node_runtime_spec,node_distribution toneIndigo
```

## Components

### Image format

- [Format specification](https://github.com/opencontainers/image-spec/blob/main/spec.md): `spec.md`
- [Image layout](https://github.com/opencontainers/image-spec/blob/main/image-layout.md): `image-layout.md`
- [Image layers](https://github.com/opencontainers/image-spec/blob/main/layer.md): `layer.md`

### Go types

- [Image index](https://github.com/opencontainers/image-spec/blob/main/specs-go/v1/index.go): `specs-go/v1/index.go`
- [Image manifest](https://github.com/opencontainers/image-spec/blob/main/specs-go/v1/manifest.go): `specs-go/v1/manifest.go`
- [Image config](https://github.com/opencontainers/image-spec/blob/main/specs-go/v1/config.go): `specs-go/v1/config.go`
- [Content descriptor](https://github.com/opencontainers/image-spec/blob/main/specs-go/v1/descriptor.go): `specs-go/v1/descriptor.go`
- [Media types](https://github.com/opencontainers/image-spec/blob/main/specs-go/v1/mediatype.go): `specs-go/v1/mediatype.go`
- [Annotations](https://github.com/opencontainers/image-spec/blob/main/specs-go/v1/annotations.go): `specs-go/v1/annotations.go`
- [Schema version](https://github.com/opencontainers/image-spec/blob/main/specs-go/versioned.go): `specs-go/versioned.go`

### Validation

- [Schema validator](https://github.com/opencontainers/image-spec/blob/main/schema/validator.go): `schema/validator.go`
- [JSON schemas](https://github.com/opencontainers/image-spec/tree/main/schema): `schema`

### Identity helpers

- [Layer ChainID](https://github.com/opencontainers/image-spec/blob/main/identity/chainid.go): `identity/chainid.go`

### Other components

- **Image implementation**
- **OCI runtime**
- **OCI distribution**

## Connections

- Image implementation → Format specification: follows
- Format specification → Image layout: defines
- Image layout → Image index: contains
- Image index → Image manifest: references
- Image manifest → Image config: references
- Image manifest → Image layers: references
- Image index → Content descriptor: uses
- Image manifest → Content descriptor: uses
- Image implementation → Schema validator: validates documents
- Schema validator → JSON schemas: validates against
- Image manifest → Schema version: embeds
- Image index → Schema version: embeds
- Image implementation → Layer ChainID: calculates layer identity
- Image layout → OCI runtime: unpacks for
- Image implementation → OCI distribution: pushes or pulls via