docker · jcarter3 · May 15, 2026
diff --git a/README.md b/README.md
@@ -87,9 +87,9 @@ import (
 	"encoding/json"
 	"fmt"
 
+	"github.com/docker/oci"
 	"github.com/docker/oci/ociauth"
 	"github.com/docker/oci/ociclient"
-	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
 )
 
 func main() {
@@ -117,7 +117,7 @@ func main() {
 	fmt.Printf("media type: %s\n", r.Descriptor().MediaType)
 	fmt.Printf("digest:     %s\n", r.Descriptor().Digest)
 
-	var manifest ocispec.Manifest
+	var manifest oci.IndexOrManifest
 	if err := json.NewDecoder(r).Decode(&manifest); err != nil {
 		panic(err)
 	}
@@ -196,4 +196,4 @@ func main() {
 	handler := ociserver.New(backend, nil)
 	http.ListenAndServe(":5000", handler)
 }
-```
+```
diff --git a/go.mod b/go.mod
@@ -3,8 +3,6 @@ module github.com/docker/oci
 go 1.25.0
 
 require (
-	github.com/opencontainers/go-digest v1.0.0
-	github.com/opencontainers/image-spec v1.1.1
 	github.com/rogpeppe/go-internal v1.14.1
 	github.com/stretchr/testify v1.11.1
 )

diff --git a/go.sum b/go.sum
@@ -1,9 +1,5 @@
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/opencontainers/go-digest v1.0.0 h1:apOUWs51W5PlhuyGyz9FCeeBIOUDA/6nW8Oi/yOhh5U=
-github.com/opencontainers/go-digest v1.0.0/go.mod h1:0JzlMkj0TRzQZfJkVvzbP0HBR3IKzErnv2BNG4W4MAM=
-github.com/opencontainers/image-spec v1.1.1 h1:y0fUlFfIZhPF1W537XOLg0/fcx6zcHCJwooC2xJA040=
-github.com/opencontainers/image-spec v1.1.1/go.mod h1:qpqAh3Dmcf36wStyyWU+kCeDgrGnAve2nCC8+7h8Q0M=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=

diff --git a/interface.go b/interface.go
@@ -60,9 +60,6 @@ import (
 	"context"
 	"io"
 	"iter"
-
-	"github.com/docker/oci/ociref"
-	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
 )
 
 // Interface defines a generic interface to a single OCI registry.
@@ -83,16 +80,6 @@ type ReadWriter interface {
 	Writer
 }
 
-// Type aliases for commonly used OCI types.
-type (
-	// Digest is a content-addressable digest. It is an alias for [ociref.Digest].
-	Digest = ociref.Digest
-	// Descriptor describes the disposition of targeted content. It is an alias for [ocispec.Descriptor].
-	Descriptor = ocispec.Descriptor
-	// Manifest provides the `application/vnd.oci.image.manifest.v1+json` mediatype structure. It is an alias for [ocispec.Manifest].
-	Manifest = ocispec.Manifest
-)
-
 // Reader defines registry operations that read blobs, manifests and tags.
 type Reader interface {
 	// GetBlob returns the content of the blob with the given digest.

diff --git a/models.go b/models.go
@@ -0,0 +1,222 @@
+// Copyright 2023 CUE Labs AG
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package oci
+
+import (
+	"encoding/json"
+	"fmt"
+
+	"github.com/docker/oci/ocidigest"
+)
+
+const (
+	// MediaTypeImageIndex specifies the media type for an image index.
+	MediaTypeImageIndex = "application/vnd.oci.image.index.v1+json"
+	// MediaTypeImageManifest specifies the media type for an image manifest.
+	MediaTypeImageManifest = "application/vnd.oci.image.manifest.v1+json"
+	// MediaTypeDockerManifestList is the media type Docker used to use for an index
+	MediaTypeDockerManifestList = "application/vnd.docker.distribution.manifest.list.v2+json"
+	// MediaTypeDockerManifest is the mediat type Docker used to use for a manifest
+	MediaTypeDockerManifest = "application/vnd.docker.distribution.manifest.v2+json"
+
+	// MediaTypeImageConfig specifies the media type for the image configuration.
+	MediaTypeImageConfig = "application/vnd.oci.image.config.v1+json"
+
+	// MaxMediaTypeLen is the maximum allowed length for any mediaType field.
+	MaxMediaTypeLen = 255
+	// MaxArtifactTypeLen is the maximum allowed length for any artifactType field.
+	MaxArtifactTypeLen = 255
+	// MaxAnnotationKeyLen is the maximum allowed length for an annotation key.
+	MaxAnnotationKeyLen = 255
+)
+
+// Digest is a content-addressable digest.
+type Digest = ocidigest.Digest
+
+// Descriptor describes the disposition of targeted content.
+type Descriptor struct {
+	// MediaType is the media type of the object this schema refers to.
+	MediaType string `json:"mediaType"`
+
+	// Digest is the digest of the targeted content.
+	Digest Digest `json:"digest"`
+
+	// Size specifies the size in bytes of the blob.
+	Size int64 `json:"size"`
+
+	// URLs specifies a list of URLs from which this object MAY be downloaded.
+	URLs []string `json:"urls,omitempty"`
+
+	// Annotations contains arbitrary metadata relating to the targeted content.
+	Annotations map[string]string `json:"annotations,omitempty"`
+
+	// Data is an embedding of the targeted content.
+	Data []byte `json:"data,omitempty"`
+
+	// Platform describes the platform which the image in the manifest runs on.
+	Platform *Platform `json:"platform,omitempty"`
+
+	// ArtifactType is the IANA media type of this artifact.
+	ArtifactType string `json:"artifactType,omitempty"`
+}
+
+// Platform describes the platform which the image in the manifest runs on.
+type Platform struct {
+	// Architecture field specifies the CPU architecture, for example amd64 or ppc64le.
+	Architecture string `json:"architecture"`
+
+	// OS specifies the operating system, for example linux or windows.
+	OS string `json:"os"`
+
+	// OSVersion is an optional field specifying the operating system version.
+	OSVersion string `json:"os.version,omitempty"`
+
+	// OSFeatures is an optional field specifying an array of strings listing required OS features.
+	OSFeatures []string `json:"os.features,omitempty"`
+
+	// Variant is an optional field specifying a variant of the CPU.
+	Variant string `json:"variant,omitempty"`
+}
+
+// IndexOrManifest parses the required fields out of a manifest json file. It handles indexes and manifests.
+type IndexOrManifest struct {
+	SchemaVersion int `json:"schemaVersion"`
+
+	// MediaType specifies the type of this document data structure e.g. `application/vnd.oci.image.manifest.v1+json` // TODO: add validation... if index, make sure it has manifests instead of layers?
+	MediaType string `json:"mediaType,omitempty"`
+
+	// ArtifactType specifies the IANA media type of artifact when the manifest is used for an artifact.
+	ArtifactType string `json:"artifactType,omitempty"`
+
+	// Manifests references platform specific manifests.
+	Manifests []Descriptor `json:"manifests"`
+
+	// Config references a configuration object for a container, by digest.
+	// The referenced configuration object is a JSON blob that the runtime uses to set up the container.
+	Config *Descriptor `json:"config"`
+
+	// Layers is an indexed list of layers referenced by the manifest.
+	Layers []Descriptor `json:"layers"`
+
+	// Subject is an optional link from the image manifest to another manifest forming an association between the image manifest and the other manifest.
+	Subject *Descriptor `json:"subject,omitempty"`
+
+	// Annotations contains arbitrary metadata for the image manifest.
+	Annotations map[string]string `json:"annotations,omitempty"`
+}
+
+// Validate checks the manifest for structural correctness and field length limits.
+func (m IndexOrManifest) Validate() error {
+	if m.SchemaVersion == 1 {
+		return fmt.Errorf("schema version 1 (Docker V1) manifests are not supported")
+	}
+	switch m.MediaType {
+	case MediaTypeImageIndex, MediaTypeDockerManifestList:
+		if m.Config != nil {
+			return fmt.Errorf("config not supported on index")
+		}
+		if len(m.Layers) > 0 {
+			return fmt.Errorf("layers not supported on index")
+		}
+	case MediaTypeImageManifest, MediaTypeDockerManifest:
+		if len(m.Manifests) > 0 {
+			return fmt.Errorf("manifests field not supported on manifest")
+		}
+		if m.Config == nil {
+			return fmt.Errorf("missing config")
+		}
+	}
+	if len(m.MediaType) > MaxMediaTypeLen {
+		return fmt.Errorf("mediaType exceeds maximum length of %d", MaxMediaTypeLen)
+	}
+	if len(m.ArtifactType) > MaxArtifactTypeLen {
+		return fmt.Errorf("artifactType exceeds maximum length of %d", MaxArtifactTypeLen)
+	}
+	for k := range m.Annotations {
+		if len(k) > MaxAnnotationKeyLen {
+			return fmt.Errorf("annotation key exceeds maximum length of %d", MaxAnnotationKeyLen)
+		}
+	}
+	for i, d := range m.Manifests {
+		if err := validateDescriptor("manifests", i, d); err != nil {
+			return err
+		}
+	}
+	for i, d := range m.Layers {
+		if err := validateDescriptor("layers", i, d); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// MarshalJSON validates m before encoding it as JSON.
+func (m IndexOrManifest) MarshalJSON() ([]byte, error) {
+	if err := m.Validate(); err != nil {
+		return nil, err
+	}
+	type common struct {
+		SchemaVersion int               `json:"schemaVersion"`
+		MediaType     string            `json:"mediaType,omitempty"`
+		ArtifactType  string            `json:"artifactType,omitempty"`
+		Subject       *Descriptor       `json:"subject,omitempty"`
+		Annotations   map[string]string `json:"annotations,omitempty"`
+	}
+	c := common{
+		SchemaVersion: m.SchemaVersion,
+		MediaType:     m.MediaType,
+		ArtifactType:  m.ArtifactType,
+		Subject:       m.Subject,
+		Annotations:   m.Annotations,
+	}
+	switch m.MediaType {
+	case MediaTypeImageIndex, MediaTypeDockerManifestList:
+		return json.Marshal(struct {
+			common
+			Manifests []Descriptor `json:"manifests"`
+		}{
+			common:    c,
+			Manifests: m.Manifests,
+		})
+	case MediaTypeImageManifest, MediaTypeDockerManifest:
+		return json.Marshal(struct {
+			common
+			Config *Descriptor  `json:"config"`
+			Layers []Descriptor `json:"layers"`
+		}{
+			common: c,
+			Config: m.Config,
+			Layers: m.Layers,
+		})
+	default:
+		type indexOrManifest IndexOrManifest
+		return json.Marshal(indexOrManifest(m))
+	}
+}
+
+func validateDescriptor(field string, i int, d Descriptor) error {
+	if len(d.MediaType) > MaxMediaTypeLen {
+		return fmt.Errorf("%s[%d].mediaType exceeds maximum length of %d", field, i, MaxMediaTypeLen)
+	}
+	if len(d.ArtifactType) > MaxArtifactTypeLen {
+		return fmt.Errorf("%s[%d].artifactType exceeds maximum length of %d", field, i, MaxArtifactTypeLen)
+	}
+	for k := range d.Annotations {
+		if len(k) > MaxAnnotationKeyLen {
+			return fmt.Errorf("%s[%d] annotation key exceeds maximum length of %d", field, i, MaxAnnotationKeyLen)
+		}
+	}
+	return nil
+}
diff --git a/ociclient/auth_test.go b/ociclient/auth_test.go
@@ -10,13 +10,15 @@ import (
 
 	"github.com/docker/oci"
 	"github.com/docker/oci/ociauth"
+	"github.com/docker/oci/ocidigest"
 	"github.com/docker/oci/ocimem"
 	"github.com/docker/oci/ociserver"
-	"github.com/opencontainers/go-digest"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 
+var testDigest = ocidigest.FromBytes([]byte("test"))
+
 func TestAuthScopes(t *testing.T) {
 
 	// Test that we're passing the expected authorization scopes to the various parts of the API.
@@ -32,30 +34,30 @@ func TestAuthScopes(t *testing.T) {
 	}
 
 	assertScope("repository:foo/bar:pull", func(ctx context.Context, r oci.Interface) {
-		r.GetBlob(ctx, "foo/bar", "sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff")
+		r.GetBlob(ctx, "foo/bar", testDigest)
 	})
 	assertScope("repository:foo/bar:pull", func(ctx context.Context, r oci.Interface) {
-		r.GetBlobRange(ctx, "foo/bar", "sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff", 100, 200)
+		r.GetBlobRange(ctx, "foo/bar", testDigest, 100, 200)
 	})
 	assertScope("repository:foo/bar:pull", func(ctx context.Context, r oci.Interface) {
-		r.GetManifest(ctx, "foo/bar", "sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff")
+		r.GetManifest(ctx, "foo/bar", testDigest)
 	})
 	assertScope("repository:foo/bar:pull", func(ctx context.Context, r oci.Interface) {
 		r.GetTag(ctx, "foo/bar", "sometag")
 	})
 	assertScope("repository:foo/bar:pull", func(ctx context.Context, r oci.Interface) {
-		r.ResolveBlob(ctx, "foo/bar", "sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff")
+		r.ResolveBlob(ctx, "foo/bar", testDigest)
 	})
 	assertScope("repository:foo/bar:pull", func(ctx context.Context, r oci.Interface) {
-		r.ResolveManifest(ctx, "foo/bar", "sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff")
+		r.ResolveManifest(ctx, "foo/bar", testDigest)
 	})
 	assertScope("repository:foo/bar:pull", func(ctx context.Context, r oci.Interface) {
 		r.ResolveTag(ctx, "foo/bar", "sometag")
 	})
 	assertScope("repository:foo/bar:push", func(ctx context.Context, r oci.Interface) {
 		r.PushBlob(ctx, "foo/bar", oci.Descriptor{
 			MediaType: "application/json",
-			Digest:    "sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
+			Digest:    testDigest,
 			Size:      3,
 		}, strings.NewReader("foo"))
 	})
@@ -69,22 +71,22 @@ func TestAuthScopes(t *testing.T) {
 		w, err = r.PushBlobChunkedResume(ctx, "foo/bar", id, 3, 0)
 		require.NoError(t, err)
 		w.Write([]byte("bar"))
-		_, err = w.Commit(digest.FromString("foobar"))
+		_, err = w.Commit(ocidigest.FromBytes([]byte("foobar")))
 		require.NoError(t, err)
 	})
 	assertScope("repository:x/y:pull repository:z/w:push", func(ctx context.Context, r oci.Interface) {
-		r.MountBlob(ctx, "x/y", "z/w", "sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff")
+		r.MountBlob(ctx, "x/y", "z/w", testDigest)
 	})
 	assertScope("repository:foo/bar:push", func(ctx context.Context, r oci.Interface) {
 		r.PushManifest(ctx, "foo/bar", []byte("something"), "application/json", &oci.PushManifestParameters{
 			Tags: []string{"sometag"},
 		})
 	})
 	assertScope("repository:foo/bar:push", func(ctx context.Context, r oci.Interface) {
-		r.DeleteBlob(ctx, "foo/bar", "sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff")
+		r.DeleteBlob(ctx, "foo/bar", testDigest)
 	})
 	assertScope("repository:foo/bar:push", func(ctx context.Context, r oci.Interface) {
-		r.DeleteManifest(ctx, "foo/bar", "sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff")
+		r.DeleteManifest(ctx, "foo/bar", testDigest)
 	})
 	assertScope("repository:foo/bar:push", func(ctx context.Context, r oci.Interface) {
 		r.DeleteTag(ctx, "foo/bar", "sometag")
@@ -96,7 +98,7 @@ func TestAuthScopes(t *testing.T) {
 		oci.All(r.Tags(ctx, "foo/bar", nil))
 	})
 	assertScope("repository:foo/bar:pull", func(ctx context.Context, r oci.Interface) {
-		oci.All(r.Referrers(ctx, "foo/bar", "sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff", nil))
+		oci.All(r.Referrers(ctx, "foo/bar", testDigest, nil))
 	})
 }