Ref types (#240)

* Add concept for ref types

Co-authored-by: Shiwei Zhang <shizh@microsoft.com>
Signed-off-by: Sajay Antony <sajaya@microsoft.com>

docs/concepts/artifact.mdx

@@ -191,7 +191,7 @@ an empty layer is also created as per the  [empty descriptors guidance][empty-de
 }
 ```
 
-### Arifact authoring decision tree 
+### Artifact authoring decision tree 
 
 Putting it all together with the types of artifacts listed above and
 [Artifact Guidance in the image specification][artifact-guidelines], the decision tree 

docs/concepts/reftypes.dot

@@ -0,0 +1,88 @@
+digraph  reftypes{
+    rankdir = LR;
+    nodesep=0.5
+    splines=ortho
+	graph [
+		fontname = "Helvetica,Arial,sans-serif"
+        dpi=600
+	]
+	node [
+		style=filled
+		pencolor="#00000044" // frames color
+		fontname="Helvetica,Arial,sans-serif"
+        penwidth=1
+	]
+	edge [
+		arrowsize=0.5
+		labelfontcolor="#00000080"
+		penwidth=2
+	]
+
+
+   {
+        rank=same
+        color="#00000080"
+        artifact [
+            color="#88000022"
+            shape=plain
+            label=<<table border="0" cellborder="1" cellspacing="0" cellpadding="5">
+                <tr> <td PORT="f0"> <b>Manifest</b> </td> </tr>
+                 <tr> <td>OCI Artifact </td> </tr>
+            </table>>
+        ]
+
+        dot1 [shape=point width=0]
+        dot2 [shape=point width=0]
+        artifact -> dot1 [dir=back]
+        dot1 -> dot2 [arrowhead=none]
+    }
+
+    {
+
+        label="Referrers"
+        signature [
+            fillcolor=lightyellow
+            label=<<table border="0" cellborder="1" cellspacing="0" cellpadding="5">
+                <tr> <td> <b>Signature</b> </td> </tr>
+                    <tr> <td align="left">... <br align="left"/></td></tr>
+                    <tr> <td align="left" PORT="f0" >subject : <i>descriptor</i><br align="left"/></td></tr>
+            </table>>
+            shape=plain
+        ]
+
+        {
+            rank=same
+            sbom [
+                rank=min
+                fillcolor="#88ff0022"
+                label=<<table border="0" cellborder="1" cellspacing="0" cellpadding="5">
+                    <tr> <td> <b>SBOM</b> </td> </tr>
+                        <tr> <td align="left">... <br align="left"/></td></tr>
+                        <tr> <td align="left" PORT="f0" >subject : <i>descriptor</i><br align="left"/></td></tr>
+                </table>>
+                shape=plain
+            ]
+            dot21  [shape=point width=0]
+            sbom -> dot21 [dir=back]
+        }
+
+
+
+        sbomsig [
+            newrank=true
+            fillcolor=lightyellow
+            label=<<table border="0" cellborder="1" cellspacing="0" cellpadding="5">
+                <tr> <td> <b>Signature</b> </td> </tr>
+                    <tr> <td align="left">... <br align="left"/></td></tr>
+                    <tr> <td align="left" PORT="f0" >subject : <i>descriptor</i><br align="left"/></td></tr>
+            </table>>
+            shape=plain
+        ]
+
+            dot21 -> sbomsig:f0 [arrowhead=none;  weight=20]
+    }  
+
+    dot1 -> signature:f0 [arrowhead=none; weight=20]
+    dot2 -> sbom:f0 [arrowhead=none;  weight=20]
+
+}

docs/concepts/reftypes.mdx

@@ -0,0 +1,230 @@
+---
+title: Attached Artifacts
+sidebar_position: 1
+---
+
+# Attaching and listing reference types
+
+The OCI distribution specification allows us to "link" [OCI artifacts](artifact.mdx)
+through the use of the concept of reference types.
+Artifacts can be tied to one another by defining one as a subject of another.
+This is crucial for maintaining dependencies between different artifacts and
+enabling the movement of artifacts and their dependencies between environments.
+
+## Implementing Reference Types in OCI artifacts
+
+The concept of linking or relating OCI artifacts is achieved using the concept
+of reference types, where one artifact can be set as a subject to another.
+In this context, "subject" refers to the target of a reference.
+
+### The Art of Associating Artifacts
+
+Consider a typical cloud-native environment with countless OCI artifacts.
+Often, it's imperative to manage relationships between them—say, an OCI artifact's
+signatures, or metadata about an artifact. This is where reference types come into the picture.
+
+A reference type enables an OCI artifact to refer to another, creating a defined
+link or association between them. This association can be for various purposes,
+such as versioning, supply chain artifacts (signatures, SBOM, etc.), and dependencies.
+
+![OCI artifact with refererrs pointing to the artifact](/img/concepts/reftypes.png)
+
+## Creating a Reference Artifact
+
+OCI Artifacts may be stored in a content-addressable storage system or OCI Layout directory.
+For the purpose of this guide, we'll use the OCI Distribution Specification to
+create and list reference types.
+
+The creation of a reference artifact is a two-step process:
+
+- **Step One**: PUT an artifact, say Artifact A, using the PUT Manifest and
+blob upload APIs if the artifact has blob content. The prerequisite for a reference 
+type is that the subject artifact must be known so that it may be added to the subject.
+
+- **Step Two**: Put another artifact, say Artifact B, which refers to Artifact A.
+In this case, Artifact A is the 'subject' of Artifact B.
+
+This is done using the [push workflow][push-workflow] in the distribution specification.
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant R as Registry
+    C->>R: PUT /v2/<name>/manifests/<tag> Artifact A
+    R-->>C: 201 Created
+    C->>R: PUT /v2/<name>/manifests/<digest> Artifact B with reference to Artifact A
+    R-->>C: 201 Created
+```
+
+In this sequence, the client first uploads Artifact A to the registry.
+Next, the client uploads Artifact B to the same registry, but this time with a
+reference to Artifact A by specifying the digest of Artifact A as the subject.
+The association is now established in the registry.
+
+:::tip NOTE
+The specification does allow  pushing the reference artifact **without** requiring 
+the presense of the the `subject` in the target registry or OCI-Layout. 
+:::
+
+The following example shows the manifest of Artifact B with a reference to Artifact A 
+in the `subject` field.
+
+```json
+ {
+  "schemaVersion": 2,
+  "mediaType": "application/vnd.oci.image.manifest.v1+json",
+  "artifactType" : "application/example",
+  "config": {
+    "mediaType": "application/vnd.oci.empty.v1+json",
+    "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
+    "size": 2
+  },
+  "layers": [
+    {
+      "mediaType": "application/vnd.oci.image.layer.v1.tar",
+      "digest": "sha256:d2a84f4b8b650937ec8f73cd8be2c74add5a911ba64df27458ed8229da804a26",
+      "size": 12,
+      "annotations": {
+        "org.opencontainers.image.title": "attach/hello.txt"
+      }
+    }
+  ],
+  "subject": {
+    "mediaType": "application/vnd.oci.image.manifest.v1+json",
+    "digest": "sha256:5e140a61e16155b30356685a6801e5250339bfb11370e70573d28d4ff2dc89cf",
+    "size": 477
+  },
+  "annotations": {
+    "org.opencontainers.image.created": "2023-08-05T06:58:38Z"
+  }
+}
+```
+
+## Listing Referrers
+
+Once an artifact has one or more referring artifacts, it's often necessary to
+list these referrers for various purposes such as tracking dependencies, updates
+or obtaining metadata of the artifact.
+The OCI [Distribution Specification][listing-referrers] defines an API endpoint
+(`/v2/<name>/referrers/<digest>`) for this purpose.
+
+If the registry does not support listing referrers, then the [referrers tag schema][tag-schema]
+may be used to obtain a client created non-dynamic index of refererres.
+
+For the purpose of this guide we will use the [referrers API][listing-referrers].
+
+### Listing all referrers
+
+In this sequence, the client requests a list of all referrers to a specific artifact
+from the registry, which then responds with the list.
+The list may be paginated if the number of referrers is large.
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant R as Registry
+    C->>R: GET /v2/<name>/referrers/<digest>
+    R-->>C: 200 OK (List of all referrers)
+```
+
+### Listing referrers with a specific artifact type
+
+In this sequence, the client requests a list of referrers to a specific artifact
+of a certain media type from the registry, which then responds with the filtered list.
+The response will include the `OCI-Filters-Applied: artifactType` header to indicate
+that the response is filtered by the `artifactType` query parameter.
+
+The artifact type is determied by the same rules as per 
+[OCI artifacts guidlines](artifact.mdx#determining-the-artifact-type).
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant R as Registry
+    C->>R: GET /v2/<name>/referrers/<digest>?artifactType=<artifactType>
+    R-->>C: 200 OK (List of referrers of specific media type)
+```
+
+The request below lists shows an example for listing referrers of a specific media type.
+
+```json
+GET /v2/hello-world/referrers/sha256:5e140a6..?artifactType=application%2Fexample HTTP/1.1
+
+// response
+Content-Type: application/vnd.oci.image.index.v1+json
+Oci-Filters-Applied: artifactType
+
+{
+  "schemaVersion": 2,
+  "mediaType": "application/vnd.oci.image.index.v1+json",
+  "manifests": [
+    {
+      "mediaType": "application/vnd.oci.image.manifest.v1+json",
+      "digest": "sha256:a10d2cf503458e48996a3e3030c75fb5f5cd967e21a38ca69ce6c1e1dee5fd27",
+      "size": 677,
+      "annotations": {
+        "org.opencontainers.image.created": "2023-08-05T07:08:43Z"
+      },
+      "artifactType": "application/example"
+    }
+  ]
+}
+```
+
+## Fetching the reference artifact
+
+Once the referrers have been queried, the client may fetch the reference artifact
+using the digest that is returned in the list of referrers.
+The client may then use the digest to fetch the artifact contents using the
+[pull workflow][pull-workflow] as described in the distribution specification.
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant R as Registry
+
+    Note over C,R: Pull Workflow Starts
+
+    C->>R: GET /v2/<name>/manifests/<digest>
+    R-->>C: 200 OK, return manifest
+
+    Note over C,R: If manifest has config
+
+    C->>R: GET /v2/<name>/blobs/<digest> (Config)
+    R-->>C: 200 OK, return config
+
+    Note over C,R: If manifest has blobs
+
+    C->>R: GET /v2/<name>/blobs/<digest> (Blob 1)
+    R-->>C: 200 OK/307 Redirect, return blob 1
+
+    C->>R: GET /v2/<name>/blobs/<digest> (Blob 2)
+    R-->>C: 200 OK/307 Redirect return blob 2
+
+    Note over C,R: Save to OCI Layout or file system
+
+    C->>+C: Save manifest, config and blobs 
+    Note over C: Pull Workflow Ends
+```
+
+## The Power of Associations
+
+The introduction of Reference Types (Associations) opens a world of possibilities in
+managing and linking of OCI Artifacts while also empowering the following scenarios: 
+
+- Discovery and distribution of artifacts like SBOMs or signatures for supply chain. 
+- Movement of a graph of OCI content across environments. 
+- Content management of a graph of artifacts by archiving, deleting or moving them 
+together.
+
+To further explore this concept, dive deeper into the 
+[OCI Distribution Specification][distribution-spec] and the [OCI Image Specification][image-spec].
+These comprehensive guides will provide more insights into the use of 
+reference types and other details of managing OCI Artifacts.
+
+[listing-referrers]: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#listing-referrers
+[pull-workflow]: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#pull
+[push-workflow]: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#push
+[tag-schema]: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#referrers-tag-schema
+[distribution-spec]: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md
+[image-spec]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/spec.md