oci-spec

oci-spec is a Rust library that provides a convenient, strongly typed way to work with the specifications defined by the Open Container Initiative (OCI). It models the Image Format, Runtime, and Distribution specs as native Rust structs and enums, so tools that build, inspect, or run containers can serialize and deserialize spec documents without hand-rolling JSON schemas.

Used as the foundation for container runtimes like youki, the crate pairs serde-based (de)serialization with derive_builder-powered builder APIs and getset accessors, giving you spec-compliant types that are easy to construct, validate, and round-trip. Each specification is behind its own Cargo feature so you only compile the parts you need.

What You Get

• Rust types for the OCI Image Format specification (manifests, configs, descriptors)
• Rust types for the OCI Runtime specification (config.json, process, mounts, linux settings)
• Rust types for the OCI Distribution specification
• serde-based serialization/deserialization to and from JSON
• Builder APIs and getters/setters for constructing and mutating spec documents

Common Use Cases

• Building a container runtime that must parse and honor an OCI runtime config.json
• Generating or inspecting OCI image manifests and configs in a registry or build tool
• Implementing an OCI distribution client or server with correctly typed payloads
• Validating that container artifacts conform to the OCI specifications

Under The Hood

Architecture - The crate is split into three top-level modules under src/ — image/, runtime/, and distribution/ — each corresponding to one OCI specification and gated behind a same-named Cargo feature (all on by default). Types are plain data structures deriving Serialize/Deserialize, with derive_builder generating builders and getset generating accessors; strum provides enum string conversions and thiserror defines the error types.

Tech Stack - Pure Rust (edition 2021, rustc 1.54+). Core dependencies are serde + serde_json for (de)serialization, derive_builder and getset for ergonomic construction, strum/strum_macros for enums, const_format and regex for validation helpers, and optional quickcheck for property tests. It is categorized on crates.io as api-bindings.

Code Quality - Strong and well maintained: 600+ commits from 64 contributors, codecov-tracked coverage, rstest-based tests plus optional quickcheck property testing, and generated docs published to both docs.rs and GitHub Pages. Because the crate is pure data modeling, correctness hinges on faithful spec representation, which the test suite and wide downstream usage (e.g. youki) help guarantee.

API Design - Clean and predictable. Every spec object gets a builder for construction and typed getters/setters for access, so callers never touch raw JSON. Feature flags keep the surface minimal, and the module layout maps one-to-one onto the OCI specs, making the API easy to navigate for anyone familiar with the underlying standards.