image-spec

image-spec is the Open Container Initiative’s reference implementation for the OCI Image Format: the JSON-based data model that describes how a container image’s manifest, index, configuration, and layers are structured and addressed by content digest. It ships as a Go module providing typed structs (Descriptor, Manifest, Index, ImageConfig, Platform) that mirror the specification exactly, plus a schema package that embeds the canonical JSON Schema files and exposes a Validator type for checking raw bytes against them.

Because this module is the ground truth that downstream tools benchmark against rather than a convenience wrapper, it is vendored directly by containerd, Docker/Moby, Podman/CRI-O, BuildKit, skopeo, and ORAS to marshal, unmarshal, and validate images without each project re-deriving the schema independently. It also documents the OCI Referrers/artifact extension (ArtifactType, Subject) used by tools such as cosign for attaching signatures and attestations to images.

What You Get

• Typed manifest/index structs - v1.Manifest, v1.Index, v1.Descriptor, and v1.ImageConfig in specs-go/v1 that marshal/unmarshal directly to the OCI JSON wire format.
• Embedded JSON Schemas - the six canonical *.json schema files (content-descriptor, image-manifest, image-index, config, image-layout) bundled into the Go binary via go:embed, no network fetch needed.
• A schema.Validator type - validates raw JSON bytes against the schema for a given OCI media type, combining media-type-specific checks with general JSON Schema validation.
• Digest-based content addressing - Descriptor.Digest built on github.com/opencontainers/go-digest, matching how registries and runtimes identify blobs.
• Chain ID computation - the identity package implements the diffID-to-chainID algorithm used to derive a layer’s rootfs identity.
• Artifact/Referrers support - ArtifactType and Subject fields on Descriptor/Manifest for the OCI artifact use case (signatures, SBOMs, attestations).

Common Use Cases

• Building a container registry or proxy - use the typed structs to parse and re-serialize manifests/indexes without hand-rolling JSON handling.
• Writing an OCI-compliant build tool - construct v1.Manifest/v1.Index values that other runtimes (containerd, Podman) can consume unmodified.
• Validating third-party image content - run untrusted manifest bytes through schema.Validator before trusting or executing them.
• Attaching signatures or SBOMs to an image - use ArtifactType and Subject to build OCI Referrers-compatible artifact manifests.
• Implementing layer/rootfs identity logic - reuse the identity package’s chain ID algorithm instead of reimplementing the digest-chaining spec detail.

Under The Hood

Architecture The module is organized as three focused pieces rather than a layered application: specs-go/v1 defines the wire-format types (Descriptor, Platform, Manifest, Index, ImageConfig) with Versioned embedded from the parent specs-go package for the schemaVersion field; a separately-versioned schema submodule (its own go.mod) embeds the six canonical *.json schema files via go:embed and exposes them through a Validator string type whose Validate method dispatches to a media-type-keyed function map (validateByMediaType) before falling back to generic JSON Schema checking via santhosh-tekuri/jsonschema/v6; and identity implements the diffID-to-chainID algorithm independently of both. There is no runtime or application logic — callers marshal/unmarshal JSON into the typed structs directly, or hand raw bytes to Validator.Validate, which buffers them with bytes.NewReader so both the media-type-specific and schema-based checks can read the same payload. Because Descriptor is composed into both Manifest and Index via struct embedding, a breaking change to Descriptor propagates to every consumer that serializes or validates OCI images.

Tech Stack The root module targets Go 1.18 and declares a single external dependency, github.com/opencontainers/go-digest, for the content-addressable Digest type. The schema submodule targets Go 1.21 and pulls in santhosh-tekuri/jsonschema/v6 for Draft-compliant JSON Schema validation and russross/blackfriday/v2 for markdown handling used by its internal tooling, with golang.org/x/text as an indirect dependency. There is no web framework, database, or deployment target — this is a pure library consumed as a Go module by container runtimes and build tools. CI, defined in a single GitHub Actions workflow, is weighted toward markdown/spec linting (markdownlint) rather than a conventional build pipeline, reflecting that this repository is as much a written specification as it is code.

Code Quality The schema package carries extensive table-driven tests (manifest, image-index, image-layout, descriptor, config, and a dedicated backwards-compatibility suite) that exercise Validator against both valid and deliberately invalid fixtures, and identity has its own test file for the chain ID algorithm. The specs-go/v1 types package itself has no tests, which is appropriate since it holds only struct definitions with no behavior to exercise. Error handling in validator.go is explicit and wrapped with fmt.Errorf("...: %w", err) rather than swallowed. A .golangci.yml enables Go linting alongside a .markdownlint.yml that lints the specification prose itself — a quality signal distinctive to a specification repository. Naming is consistent, idiomatic Go, with struct tags matching the JSON schema field names exactly.

What Makes It Unique image-spec is not attempting to be novel — its value is being the normative reference that unified the pre-OCI Docker and rkt/appc image formats, and that other tools import directly rather than re-deriving. Its distinctive technical choice is keeping a machine-checkable JSON Schema and matching Go structs in lockstep within the same repository, embedded at build time via go:embed so validation requires no network access, while also extending the original image-only model to cover the newer OCI artifact use case (arbitrary content, signatures, SBOMs) via the ArtifactType and Subject fields.