add decision tree from #1011 and examples

Signed-off-by: Dasith Wijesiriwardena <[email protected]>
opencontainers · Aug 5, 2023 · e77b00e · e77b00e
1 parent 77b364a
commit e77b00e
Show file tree

Hide file tree

Showing 2 changed files with 81 additions and 65 deletions.
diff --git a/artifacts-guidance.md b/artifacts-guidance.md
@@ -1,9 +1,6 @@
 # Guidance for Artifacts Authors
 
 Content other than OCI container images MAY be packaged using the image manifest.
-When this is done, 
+When this is done, the `config.mediaType` value will not be a known OCI image config [media type](media-types.md).
 
- - `image.artifactType` value MUST be set to a value specific to the artifact type.
- - `config.mediaType` value must be set to [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).
+Implementation details and examples are provided in the [image manifest specification](manifest.md#guidelines-for-artifact-usage).
diff --git a/manifest.md b/manifest.md
@@ -175,74 +175,93 @@ 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
     {
-      "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:
-
-```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": [
+    ```
+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
     {
-      "mediaType": "application/vnd.example+type",
-      "digest": "sha256:e258d248fda94c63753607f7c4494ee0fcbe92f1a76bfdac795c9d84101eb317",
-      "size": 1234
+      "schemaVersion": 2,
+      "mediaType": "application/vnd.oci.image.manifest.v1+json",
+      "artifactType": "application/vnd.example+type1",
+      "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
+        }
+      ]
     }
-  ]
-}
-```
-
-Here is an example manifest for an artifact with only annotations set, and the content of both blobs set to the empty descriptor:
+    ```
+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
+    {
+      "schemaVersion": 2,
+      "mediaType": "application/vnd.oci.image.manifest.v1+json",
+      "config": {
+        "mediaType": "application/vnd.example+type",
+        "digest": "sha256:5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03",
+        "size": 2
+      },
+      "layers": [
+        {
+          "mediaType": "application/vnd.example.data.v1.tar+gzip",
+          "digest": "sha256:e258d248fda94c63753607f7c4494ee0fcbe92f1a76bfdac795c9d84101eb317",
+          "size": 1234
+        }
+      ]
+    }
+    ```
+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
     {
-      "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+type1",
+      "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