api/types/image: InspectResponse: deprecate Parent, DockerVersion

thaJeztah · thaJeztah · commit bd8a99b4004b · 2025-10-05T23:00:18.000+02:00
The image inspect response has various fields that were deprecated as part of the legacy builder, or Dockerfile syntax; - The `Parent` field is only used for the legacy builder, and only set for images that are built locally (i.e., not persisted when pulling an image). - The `DockerVersion` field is only set when building images with the legacy builder, and empty in most cases. This patch deprecates the fields in the `InspectResponse` go struct, as these fields will no longer be set in future once the legacy builder is removed (`Parent`, `DockerVersion`). The legacy builder's deprecation in [cli@4d8e457] / [cli@fd22746] (docker 23.0, API v1.42), however the related API fields were kept so that information of legacy images would not be discarded. The API continues to return these fields if set, allowing the client to print the fields for informational purposes when printing the raw response, but these fields should be considered "transitional", and not be depended on; deprecating the fields helps raise awareness. [cli@4d8e457]: docker/cli@4d8e457 [cli@fd22746]: docker/cli@fd22746 Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
diff --git a/api/docs/CHANGELOG.md b/api/docs/CHANGELOG.md
@@ -68,6 +68,12 @@ keywords: "API, Docker, rcli, REST, documentation"
   in the next API version.
 * Deprecated: The field `KernelMemoryTCP` as part of `GET /info` is deprecated
   and will be removed in the next API version.
+* Deprecated: the `Parent` and `DockerVersion` fields returned by the
+  `GET /images/{name}/json` endpoint are deprecated. These fields are set by
+  the legacy builder, and are no longer set when using BuildKit. The API
+  continues returning these fields when set for informational purposes, but
+  they should not be depended on as they will be omitted once the legacy builder
+  is removed.
 
 ## v1.50 API changes
 
diff --git a/api/docs/v1.51.yaml b/api/docs/v1.51.yaml
@@ -1938,6 +1938,11 @@ definitions:
           Depending on how the image was created, this field may be empty and
           is only set for images that were built/created locally. This field
           is empty if the image was pulled from an image registry.
+
+          > **Deprecated**: This field is only set when using the deprecated
+          > legacy builder. It is included in API responses for informational
+          > purposes, but should not be depended on as it will be omitted
+          > once the legacy builder is removed.
         type: "string"
         x-nullable: false
         example: ""
@@ -1963,6 +1968,11 @@ definitions:
           The version of Docker that was used to build the image.
 
           Depending on how the image was created, this field may be empty.
+
+          > **Deprecated**: This field is only set when using the deprecated
+          > legacy builder. It is included in API responses for informational
+          > purposes, but should not be depended on as it will be omitted
+          > once the legacy builder is removed.
         type: "string"
         x-nullable: false
         example: "27.0.1"
diff --git a/api/docs/v1.52.yaml b/api/docs/v1.52.yaml
@@ -1838,6 +1838,11 @@ definitions:
           Depending on how the image was created, this field may be empty and
           is only set for images that were built/created locally. This field
           is empty if the image was pulled from an image registry.
+
+          > **Deprecated**: This field is only set when using the deprecated
+          > legacy builder. It is included in API responses for informational
+          > purposes, but should not be depended on as it will be omitted
+          > once the legacy builder is removed.
         type: "string"
         x-nullable: true
         example: ""
@@ -1863,6 +1868,11 @@ definitions:
           The version of Docker that was used to build the image.
 
           Depending on how the image was created, this field may be empty.
+
+          > **Deprecated**: This field is only set when using the deprecated
+          > legacy builder. It is included in API responses for informational
+          > purposes, but should not be depended on as it will be omitted
+          > once the legacy builder is removed.
         type: "string"
         x-nullable: true
         example: "27.0.1"
diff --git a/api/swagger.yaml b/api/swagger.yaml
@@ -1838,6 +1838,11 @@ definitions:
           Depending on how the image was created, this field may be empty and
           is only set for images that were built/created locally. This field
           is empty if the image was pulled from an image registry.
+
+          > **Deprecated**: This field is only set when using the deprecated
+          > legacy builder. It is included in API responses for informational
+          > purposes, but should not be depended on as it will be omitted
+          > once the legacy builder is removed.
         type: "string"
         x-nullable: true
         example: ""
@@ -1863,6 +1868,11 @@ definitions:
           The version of Docker that was used to build the image.
 
           Depending on how the image was created, this field may be empty.
+
+          > **Deprecated**: This field is only set when using the deprecated
+          > legacy builder. It is included in API responses for informational
+          > purposes, but should not be depended on as it will be omitted
+          > once the legacy builder is removed.
         type: "string"
         x-nullable: true
         example: "27.0.1"
diff --git a/api/types/image/image_inspect.go b/api/types/image/image_inspect.go
@@ -48,6 +48,8 @@ type InspectResponse struct {
 	// Depending on how the image was created, this field may be empty and
 	// is only set for images that were built/created locally. This field
 	// is omitted if the image was pulled from an image registry.
+	//
+	// Deprecated: this field is deprecated, and will be removed in the next release.
 	Parent string `json:",omitempty"`
 
 	// Comment is an optional message that can be set when committing or
@@ -80,6 +82,8 @@ type InspectResponse struct {
 	// DockerVersion is the version of Docker that was used to build the image.
 	//
 	// Depending on how the image was created, this field may be omitted.
+	//
+	// Deprecated: this field is deprecated, and will be removed in the next release.
 	DockerVersion string `json:",omitempty"`
 
 	// Author is the name of the author that was specified when committing the
diff --git a/daemon/containerd/image_inspect.go b/daemon/containerd/image_inspect.go
@@ -86,14 +86,13 @@ func (i *ImageService) ImageInspect(ctx context.Context, refOrID string, opts ba
 	}
 
 	resp := &imagetypes.InspectResponse{
-		ID:            target.Digest.String(),
-		RepoTags:      repoTags,
-		Descriptor:    &target,
-		RepoDigests:   repoDigests,
-		Parent:        parent,
-		DockerVersion: "",
-		Size:          size,
-		Manifests:     manifests,
+		ID:          target.Digest.String(),
+		RepoTags:    repoTags,
+		Descriptor:  &target,
+		RepoDigests: repoDigests,
+		Parent:      parent, //nolint:staticcheck // ignore SA1019: field is deprecated, but still included in response when present.
+		Size:        size,
+		Manifests:   manifests,
 		Metadata: imagetypes.Metadata{
 			LastTagTime: lastUpdated,
 		},
diff --git a/daemon/images/image_inspect.go b/daemon/images/image_inspect.go
@@ -58,12 +58,12 @@ func (i *ImageService) ImageInspect(ctx context.Context, refOrID string, opts ba
 		ID:              img.ID().String(),
 		RepoTags:        repoTags,
 		RepoDigests:     repoDigests,
-		Parent:          img.Parent.String(),
+		Parent:          img.Parent.String(), //nolint:staticcheck // ignore SA1019: field is deprecated, but still included in response when present (built with legacy builder).
 		Comment:         comment,
 		Created:         created,
 		Container:       img.Container,        //nolint:staticcheck // ignore SA1019: field is deprecated, but still set on API < v1.45.
 		ContainerConfig: &img.ContainerConfig, //nolint:staticcheck // ignore SA1019: field is deprecated, but still set on API < v1.45.
-		DockerVersion:   img.DockerVersion,
+		DockerVersion:   img.DockerVersion,    //nolint:staticcheck // ignore SA1019: field is deprecated, but still included in response when present.
 		Author:          img.Author,
 		Config:          &imgConfig,
 		Architecture:    img.Architecture,
diff --git a/daemon/server/router/image/image_routes.go b/daemon/server/router/image/image_routes.go
@@ -421,9 +421,9 @@ func (ir *imageRouter) getImagesByName(ctx context.Context, w http.ResponseWrite
 		// These fields have "omitempty" on API v1.52 and higher,
 		// but older API versions returned them unconditionally.
 		legacyOptions = append(legacyOptions, compat.WithExtraFields(map[string]any{
-			"Parent":        imageInspect.Parent,
+			"Parent":        imageInspect.Parent, //nolint:staticcheck // ignore SA1019: field is deprecated, but still included in response when present (built with legacy builder).
 			"Comment":       imageInspect.Comment,
-			"DockerVersion": imageInspect.DockerVersion,
+			"DockerVersion": imageInspect.DockerVersion, //nolint:staticcheck // ignore SA1019: field is deprecated, but still included in response when present.
 			"Author":        imageInspect.Author,
 		}))
 		if versions.LessThan(version, "1.50") {
diff --git a/integration-cli/docker_api_build_test.go b/integration-cli/docker_api_build_test.go
@@ -313,16 +313,16 @@ func (s *DockerAPISuite) TestBuildOnBuildCache(c *testing.T) {
 	assert.Assert(c, is.Len(imageIDs, 2))
 	parentID, childID := imageIDs[0], imageIDs[1]
 
-	client := testEnv.APIClient()
+	apiClient := testEnv.APIClient()
 	ctx := testutil.GetContext(c)
 
 	// check parentID is correct
 	// Parent is graphdriver-only
 	if !testEnv.UsingSnapshotter() {
-		image, err := client.ImageInspect(ctx, childID)
+		image, err := apiClient.ImageInspect(ctx, childID)
 		assert.NilError(c, err)
 
-		assert.Check(c, is.Equal(parentID, image.Parent))
+		assert.Check(c, is.Equal(parentID, image.Parent)) //nolint:staticcheck // ignore SA1019: field is deprecated, but still included in response when present.
 	}
 }
 
diff --git a/vendor/github.com/moby/moby/api/types/image/image_inspect.go b/vendor/github.com/moby/moby/api/types/image/image_inspect.go
