OCI Image vs Docker Image
This cheatsheet compares the OCI (Open Container Initiative) Image Specification and the Docker Image Manifest V2, Schema 2 (often referred to as Docker v2 image format).
TL;DR: The OCI Image Specification is an open standard heavily based on and derived from Docker's v2 schema 2 format. They are structurally very similar, aiming for interoperability. The primary technical difference lies in the specific media types used within the manifests and configuration objects. Modern container tools often handle both formats transparently.
Key Concepts
- Image Manifest: A JSON file describing the components of a container image, including its configuration and layers.
- Image Index / Manifest List: A higher-level JSON file that points to multiple image manifests, typically used for multi-architecture images.
- Image Configuration: A JSON file detailing image runtime parameters like environment variables, entrypoint, command, exposed ports, etc.
- Layers: Tarballs (often gzipped) representing filesystem diffs that make up the container image.
- Media Type (MIME Type): A string identifying the format of a resource (e.g.,
application/json,application/vnd.oci.image.manifest.v1+json). This is the main technical differentiator visible in the spec documents.
Comparison Table
| Feature | Docker Image Manifest V2, Schema 2 | OCI Image Specification v1.x | Key Difference / Notes |
|---|---|---|---|
| Origin | Developed by Docker, Inc. | Developed by the Open Container Initiative (OCI), a Linux Foundation project. | OCI was formed by Docker and other industry leaders to create open standards. |
| Goal | Serve the needs of the Docker Engine & ecosystem. | Create an open, interoperable standard for container images across different tools and runtimes. | OCI aims for wider industry adoption and prevents vendor lock-in. |
| Governance | Controlled by Docker, Inc. | Governed by the OCI community under the Linux Foundation. | OCI is vendor-neutral. |
| Specification | Defined by Docker documentation (initially). | Formal specification documents hosted by OCI (on GitHub). | OCI provides a more formalized, versioned spec. |
| Base | N/A (Original) | Heavily based on and derived from Docker v2 schema 2. | Docker donated v2 schema 2 as the foundation for the OCI spec. Structure is extremely similar. |
| Manifest Media Type | application/vnd.docker.distribution.manifest.v2+json |
application/vnd.oci.image.manifest.v1+json |
Primary technical difference. Identifies the type of manifest document. |
| Manifest List / Image Index Media Type | application/vnd.docker.distribution.manifest.list.v2+json |
application/vnd.oci.image.index.v1+json |
Primary technical difference. Identifies the multi-arch manifest list / index. |
| Config Media Type | application/vnd.docker.container.image.v1+json |
application/vnd.oci.image.config.v1+json |
Primary technical difference. Identifies the image configuration JSON. |
| Layer Media Types (Examples) | application/vnd.docker.image.rootfs.diff.tar.gzip |
application/vnd.oci.image.layer.v1.tar+gzip (common) application/vnd.oci.image.layer.nondistributable.v1.tar+gzip |
OCI defines standard and non-distributable layer types. |
| Compatibility | OCI-compliant runtimes (containerd, CRI-O) typically support Docker v2 format for backward compatibility. | Modern Docker Engine (using containerd) can pull/run OCI images. Many build tools (Buildah, Podman) default to OCI. | High degree of compatibility due to shared structure. Tools often convert or handle both transparently. |
| Industry Adoption | De facto standard due to Docker's popularity. | The official industry standard, increasingly adopted by tools and registries. | OCI is the forward-looking standard. |
| Extensibility | Via annotations (less formalized early on). | Formalized support for annotations in manifests and indexes. | OCI provides clearer guidelines for extensions. |
Key Takeaways
- Similarity: The OCI image spec is fundamentally based on Docker v2, schema 2. Their structure (manifest referencing config and layers) is almost identical.
- Standardization: OCI provides a vendor-neutral, community-governed standard, promoting interoperability between container tools (Docker, Podman, Buildah, Kaniko, containerd, CRI-O, etc.) and registries.
- Media Types: The most significant technical difference is the set of media types used to identify the JSON manifests, indexes, configuration blobs, and layers. Tools use these media types to understand how to interpret the content.
- Compatibility: Due to the shared heritage, there's excellent compatibility. OCI runtimes usually read Docker v2 images, and modern Docker can read OCI images. Registries generally support pushing/pulling both formats.
- Future: OCI is the direction the container ecosystem has standardized upon. New tools and features are more likely to prioritize OCI compliance. While Docker v2 remains prevalent due to history, building/using OCI images is generally recommended for future-proofing and broader compatibility.
In practice, when you build or pull images using modern tools, the tool often handles the specific format details for you. You might see different media types if you inspect the manifest JSON directly (e.g., using skopeo inspect or docker manifest inspect), but the runtime behavior is typically the same.