Skip to content

Commit e6a75e6

Browse files
sudo-bmitchsudo-bmitch
committed
Provide a decision tree for artifacts
Signed-off-by: Brandon Mitchell <[email protected]> Helped-by: Dasith Wijesiriwardena <[email protected]>
1 parent 4b568ff commit e6a75e6

File tree

2 files changed

+84
-70
lines changed

2 files changed

+84
-70
lines changed

‎artifacts-guidance.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
# Guidance for Artifacts Authors
22

33
Content other than OCI container images MAY be packaged using the image manifest.
4-
When this is done, the `config.mediaType` value MUST be set to a value specific to the artifact type or the [empty value](manifest.md#guidance-for-an-empty-descriptor).
5-
Additional details and examples are provided in the [image manifest specification](manifest.md#guidelines-for-artifact-usage).
4+
When this is done, the `config.mediaType` value should not be a known OCI image config [media type](media-types.md).
5+
Historically, due to registry limitations, some tools have created non-OCI conformant artifacts using the `application/vnd.oci.image.config.v1+json` value for `config.mediaType` and values specific to the artifact in `layer[*].mediaType`.
6+
Implementation details and examples are provided in the [image manifest specification](manifest.md#guidelines-for-artifact-usage).

‎manifest.md‎

Lines changed: 81 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -175,74 +175,87 @@ If the `config.mediaType` is set to the empty value, the `artifactType` MUST be
175175
If the artifact does not need layers, a single layer SHOULD be included with a non-zero size.
176176
The suggested content for an unused `layers` array is the [empty descriptor](#guidance-for-an-empty-descriptor).
177177

178-
Here is an example manifest for a typical artifact:
179-
180-
```json,title=Artifact%20with%20config&mediatype=application/vnd.oci.image.manifest.v1%2Bjson
181-
{
182-
"schemaVersion": 2,
183-
"mediaType": "application/vnd.oci.image.manifest.v1+json",
184-
"config": {
185-
"mediaType": "application/vnd.example.config.v1+json",
186-
"digest": "sha256:5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03",
187-
"size": 123
188-
},
189-
"layers": [
190-
{
191-
"mediaType": "application/vnd.example.data.v1.tar+gzip",
192-
"digest": "sha256:e258d248fda94c63753607f7c4494ee0fcbe92f1a76bfdac795c9d84101eb317",
193-
"size": 1234
194-
}
195-
]
196-
}
197-
```
198-
199-
Here is an example manifest for a simple artifact without content in the config, using the empty descriptor:
200-
201-
```json,title=Artifact%20without%20config&mediatype=application/vnd.oci.image.manifest.v1%2Bjson
202-
{
203-
"schemaVersion": 2,
204-
"mediaType": "application/vnd.oci.image.manifest.v1+json",
205-
"artifactType": "application/vnd.example+type",
206-
"config": {
207-
"mediaType": "application/vnd.oci.empty.v1+json",
208-
"digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
209-
"size": 2
210-
},
211-
"layers": [
212-
{
213-
"mediaType": "application/vnd.example+type",
214-
"digest": "sha256:e258d248fda94c63753607f7c4494ee0fcbe92f1a76bfdac795c9d84101eb317",
215-
"size": 1234
216-
}
217-
]
218-
}
219-
```
220-
221-
Here is an example manifest for an artifact with only annotations set, and the content of both blobs set to the empty descriptor:
222-
223-
```json,title=Minimal%20artifact&mediatype=application/vnd.oci.image.manifest.v1%2Bjson
224-
{
225-
"schemaVersion": 2,
226-
"mediaType": "application/vnd.oci.image.manifest.v1+json",
227-
"artifactType": "application/vnd.example+type",
228-
"config": {
229-
"mediaType": "application/vnd.oci.empty.v1+json",
230-
"digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
231-
"size": 2
232-
},
233-
"layers": [
234-
{
235-
"mediaType": "application/vnd.oci.empty.v1+json",
236-
"digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
237-
"size": 2
238-
}
239-
],
240-
"annotations": {
241-
"oci.opencontainers.image.created": "2023-01-02T03:04:05Z",
242-
"com.example.data": "payload"
243-
}
244-
}
245-
```
178+
The design of the artifact depends on what content is being packaged with the artifact.
179+
The decision tree below and the associated examples MAY be used to design new artifacts:
180+
181+
1. Does the artifact consist of at least one file or blob?
182+
If yes, continue to 2.
183+
If no, specify the `artifactType`, and set the `config` and a single `layers` element to the empty descriptor value.
184+
Here is an example of this with annotations included:
185+
186+
```json,title=Minimal%20artifact&mediatype=application/vnd.oci.image.manifest.v1%2Bjson
187+
{
188+
"schemaVersion": 2,
189+
"mediaType": "application/vnd.oci.image.manifest.v1+json",
190+
"artifactType": "application/vnd.example+type",
191+
"config": {
192+
"mediaType": "application/vnd.oci.empty.v1+json",
193+
"digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
194+
"size": 2
195+
},
196+
"layers": [
197+
{
198+
"mediaType": "application/vnd.oci.empty.v1+json",
199+
"digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
200+
"size": 2
201+
}
202+
],
203+
"annotations": {
204+
"oci.opencontainers.image.created": "2023-01-02T03:04:05Z",
205+
"com.example.data": "payload"
206+
}
207+
}
208+
```
209+
210+
2. Does the artifact have additional JSON formatted metadata as configuration?
211+
If yes, continue to 3.
212+
If no, specify the `artifactType`, include the artifact in the `layers`, and set `config` to the empty descriptor value.
213+
Here is an example of this with a single layer:
214+
215+
```json,title=Artifact%20without%20config&mediatype=application/vnd.oci.image.manifest.v1%2Bjson
216+
{
217+
"schemaVersion": 2,
218+
"mediaType": "application/vnd.oci.image.manifest.v1+json",
219+
"artifactType": "application/vnd.example+type",
220+
"config": {
221+
"mediaType": "application/vnd.oci.empty.v1+json",
222+
"digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
223+
"size": 2
224+
},
225+
"layers": [
226+
{
227+
"mediaType": "application/vnd.example+type",
228+
"digest": "sha256:e258d248fda94c63753607f7c4494ee0fcbe92f1a76bfdac795c9d84101eb317",
229+
"size": 1234
230+
}
231+
]
232+
}
233+
```
234+
235+
3. For artifacts with a config blob, specify the `artifactType` to a common value for your artifact tooling, specify the `config` with the metadata for this artifact, and include the artifact in the `layers`.
236+
Here is an example of this:
237+
238+
```json,title=Artifact%20with%20config&mediatype=application/vnd.oci.image.manifest.v1%2Bjson
239+
{
240+
"schemaVersion": 2,
241+
"mediaType": "application/vnd.oci.image.manifest.v1+json",
242+
"artifactType": "application/vnd.example+type",
243+
"config": {
244+
"mediaType": "application/vnd.example.config.v1+json",
245+
"digest": "sha256:5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03",
246+
"size": 123
247+
},
248+
"layers": [
249+
{
250+
"mediaType": "application/vnd.example.data.v1.tar+gzip",
251+
"digest": "sha256:e258d248fda94c63753607f7c4494ee0fcbe92f1a76bfdac795c9d84101eb317",
252+
"size": 1234
253+
}
254+
]
255+
}
256+
```
257+
258+
_Implementers note:_ artifacts have historically been created without an `artifactType` field, and tooling to work with artifacts should fallback to the `config.mediaType` value.
246259

247260
[iana]: https://www.iana.org/assignments/media-types/media-types.xhtml
248261
[rfc6838]: https://tools.ietf.org/html/rfc6838

0 commit comments

Comments
 (0)