Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update artifacts-guidance based on proposed changes #1100

Closed
wants to merge 8 commits into from
Closed

Update artifacts-guidance based on proposed changes #1100

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
3c894af
Update artifacts-guidance.md
dasiths Aug 3, 2023
77b364a
Merge pull request #1 from dasiths/dasiths-patch-1
dasiths Aug 3, 2023
e77b00e
add decision tree from #1011 and examples
dasiths Aug 5, 2023
c117be5
add codeblock titles
dasiths Aug 8, 2023
3ba0788
fixup for test failure
dasiths Aug 8, 2023
72b3fb0
Provide a decision tree for artifacts
sudo-bmitch Aug 4, 2023
dba335f
cherry pick changes from sudo-bmitch/image-spec/tree/partifact-workflow
dasiths Aug 9, 2023
25fc92e
Merge remote-tracking branch 'sudo-bmitch/pr-artifact-workflow'
dasiths Aug 9, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions artifacts-guidance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
# Guidance for Artifacts Authors

Content other than OCI container images MAY be packaged using the image manifest.
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).
Additional details and examples are provided in the [image manifest specification](manifest.md#guidelines-for-artifact-usage).
When this is done, the `config.mediaType` value will not be a known OCI image config [media type](media-types.md).

Implementation details and examples are provided in the [image manifest specification](manifest.md#guidelines-for-artifact-usage).
139 changes: 82 additions & 57 deletions manifest.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -175,74 +175,99 @@ If the `config.mediaType` is set to the empty value, the `artifactType` MUST be
If the artifact does not need layers, a single layer SHOULD be included with a non-zero size.
The suggested content for an unused `layers` array is the [empty descriptor](#guidance-for-an-empty-descriptor).

Here is an example manifest for a typical artifact:
The design of the artifact depends on what content is being packaged with the artifact.
The decision tree below MAY be used to structure your artifact:

```json,title=Artifact%20with%20config&mediatype=application/vnd.oci.image.manifest.v1%2Bjson
{
"schemaVersion": 2,
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"config": {
"mediaType": "application/vnd.example.config.v1+json",
"digest": "sha256:5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03",
"size": 123
},
"layers": [
1. Does the artifact consist of at least one file or blob? If yes, continue to 2. If no, specify the `artifactType`, and set the `config` and `layers` to their empty descriptor values.

```json,title=Artifact%20with%20annotations&mediatype=application/vnd.oci.image.manifest.v1%2Bjson
{
"mediaType": "application/vnd.example.data.v1.tar+gzip",
"digest": "sha256:e258d248fda94c63753607f7c4494ee0fcbe92f1a76bfdac795c9d84101eb317",
"size": 1234
"schemaVersion": 2,
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"artifactType": "application/vnd.example+type",
"config": {
"mediaType": "application/vnd.oci.empty.v1+json",
"digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
"size": 2
},
"layers": [
{
"mediaType": "application/vnd.oci.empty.v1+json",
"digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
"size": 2
}
],
"annotations": {
"oci.opencontainers.image.created": "2023-01-02T03:04:05Z",
"com.example.data": "payload"
}
}
]
}
```
```

Here is an example manifest for a simple artifact without content in the config, using the empty descriptor:
2. Does the artifact have additional JSON formatted metadata as configuration? If yes, continue to 3. If no, specify the `artifactType`, include the artifact in the `layers`, and set `config` to the empty descriptor value.

```json,title=Artifact%20without%20config&mediatype=application/vnd.oci.image.manifest.v1%2Bjson
{
"schemaVersion": 2,
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"artifactType": "application/vnd.example+type",
"config": {
"mediaType": "application/vnd.oci.empty.v1+json",
"digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
"size": 2
},
"layers": [
```json,title=Artifact%20with%20artificatType%20and%20layers&mediatype=application/vnd.oci.image.manifest.v1%2Bjson
{
"mediaType": "application/vnd.example+type",
"digest": "sha256:e258d248fda94c63753607f7c4494ee0fcbe92f1a76bfdac795c9d84101eb317",
"size": 1234
"schemaVersion": 2,
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"artifactType": "application/vnd.example+type",
"config": {
"mediaType": "application/vnd.oci.empty.v1+json",
"digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
"size": 2
},
"layers": [
{
"mediaType": "application/vnd.example.data.v1.tar+gzip",
"digest": "sha256:e258d248fda94c63753607f7c4494ee0fcbe92f1a76bfdac795c9d84101eb317",
"size": 1234
}
]
}
```

3. Does the artifact require a different `artifactType` from the `config.mediaType`, to support multiple configuration formats or versions for the same artifact tooling? If yes, continue to 4. If no, specify the `config` with the metadata, include the artifact in the `layers`, but do not set the `artifactType`.

```json,title=Artifact%20with%20metadata%20and%20layers&mediatype=application/vnd.oci.image.manifest.v1%2Bjson
{
"schemaVersion": 2,
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"config": {
"mediaType": "application/vnd.example+type",
dasiths marked this conversation as resolved.
Show resolved Hide resolved
"digest": "sha256:5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03",
"size": 2
},
"layers": [
{
"mediaType": "application/vnd.example.data.v1.tar+gzip",
"digest": "sha256:e258d248fda94c63753607f7c4494ee0fcbe92f1a76bfdac795c9d84101eb317",
"size": 1234
}
]
}
]
}
```
```

Here is an example manifest for an artifact with only annotations set, and the content of both blobs set to the empty descriptor:
4. 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`.

```json,title=Minimal%20artifact&mediatype=application/vnd.oci.image.manifest.v1%2Bjson
{
"schemaVersion": 2,
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"artifactType": "application/vnd.example+type",
"config": {
"mediaType": "application/vnd.oci.empty.v1+json",
"digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
"size": 2
},
"layers": [
```json,title=Artifact%20with%20metadata%20and%20layers&mediatype=application/vnd.oci.image.manifest.v1%2Bjson
{
"mediaType": "application/vnd.oci.empty.v1+json",
"digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
"size": 2
"schemaVersion": 2,
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"artifactType": "application/vnd.example+type",
"config": {
"mediaType": "application/vnd.example.config.v1+json",
"digest": "sha256:5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03",
"size": 123
},
"layers": [
{
"mediaType": "application/vnd.example.data.v1.tar+gzip",
"digest": "sha256:e258d248fda94c63753607f7c4494ee0fcbe92f1a76bfdac795c9d84101eb317",
"size": 1234
}
]
}
],
"annotations": {
"oci.opencontainers.image.created": "2023-01-02T03:04:05Z",
"com.example.data": "payload"
}
}
```
```

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