Skip to content

api: omit legacy fields from image inspect if not set#51072

Merged
thaJeztah merged 1 commit intomoby:masterfrom
thaJeztah:image_inspect_omit_legacy
Oct 4, 2025
Merged

api: omit legacy fields from image inspect if not set#51072
thaJeztah merged 1 commit intomoby:masterfrom
thaJeztah:image_inspect_omit_legacy

Conversation

@thaJeztah
Copy link
Member

@thaJeztah thaJeztah commented Sep 30, 2025

The image inspect response has various fields that are either optional, or only used if the image was built using the deprecated legacy builder. This patch marks them as "omitempty" to omit them from the response if not set:

  • 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 Comment field is optional, and may not be set, depending on how the image is produced.
  • The DockerVersion field is only set when building images with the legacy builder, and empty in most cases.
  • The Author field can be set through the MAINTAINER instruction in Dockerfiles, and through the --author option on docker commit, but is optional, and won't be set in most situations.

With this patch:

On API v1.52

DOCKER_API_VERSION=v1.52 docker inspect busybox
[
    {
        "Id": "sha256:d82f458899c9696cb26a7c02d5568f81c8c8223f8661bb2a7988b269c8b9051e",
        "RepoTags": ["busybox:latest"],
        "RepoDigests": ["busybox@sha256:d82f458899c9696cb26a7c02d5568f81c8c8223f8661bb2a7988b269c8b9051e"],
        "Created": "2024-09-26T21:31:42Z",
        "Config": {
            "Env": ["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"],
            "Cmd": ["sh"]
        },
        "Architecture": "arm64",
        "Variant": "v8",
        "Os": "linux",
        "Size": 1913388,
        "RootFS": {
            "Type": "layers",
            "Layers": ["sha256:6aba5e0d32d91e3e923854dcb30588dc4112bfa1dae82b89535ad31d322a7b19"]
        },
        "Metadata": {
            "LastTagTime": "2025-10-03T22:24:18.440035424Z"
        },
        "Descriptor": {
            "mediaType": "application/vnd.oci.image.index.v1+json",
            "digest": "sha256:d82f458899c9696cb26a7c02d5568f81c8c8223f8661bb2a7988b269c8b9051e",
            "size": 9535
        }
    }
]

On API v1.51 or lower:

DOCKER_API_VERSION=v1.51 docker inspect busybox
[
    {
        "Architecture": "arm64",
        "Author": "",
        "Cmd": null,
        "Comment": "",
        "Config": {
            "Cmd": ["sh"],
            "Env": ["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"]
        },
        "Created": "2024-09-26T21:31:42Z",
        "Descriptor": {
            "digest": "sha256:d82f458899c9696cb26a7c02d5568f81c8c8223f8661bb2a7988b269c8b9051e",
            "mediaType": "application/vnd.oci.image.index.v1+json",
            "size": 9535
        },
        "DockerVersion": "",
        "Entrypoint": null,
        "Env": null,
        "Id": "sha256:d82f458899c9696cb26a7c02d5568f81c8c8223f8661bb2a7988b269c8b9051e",
        "Labels": null,
        "Metadata": {
            "LastTagTime": "2025-10-03T22:24:18.440035424Z"
        },
        "OnBuild": null,
        "Os": "linux",
        "Parent": "",
        "RepoDigests": ["busybox@sha256:d82f458899c9696cb26a7c02d5568f81c8c8223f8661bb2a7988b269c8b9051e"],
        "RepoTags": ["busybox:latest"],
        "RootFS": {
            "Layers": ["sha256:6aba5e0d32d91e3e923854dcb30588dc4112bfa1dae82b89535ad31d322a7b19"],
            "Type": "layers"
        },
        "Size": 1913388,
        "User": "",
        "Variant": "v8",
        "Volumes": null,
        "WorkingDir": ""
    }
]

- Human readable description for the release notes

`GET /images/{name}/json` now omits the following fields if their value is empty: `Parent`, `Comment`, `DockerVersion`, `Author`.

- A picture of a cute animal (not mandatory but encouraged)

@thaJeztah thaJeztah added this to the 29.0.0 milestone Sep 30, 2025
@thaJeztah thaJeztah marked this pull request as ready for review September 30, 2025 16:49
Copy link
Contributor

@vvoland vvoland left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, but considering that we haven't announced a deprecation, I think we should still include them for older API versions

@thaJeztah thaJeztah force-pushed the image_inspect_omit_legacy branch from 87d43e4 to 40bdc8e Compare October 3, 2025 22:11
The image inspect response has various fields that are either optional,
or only used if the image was built using the deprecated legacy builder.
This patch marks them as "omitempty" to omit them from the response if
not set:

- 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 `Comment` field is optional, and may not be set, depending on how the
  image is produced.
- The `DockerVersion` field is only set when building images with the legacy
  builder, and empty in most cases.
- The `Author` field can be set through the `MAINTAINER` instruction in
  Dockerfiles, and through the `--author` option on `docker commit`, but
  is optional, and won't be set in most situations.

With this patch:

On API v1.52

    DOCKER_API_VERSION=v1.52 docker inspect busybox
    [
        {
            "Id": "sha256:d82f458899c9696cb26a7c02d5568f81c8c8223f8661bb2a7988b269c8b9051e",
            "RepoTags": ["busybox:latest"],
            "RepoDigests": ["busybox@sha256:d82f458899c9696cb26a7c02d5568f81c8c8223f8661bb2a7988b269c8b9051e"],
            "Created": "2024-09-26T21:31:42Z",
            "Config": {
                "Env": ["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"],
                "Cmd": ["sh"]
            },
            "Architecture": "arm64",
            "Variant": "v8",
            "Os": "linux",
            "Size": 1913388,
            "RootFS": {
                "Type": "layers",
                "Layers": ["sha256:6aba5e0d32d91e3e923854dcb30588dc4112bfa1dae82b89535ad31d322a7b19"]
            },
            "Metadata": {
                "LastTagTime": "2025-10-03T22:24:18.440035424Z"
            },
            "Descriptor": {
                "mediaType": "application/vnd.oci.image.index.v1+json",
                "digest": "sha256:d82f458899c9696cb26a7c02d5568f81c8c8223f8661bb2a7988b269c8b9051e",
                "size": 9535
            }
        }
    ]

On API v1.51 or lower:

    DOCKER_API_VERSION=v1.51 docker inspect busybox
    [
        {
            "Architecture": "arm64",
            "Author": "",
            "Cmd": null,
            "Comment": "",
            "Config": {
                "Cmd": ["sh"],
                "Env": ["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"]
            },
            "Created": "2024-09-26T21:31:42Z",
            "Descriptor": {
                "digest": "sha256:d82f458899c9696cb26a7c02d5568f81c8c8223f8661bb2a7988b269c8b9051e",
                "mediaType": "application/vnd.oci.image.index.v1+json",
                "size": 9535
            },
            "DockerVersion": "",
            "Entrypoint": null,
            "Env": null,
            "Id": "sha256:d82f458899c9696cb26a7c02d5568f81c8c8223f8661bb2a7988b269c8b9051e",
            "Labels": null,
            "Metadata": {
                "LastTagTime": "2025-10-03T22:24:18.440035424Z"
            },
            "OnBuild": null,
            "Os": "linux",
            "Parent": "",
            "RepoDigests": ["busybox@sha256:d82f458899c9696cb26a7c02d5568f81c8c8223f8661bb2a7988b269c8b9051e"],
            "RepoTags": ["busybox:latest"],
            "RootFS": {
                "Layers": ["sha256:6aba5e0d32d91e3e923854dcb30588dc4112bfa1dae82b89535ad31d322a7b19"],
                "Type": "layers"
            },
            "Size": 1913388,
            "User": "",
            "Variant": "v8",
            "Volumes": null,
            "WorkingDir": ""
        }
    ]

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
@thaJeztah thaJeztah force-pushed the image_inspect_omit_legacy branch from 40bdc8e to 038bfbf Compare October 3, 2025 22:30
@thaJeztah
Copy link
Member Author

@thaJeztah thaJeztah merged commit f739c61 into moby:master Oct 4, 2025
317 of 320 checks passed
@thaJeztah thaJeztah deleted the image_inspect_omit_legacy branch October 4, 2025 08:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants