manifest/schema1: mark docker manifest v2, schema 1 deprecated

Docker Image manifest v2, schema version 1 is deprecated since 2015, when
manifest v2, schema version 2 was introduced (2e3f4934a73b27c22ae8966549e11920ffb28b81).

Users should no longer use this specification other than for backward
compatibility.

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

configuration/configuration.go

@@ -203,12 +203,24 @@ type Configuration struct {
 
 	// Compatibility is used for configurations of working with older or deprecated features.
 	Compatibility struct {
-		// Schema1 configures how schema1 manifests will be handled
+		// Schema1 configures how schema1 manifests will be handled.
+		//
+		// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since
+		// 2015. These options should only be used if you need to provide
+		// backward compatibility.
 		Schema1 struct {
 			// TrustKey is the signing key to use for adding the signature to
 			// schema1 manifests.
+			//
+			// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since
+			// 2015. These options should only be used if you need to provide
+			// backward compatibility.
 			TrustKey string `yaml:"signingkeyfile,omitempty"`
-			// Enabled determines if schema1 manifests should be pullable
+			// Enabled determines if schema1 manifests should be pullable.
+			//
+			// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since
+			// 2015. These options should only be used if you need to provide
+			// backward compatibility.
 			Enabled bool `yaml:"enabled,omitempty"`
 		} `yaml:"schema1,omitempty"`
 	} `yaml:"compatibility,omitempty"`

docs/spec/manifest-v2-1.md

@@ -6,6 +6,13 @@ keywords: registry, on-prem, images, tags, repository, distribution, api, advanc
 
 # Image Manifest Version 2, Schema 1
 
+> **Deprecated**
+>
+> Image Manifest v2, Schema 1 is deprecated. Use [Image Manifest v2, Schema 2](manifest-v2-2.md),
+> or the [OCI Image Specification](https://github.com/opencontainers/image-spec).
+> Image Manifest v2, Schema 1 should not be used for purposes other than backward
+> compatibility.
+
 This document outlines the format of the V2 image manifest. The image
 manifest described herein was introduced in the Docker daemon in the [v1.3.0
 release](https://github.com/docker/docker/commit/9f482a66ab37ec396ac61ed0c00d59122ac07453).

manifest/schema1/config_builder.go

@@ -52,6 +52,10 @@ type configManifestBuilder struct {
 // schema version from an image configuration and a set of descriptors.
 // It takes a BlobService so that it can add an empty tar to the blob store
 // if the resulting manifest needs empty layers.
+//
+// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015,
+// use Docker Image Manifest v2, Schema 2, or the OCI Image Specification v1.
+// This package should not be used for purposes other than backward compatibility.
 func NewConfigManifestBuilder(bs distribution.BlobService, pk libtrust.PrivateKey, ref reference.Named, configJSON []byte) distribution.ManifestBuilder {
 	return &configManifestBuilder{
 		bs:         bs,
@@ -61,7 +65,10 @@ func NewConfigManifestBuilder(bs distribution.BlobService, pk libtrust.PrivateKe
 	}
 }
 
-// Build produces a final manifest from the given references
+// Build produces a final manifest from the given references.
+//
+// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015.
+// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification.
 func (mb *configManifestBuilder) Build(ctx context.Context) (m distribution.Manifest, err error) {
 	type imageRootFS struct {
 		Type      string   `json:"type"`
@@ -238,7 +245,10 @@ func (mb *configManifestBuilder) emptyTar(ctx context.Context) (digest.Digest, e
 	return descriptor.Digest, nil
 }
 
-// AppendReference adds a reference to the current ManifestBuilder
+// AppendReference adds a reference to the current ManifestBuilder.
+//
+// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015.
+// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification.
 func (mb *configManifestBuilder) AppendReference(d distribution.Describable) error {
 	descriptor := d.Descriptor()
 
@@ -250,12 +260,18 @@ func (mb *configManifestBuilder) AppendReference(d distribution.Describable) err
 	return nil
 }
 
-// References returns the current references added to this builder
+// References returns the current references added to this builder.
+//
+// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015.
+// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification.
 func (mb *configManifestBuilder) References() []distribution.Descriptor {
 	return mb.descriptors
 }
 
-// MakeV1ConfigFromConfig creates an legacy V1 image config from image config JSON
+// MakeV1ConfigFromConfig creates an legacy V1 image config from image config JSON.
+//
+// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015.
+// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification.
 func MakeV1ConfigFromConfig(configJSON []byte, v1ID, parentV1ID string, throwaway bool) ([]byte, error) {
 	// Top-level v1compatibility string should be a modified version of the
 	// image config.

manifest/schema1/manifest.go

@@ -1,3 +1,9 @@
+// Package schema1 provides definitions for the deprecated Docker Image
+// Manifest v2, Schema 1 specification.
+//
+// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015.
+// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification. This package should not be used for purposes
+// other than backward compatibility.
 package schema1
 
 import (
@@ -10,18 +16,30 @@ import (
 	"github.com/opencontainers/go-digest"
 )
 
-const (
-	// MediaTypeManifest specifies the mediaType for the current version. Note
-	// that for schema version 1, the the media is optionally "application/json".
-	MediaTypeManifest = "application/vnd.docker.distribution.manifest.v1+json"
-	// MediaTypeSignedManifest specifies the mediatype for current SignedManifest version
-	MediaTypeSignedManifest = "application/vnd.docker.distribution.manifest.v1+prettyjws"
-	// MediaTypeManifestLayer specifies the media type for manifest layers
-	MediaTypeManifestLayer = "application/vnd.docker.container.image.rootfs.diff+x-gtar"
-)
+// MediaTypeManifest specifies the mediaType for the current version. Note
+// that for schema version 1, the the media is optionally "application/json".
+//
+// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015.
+// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification.
+const MediaTypeManifest = "application/vnd.docker.distribution.manifest.v1+json"
+
+// MediaTypeSignedManifest specifies the mediatype for current SignedManifest version
+//
+// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015.
+// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification.
+const MediaTypeSignedManifest = "application/vnd.docker.distribution.manifest.v1+prettyjws"
+
+// MediaTypeManifestLayer specifies the media type for manifest layers
+//
+// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015.
+// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification.
+const MediaTypeManifestLayer = "application/vnd.docker.container.image.rootfs.diff+x-gtar"
 
 // SchemaVersion provides a pre-initialized version structure for this
 // packages version of the manifest.
+//
+// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015.
+// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification.
 var SchemaVersion = manifest.Versioned{
 	SchemaVersion: 1,
 }
@@ -55,13 +73,19 @@ func init() {
 	}
 }
 
-// FSLayer is a container struct for BlobSums defined in an image manifest
+// FSLayer is a container struct for BlobSums defined in an image manifest.
+//
+// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015.
+// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification.
 type FSLayer struct {
 	// BlobSum is the tarsum of the referenced filesystem image layer
 	BlobSum digest.Digest `json:"blobSum"`
 }
 
-// History stores unstructured v1 compatibility information
+// History stores unstructured v1 compatibility information.
+//
+// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015.
+// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification.
 type History struct {
 	// V1Compatibility is the raw v1 compatibility information
 	V1Compatibility string `json:"v1Compatibility"`
@@ -69,6 +93,9 @@ type History struct {
 
 // Manifest provides the base accessible fields for working with V2 image
 // format in the registry.
+//
+// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015.
+// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification.
 type Manifest struct {
 	manifest.Versioned
 
@@ -91,6 +118,9 @@ type Manifest struct {
 
 // SignedManifest provides an envelope for a signed image manifest, including
 // the format sensitive raw bytes.
+//
+// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015.
+// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification.
 type SignedManifest struct {
 	Manifest
 
@@ -105,6 +135,9 @@ type SignedManifest struct {
 }
 
 // UnmarshalJSON populates a new SignedManifest struct from JSON data.
+//
+// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015.
+// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification.
 func (sm *SignedManifest) UnmarshalJSON(b []byte) error {
 	sm.all = make([]byte, len(b))
 	// store manifest and signatures in all
@@ -136,7 +169,10 @@ func (sm *SignedManifest) UnmarshalJSON(b []byte) error {
 	return nil
 }
 
-// References returns the descriptors of this manifests references
+// References returns the descriptors of this manifests references.
+//
+// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015.
+// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification.
 func (sm SignedManifest) References() []distribution.Descriptor {
 	dependencies := make([]distribution.Descriptor, len(sm.FSLayers))
 	for i, fsLayer := range sm.FSLayers {
@@ -153,6 +189,9 @@ func (sm SignedManifest) References() []distribution.Descriptor {
 // contents. Applications requiring a marshaled signed manifest should simply
 // use Raw directly, since the the content produced by json.Marshal will be
 // compacted and will fail signature checks.
+//
+// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015.
+// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification.
 func (sm *SignedManifest) MarshalJSON() ([]byte, error) {
 	if len(sm.all) > 0 {
 		return sm.all, nil
@@ -163,6 +202,9 @@ func (sm *SignedManifest) MarshalJSON() ([]byte, error) {
 }
 
 // Payload returns the signed content of the signed manifest.
+//
+// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015.
+// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification.
 func (sm SignedManifest) Payload() (string, []byte, error) {
 	return MediaTypeSignedManifest, sm.all, nil
 }
@@ -170,6 +212,9 @@ func (sm SignedManifest) Payload() (string, []byte, error) {
 // Signatures returns the signatures as provided by
 // (*libtrust.JSONSignature).Signatures. The byte slices are opaque jws
 // signatures.
+//
+// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015.
+// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification.
 func (sm *SignedManifest) Signatures() ([][]byte, error) {
 	jsig, err := libtrust.ParsePrettySignature(sm.all, "signatures")
 	if err != nil {

manifest/schema1/reference_builder.go

@@ -21,6 +21,9 @@ type referenceManifestBuilder struct {
 
 // NewReferenceManifestBuilder is used to build new manifests for the current
 // schema version using schema1 dependencies.
+//
+// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015.
+// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification.
 func NewReferenceManifestBuilder(pk libtrust.PrivateKey, ref reference.Named, architecture string) distribution.ManifestBuilder {
 	tag := ""
 	if tagged, isTagged := ref.(reference.Tagged); isTagged {
@@ -54,7 +57,10 @@ func (mb *referenceManifestBuilder) Build(ctx context.Context) (distribution.Man
 	return Sign(&m, mb.pk)
 }
 
-// AppendReference adds a reference to the current ManifestBuilder
+// AppendReference adds a reference to the current ManifestBuilder.
+//
+// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015.
+// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification.
 func (mb *referenceManifestBuilder) AppendReference(d distribution.Describable) error {
 	r, ok := d.(Reference)
 	if !ok {
@@ -67,7 +73,10 @@ func (mb *referenceManifestBuilder) AppendReference(d distribution.Describable)
 	return nil
 }
 
-// References returns the current references added to this builder
+// References returns the current references added to this builder.
+//
+// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015.
+// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification.
 func (mb *referenceManifestBuilder) References() []distribution.Descriptor {
 	refs := make([]distribution.Descriptor, len(mb.Manifest.FSLayers))
 	for i := range mb.Manifest.FSLayers {
@@ -79,15 +88,21 @@ func (mb *referenceManifestBuilder) References() []distribution.Descriptor {
 	return refs
 }
 
-// Reference describes a manifest v2, schema version 1 dependency.
+// Reference describes a Manifest v2, schema version 1 dependency.
 // An FSLayer associated with a history entry.
+//
+// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015.
+// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification.
 type Reference struct {
 	Digest  digest.Digest
 	Size    int64 // if we know it, set it for the descriptor.
 	History History
 }
 
-// Descriptor describes a reference
+// Descriptor describes a reference.
+//
+// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015.
+// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification.
 func (r Reference) Descriptor() distribution.Descriptor {
 	return distribution.Descriptor{
 		MediaType: MediaTypeManifestLayer,

manifest/schema1/sign.go

@@ -10,6 +10,9 @@ import (
 // Sign signs the manifest with the provided private key, returning a
 // SignedManifest. This typically won't be used within the registry, except
 // for testing.
+//
+// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015.
+// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification.
 func Sign(m *Manifest, pk libtrust.PrivateKey) (*SignedManifest, error) {
 	p, err := json.MarshalIndent(m, "", "   ")
 	if err != nil {
@@ -40,6 +43,9 @@ func Sign(m *Manifest, pk libtrust.PrivateKey) (*SignedManifest, error) {
 // SignWithChain signs the manifest with the given private key and x509 chain.
 // The public key of the first element in the chain must be the public key
 // corresponding with the sign key.
+//
+// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015.
+// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification.
 func SignWithChain(m *Manifest, key libtrust.PrivateKey, chain []*x509.Certificate) (*SignedManifest, error) {
 	p, err := json.MarshalIndent(m, "", "   ")
 	if err != nil {

manifest/schema1/verify.go

@@ -9,6 +9,9 @@ import (
 
 // Verify verifies the signature of the signed manifest returning the public
 // keys used during signing.
+//
+// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015.
+// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification.
 func Verify(sm *SignedManifest) ([]libtrust.PublicKey, error) {
 	js, err := libtrust.ParsePrettySignature(sm.all, "signatures")
 	if err != nil {
@@ -22,6 +25,9 @@ func Verify(sm *SignedManifest) ([]libtrust.PublicKey, error) {
 // VerifyChains verifies the signature of the signed manifest against the
 // certificate pool returning the list of verified chains. Signatures without
 // an x509 chain are not checked.
+//
+// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015.
+// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification.
 func VerifyChains(sm *SignedManifest, ca *x509.CertPool) ([][]*x509.Certificate, error) {
 	js, err := libtrust.ParsePrettySignature(sm.all, "signatures")
 	if err != nil {

testutil/manifests.go

@@ -40,7 +40,10 @@ func MakeManifestList(blobstatter distribution.BlobStatter, manifestDigests []di
 }
 
 // MakeSchema1Manifest constructs a schema 1 manifest from a given list of digests and returns
-// the digest of the manifest
+// the digest of the manifest.
+//
+// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015.
+// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification.
 func MakeSchema1Manifest(digests []digest.Digest) (distribution.Manifest, error) {
 	manifest := schema1.Manifest{
 		Versioned: manifest.Versioned{