runtime-spec

runtime-spec is the reference implementation package for the Open Container Initiative (OCI) Runtime Specification — the vendor-neutral standard that defines how a container’s bundle, configuration, and runtime state are structured. The specs-go package inside this repository provides the canonical Go structs (Spec, State, Process, Linux, Windows, Solaris, VM, FreeBSD, ZOS, and the features sub-package) that mirror the JSON schema published alongside the spec documents, giving Go programs a single, versioned source of truth for config.json and state.json shapes.

Because the OCI spec is the interoperability contract behind the container ecosystem, this package is imported (directly or transitively) by nearly every low-level container runtime and tool written in Go — runc, containerd, CRI-O, Podman/conmon tooling, and countless container build and inspection utilities all decode or encode against these same types rather than hand-rolling their own config structs. The repository also ships JSON Schema definitions under schema/ and a small validate CLI for checking a config or state document against them outside of Go entirely.

Versioning is intentionally conservative: the package tracks the spec’s own major/minor/patch version (exposed via specs-go.Version), and changes go through the OCI’s public RFC-style review process rather than ad hoc PRs, which is why the repo’s commit cadence is slow relative to its dependents’ — stability is the feature.

What You Get

• specs.Spec — the full OCI runtime configuration struct covering process, root filesystem, mounts, hooks, annotations, and per-platform sections (Linux, Windows, Solaris, VM, FreeBSD, ZOS)
• specs.State and specs.ContainerProcessState — the runtime-state JSON shape a compliant runtime reports back for a running container
• features.Features — a structured description of which spec capabilities (hooks, mount options, cgroup versions, seccomp actions, namespaces) a given runtime implementation actually supports
• JSON Schema files under schema/ (config-schema.json, state-schema.json, per-platform variants) plus a standalone validate CLI for checking documents outside of Go
• Versioned releases (specs-go.Version, tagged like v1.3.0) that track the spec document itself, so a Go build pin also pins the exact OCI spec revision in use

Common Use Cases

• A low-level container runtime (runc-style) unmarshals config.json into specs.Spec to know what process, mounts, and namespaces to set up
• A container build tool (bundle builder) marshals a specs.Spec to produce a spec-compliant bundle directory for any OCI runtime to consume
• A monitoring or orchestration tool decodes a running container’s state.json into specs.State to read its status and PID without depending on a specific runtime’s internals
• A runtime author calls the features sub-package’s Features struct to advertise supported hooks, seccomp actions, and cgroup versions for capability discovery by callers

Under The Hood

Architecture The module has no application logic to speak of — its entire surface is the specs-go package (config.go, state.go, version.go, and the features sub-package), a set of plain Go structs with json struct tags that mirror the markdown-and-JSON-Schema spec documents living alongside them at the repo root (config.md, runtime.md, schema/config-schema.json, etc.). There is no runtime behavior beyond (de)serialization — the schema/validate.go CLI is the one executable, and it exists purely to check a document against the JSON Schema files using an external validator library, entirely separate from the Go type definitions consumers actually import. Because dozens of independent runtimes import these types, the practical “architecture” constraint is backward compatibility: every field addition is additive and omitempty-tagged, and platform-specific sections are gated behind platform:"..." struct tags rather than separate packages, so a single Spec value works across Linux, Windows, Solaris, VM, FreeBSD, and z/OS without type-switching.

Tech Stack Pure standard-library Go — the specs-go package imports only os and fmt, with no third-party dependencies, and the repository carries no go.mod at all (it predates Go modules being mandatory and has never needed one, since consumers reference it as a version-tagged import path directly). The only place a third-party dependency shows up is the separate schema/validate.go command, which pulls in github.com/xeipuuv/gojsonschema to validate documents against the schema/*.json files; documentation is built via a Makefile that shells out to pandoc (or a Docker image wrapping it) to produce PDF/HTML renders of the spec markdown.

Code Quality There are no unit tests for the Go structs themselves — correctness is enforced externally, by the JSON Schema files under schema/ (with their own schema/test/ fixtures) and by CI (.github/workflows) running go vet, linting, and git-validation (DCO/commit-message checks) rather than functional tests, which makes sense given the package has no logic to unit-test beyond field tags. Field documentation is unusually thorough: every exported struct field carries a doc comment describing its exact JSON key and semantics, matching the corresponding prose in the markdown spec files, which is the primary quality bar for a types-only package like this.

What Makes It Unique This isn’t a typical library solving a technical problem — it’s the codified, machine-checkable form of an industry standards document. Its value is that the entire container ecosystem (runc, containerd, CRI-O, and everything built on them) agrees to decode the exact same struct shapes, so interoperability is structural rather than convention-based; the features sub-package is a more recent addition that lets runtimes self-report spec-version and capability support for callers that need to feature-detect rather than assume.