From 384636490397c9b5b7d3c7873bdb9fd160ec984f Mon Sep 17 00:00:00 2001
From: Sajay Antony <sajaya@microsoft.com>
Date: Sat, 5 Aug 2023 07:59:20 +0000
Subject: [PATCH] add decision tree for artifact creation

Signed-off-by: Sajay Antony <sajaya@microsoft.com>
---
 docs/concepts/artifact.mdx | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/docs/concepts/artifact.mdx b/docs/concepts/artifact.mdx
index e503a2bf..f51050e0 100644
--- a/docs/concepts/artifact.mdx
+++ b/docs/concepts/artifact.mdx
@@ -162,6 +162,30 @@ as per the  [empty descriptors guidance][empty-descriptor].
 }
 ```
 
+### Deciding on artifactType or config.mediaType
+
+Considering the above types of artifacts the decision tree below should help 
+determine what fields to set when creating an artifact.
+
+```mermaid
+graph TD
+    A{Artifact has at least<br>one file or blob?}
+    B{Artifact has additional<br>JSON metadata?}
+    C{Artifact requires <br>different artifactType<br>from config.mediaType?}
+    D[Specify artifactType,<br>set config and layers<br>to empty descriptors.]
+    E[Specify artifactType, include<br>artifact in layers, set<br>config to empty descriptor.]
+    F[Specify config with metadata,<br>include artifact in layers,<br>do not set artifactType.]
+    G[Specify artifactType to common<br>value, specify config with<br>metadata, include artifact in layers.]
+
+    A -- No --> D
+    A -- Yes --> B
+    B -- No --> E
+    B -- Yes --> C
+    C -- No --> F
+    C -- Yes --> G
+
+```
+
 ### Harnessing Image Indexes
 
 One of the key advantages of OCI artifacts is their ability to utilize [Image Indexes][image-index],