api: swagger: document "platform" param for GET /image/{name}/json#52082
Merged
thaJeztah merged 2 commits intomoby:masterfrom Feb 24, 2026
Merged
api: swagger: document "platform" param for GET /image/{name}/json#52082thaJeztah merged 2 commits intomoby:masterfrom
GET /image/{name}/json#52082thaJeztah merged 2 commits intomoby:masterfrom
Conversation
This parameter was added in 59169d0 (API v1.49, docker 28.5.1), but forgot to update the swagger definition. Signed-off-by: Sebastiaan van Stijn <[email protected]>
…9-v1.53) This parameter was added in 59169d0 (API v1.49, docker 28.5.1), but forgot to update the swagger definition. Signed-off-by: Sebastiaan van Stijn <[email protected]>
thaJeztah
added
area/api
thaJeztah
commented
Feb 23, 2026
Comment on lines
+9752
to
+9759
| JSON-encoded OCI platform to select the platform-variant. | ||
| If omitted, it defaults to any locally available platform, | ||
| prioritizing the daemon's host platform. | ||
|
|
||
| If the daemon provides a multi-platform image store, this selects | ||
| the platform-variant to show inspect. If the image is | ||
| a single-platform image, or if the multi-platform image does not | ||
| provide a variant matching the given platform, an error is returned. |
Member
Author
There was a problem hiding this comment.
FWIW (I used the same description as for history) it looks like we don't produce an error if the image variant is not present; I think that's a bug;
Trying this on an image that doesn't have the s390x variant present;
curl -s --unix-socket /var/run/docker.sock \
--get 'http://localhost/v1.51/images/hello-world/json' \
--data-urlencode 'manifests=0' \
--data-urlencode 'platform={"os":"linux","architecture":"s390x"}' \
| jq .Does not produce an error, but shows the image config fields with their default (zero) values;
{
"Architecture": "",
"Author": "",
"Comment": "",
"Config": {
"Cmd": null,
"Entrypoint": null,
"Env": null,
"Labels": null,
"OnBuild": null,
"User": "",
"Volumes": null,
"WorkingDir": ""
},
"Descriptor": {
"annotations": {
"com.docker.official-images.bashbrew.arch": "s390x",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-08-14T02:53:30Z",
"org.opencontainers.image.revision": "6930d60e10e81283a57be3ee3a2b5ca328a40304",
"org.opencontainers.image.source": "https://github.com/docker-library/hello-world.git#6930d60e10e81283a57be3ee3a2b5ca328a40304:s390x/hello-world",
"org.opencontainers.image.url": "https://hub.docker.com/_/hello-world",
"org.opencontainers.image.version": "linux"
},
"digest": "sha256:92867137e934e6df211d16db0011244d3b30fc052caae4f09438f5f2134b7998",
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"platform": {
"architecture": "s390x",
"os": "linux"
},
"size": 1035
},
"DockerVersion": "",
"GraphDriver": {
"Data": null,
"Name": "overlayfs"
},
"Id": "sha256:92867137e934e6df211d16db0011244d3b30fc052caae4f09438f5f2134b7998",
"Metadata": {
"LastTagTime": "2026-02-23T09:04:09.165007301Z"
},
"Os": "",
"Parent": "",
"RepoDigests": [
"hello-world@sha256:ef54e839ef541993b4e87f25e752f7cf4238fa55f017957c2eb44077083d7a6a"
],
"RepoTags": [
"hello-world:latest"
],
"RootFS": {},
"Size": 13377
}When using graph-drivers, we DO produce an error, so I think it may be a bug in our logic;
curl -s --unix-socket /var/run/docker.sock \
--get 'http://localhost/v1.51/images/hello-world/json' \
--data-urlencode 'manifests=0' \
--data-urlencode 'platform={"os":"linux","architecture":"s390x"}' \
| jq .
{
"message": "image with reference hello-world was found but its platform (linux/arm64/v8) does not match the specified platform (linux/amd64)"
}
thaJeztah
commented
Feb 23, 2026
Comment on lines
+9761
to
+9762
| The `platform` and `manifests` options are mutually exclusive, and | ||
| an error is produced if both are set. |
Member
Author
There was a problem hiding this comment.
Combining with manifests=1 produces an error (as currently expected);
curl -s --unix-socket /var/run/docker.sock \
--get 'http://localhost/v1.51/images/hello-world/json' \
--data-urlencode 'manifests=1' \
--data-urlencode 'platform={"os":"linux","architecture":"s390x"}' \
| jq .
{
"message": "conflicting options: manifests and platform options cannot both be set"
}
robmry
approved these changes
Feb 24, 2026
Member
Author
|
I'll bring this one in; I may be opening a tracking ticket for the error case; I think it's a bug that it doesn't error if I request a specific platform and it's not present. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
api: swagger: document "platform" param for
GET /image/{name}/jsonThis parameter was added in 59169d0
(API v1.49, docker 28.5.1), but forgot to update the swagger definition.
api/docs: add "platform" param for
GET /image/{name}/json(API v1.49-v1.53)This parameter was added in 59169d0
(API v1.49, docker 28.5.1), but forgot to update the swagger definition.
- What I did
- How I did it
- How to verify it
- Human readable description for the release notes
- A picture of a cute animal (not mandatory but encouraged)