Skip to content

Commit 3b62d0b

Browse files
committed
docs: deprecate empty Config fields in image inspect API
Image config fields like Cmd, Entrypoint, Env, etc. will be omitted from /images/{name}/json response when empty, starting in v29.0. Signed-off-by: Paweł Gronowski <pawel.gronowski@docker.com>
1 parent 082d23d commit 3b62d0b

1 file changed

Lines changed: 29 additions & 1 deletion

File tree

docs/deprecated.md

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,7 @@ The following table provides an overview of the current status of deprecated fea
5353

5454
| Status | Feature | Deprecated | Remove |
5555
|------------|------------------------------------------------------------------------------------------------------------------------------------|------------|--------|
56+
| Deprecated | [Empty/nil fields in image Config from inspect API](#emptynil-fields-in-image-config-from-inspect-api) | v28.3 | v29.0 |
5657
| Deprecated | [Configuration for pushing non-distributable artifacts](#configuration-for-pushing-non-distributable-artifacts) | v28.0 | v29.0 |
5758
| Deprecated | [`--time` option on `docker stop` and `docker restart`](#--time-option-on-docker-stop-and-docker-restart) | v28.0 | - |
5859
| Removed | [Non-standard fields in image inspect](#non-standard-fields-in-image-inspect) | v27.0 | v28.2 |
@@ -161,14 +162,41 @@ entirely.
161162

162163
### `--time` option on `docker stop` and `docker restart`
163164

164-
**Deprecated in Release: v28.0**
165+
**Deprecated in Release: v28.3**
165166

166167
The `--time` option for the `docker stop`, `docker container stop`, `docker restart`,
167168
and `docker container restart` commands has been renamed to `--timeout` for
168169
consistency with other uses of timeout options. The `--time` option is now
169170
deprecated and hidden, but remains functional for backward compatibility.
170171
Users are encouraged to migrate to using the `--timeout` option instead.
171172

173+
### Empty/nil fields in image Config from inspect API
174+
175+
**Deprecated in Release: v28.0**
176+
**Target For Removal In Release: v29.0**
177+
178+
The `Config` field returned by `docker image inspect` (and the `GET /images/{name}/json`
179+
API endpoint) currently includes certain fields even when they are empty or nil.
180+
Starting in Docker v29.0, the following fields will be omitted from the API response
181+
when they contain empty or default values:
182+
183+
- `Cmd`
184+
- `Entrypoint`
185+
- `Env`
186+
- `Labels`
187+
- `OnBuild`
188+
- `User`
189+
- `Volumes`
190+
- `WorkingDir`
191+
192+
Applications consuming the image inspect API should be updated to handle the
193+
absence of these fields gracefully, treating missing fields as having their
194+
default/empty values.
195+
196+
For API version corresponding to Docker v29.0, these fields will be omitted when
197+
empty. They will continue to be included when using clients that request an older
198+
API version for backward compatibility.
199+
172200
### Non-standard fields in image inspect
173201

174202
**Deprecated in Release: v27.0**

0 commit comments

Comments
 (0)