fixup! add link examples

Signed-off-by: benjamin-j-powell <[email protected]>

examples/links/README.md

@@ -0,0 +1,34 @@
+# Links Examples
+
+These examples need a little context to make sense of how individual links are
+connected. A single example link by itself is not too useful in understanding
+how links are used, and this folder is to give context to the example to help
+describe how links can be used as described in the API.
+
+More information can be found in the [links proposal]()
+
+## Format
+
+The format of these examples will be 0_<event>.json, where `0` represents the
+order in which it was sent.  `embedded` signifies whether or not the link is
+embedded in the CDEvent context or sent separately.
+
+## Example Use Case
+
+Let us assume we have a source change that just got merged. The [source change
+event](https://github.com/cdevents/spec/blob/v0.3.0/source-code-version-control.md#change-merged)
+will be consumed by some CI system and kick off the whole chain. We will
+describe this example utilizing links and how links can be used to visualize
+these connections. For sake of simplicity of this example we will capture only
+a few events to illustrate how links can be used separately or within the
+CDEvent itself.
+
+These 6 events will utilize links to connect themselves to the appropriate
+event or entity:
+
+1. change.merged
+2. build.queued
+3. build.started
+4. build.finished
+5. artifact.packaged
+6. artifact.published

examples/links/embedded/0_change.merged.json

@@ -0,0 +1,29 @@
+{
+  "context": {
+    "version": "0.4.0-draft",
+    "id": "271069a8-fc18-44f1-b38f-9d70a1695819",
+    "chain_id": "97ef590e-0285-45ad-98bb-9660ffaa567e",
+    "source": "/event/source/123",
+    "type": "dev.cdevents.change.merged.0.1.2",
+    "timestamp": "2023-03-20T14:27:05.315384Z",
+    "links" : [
+      {
+        "link_type": "PATH",
+        "from": {
+          "id": "b8e82ad7-3b8f-48b5-ba70-851d743a33ae"
+        }
+      }
+    ]
+  },
+  "subject": {
+    "id": "mySubject123",
+    "source": "/event/source/123",
+    "type": "change",
+    "content": {
+      "repository": {
+        "id": "TestRepo/TestOrg",
+        "source": "https://example.org"
+      }
+    }
+  }
+}

examples/links/embedded/1_build.queued.json

@@ -0,0 +1,24 @@
+{
+  "context": {
+    "version": "0.4.0-draft",
+    "id": "bf125d33-8b7f-4748-b804-671d86d891bf",
+    "chain_id": "97ef590e-0285-45ad-98bb-9660ffaa567e",
+    "source": "/event/source/123",
+    "type": "dev.cdevents.build.queued.0.1.1",
+    "timestamp": "2023-03-20T14:27:05.315384Z",
+    "links" : [
+      {
+        "link_type": "PATH",
+        "from": {
+          "id": "271069a8-fc18-44f1-b38f-9d70a1695819"
+        }
+      }
+    ]
+  },
+  "subject": {
+    "id": "mySubject123",
+    "source": "/event/source/123",
+    "type": "build",
+    "content": {}
+  }
+}

examples/links/embedded/2_build.started.json

@@ -0,0 +1,24 @@
+{
+  "context": {
+    "version": "0.4.0-draft",
+    "id": "965bbb79-32fe-44eb-8817-4657cea2ff47",
+    "chain_id": "97ef590e-0285-45ad-98bb-9660ffaa567e",
+    "source": "/event/source/123",
+    "type": "dev.cdevents.build.started.0.1.1",
+    "timestamp": "2023-03-20T14:27:05.315384Z",
+    "links" : [
+      {
+        "link_type": "PATH",
+        "from": {
+          "id": "bf125d33-8b7f-4748-b804-671d86d891bf"
+        }
+      }
+    ]
+  },
+  "subject": {
+    "id": "mySubject123",
+    "source": "/event/source/123",
+    "type": "build",
+    "content": {}
+  }
+}

examples/links/embedded/3_build.finished.json

@@ -0,0 +1,26 @@
+{
+  "context": {
+    "version": "0.4.0-draft",
+    "id": "bbb3814b-0c6a-42ea-8db2-10e290c61069",
+    "chain_id": "97ef590e-0285-45ad-98bb-9660ffaa567e",
+    "source": "/event/source/123",
+    "type": "dev.cdevents.build.finished.0.1.1",
+    "timestamp": "2023-03-20T14:27:05.315384Z",
+    "links" : [
+      {
+        "link_type": "PATH",
+        "from": {
+          "id": "965bbb79-32fe-44eb-8817-4657cea2ff47"
+        }
+      }
+    ]
+  },
+  "subject": {
+    "id": "mySubject123",
+    "source": "/event/source/123",
+    "type": "build",
+    "content": {
+      "artifactId": "pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427"
+    }
+  }
+}

examples/links/embedded/4_artifact.packaged.json

@@ -0,0 +1,29 @@
+{
+  "context": {
+    "version": "0.4.0-draft",
+    "id": "d7124088-2842-4ffa-a35a-e7e63e16de80",
+    "chain_id": "97ef590e-0285-45ad-98bb-9660ffaa567e",
+    "source": "/event/source/123",
+    "type": "dev.cdevents.artifact.packaged.0.1.1",
+    "timestamp": "2023-03-20T14:27:05.315384Z",
+    "links": [
+      {
+        "link_type": "PATH",
+        "from": {
+          "id": "bbb3814b-0c6a-42ea-8db2-10e290c61069"
+        }
+      }
+    ]
+  },
+  "subject": {
+    "id": "pkg:golang/mygit.com/myorg/myapp@234fd47e07d1004f0aed9c",
+    "source": "/event/source/123",
+    "type": "artifact",
+    "content": {
+      "change": {
+        "id": "myChange123",
+        "source": "my-git.example/an-org/a-repo"
+      }
+    }
+  }
+}

examples/links/embedded/5_artifact.published.json

@@ -0,0 +1,31 @@
+{
+  "context": {
+    "version": "0.4.0-draft",
+    "id": "0991eefb-609d-454e-b7fd-b6da60adf54f",
+    "chain_id": "97ef590e-0285-45ad-98bb-9660ffaa567e",
+    "source": "/event/source/123",
+    "type": "dev.cdevents.artifact.published.0.1.1",
+    "timestamp": "2023-03-20T14:27:05.315384Z",
+    "links": [
+      {
+        "link_type": "END",
+        "from": {
+          "id": "b7d9d61d-6f82-4bb9-a0dd-65748491df0e"
+        }
+      },
+      {
+        "link_type": "RELATION",
+        "link_kind": "ARTIFACT",
+        "target": {
+          "id": "mySubject123"
+        }
+      }
+    ]
+  },
+  "subject": {
+    "id": "pkg:golang/mygit.com/myorg/myapp@234fd47e07d1004f0aed9c",
+    "source": "/event/source/123",
+    "type": "artifact",
+    "content": {}
+  }
+}

examples/linkpath.json → examples/links/separate/0_change.merged.json

@@ -3,13 +3,9 @@
   "link_type": "PATH",
   "timestamp": "2023-03-20T14:27:05.315384Z",
   "from": {
-    "id": "f27e36a4-5c78-43c0-840a-52524dfeed03"
+    "id": "b8e82ad7-3b8f-48b5-ba70-851d743a33ae"
   },
   "to": {
-    "id": "f004290e-5e45-45f4-b97a-fa82499f534c"
-  },
-  "tags": {
-    "ci.environment": "prod"
+    "id": "271069a8-fc18-44f1-b38f-9d70a1695819"
   }
 }
-

examples/links/separate/1_build.queued.json

@@ -0,0 +1,11 @@
+{
+  "chain_id": "97ef590e-0285-45ad-98bb-9660ffaa567e",
+  "link_type": "PATH",
+  "timestamp": "2023-03-20T14:37:06.315384Z",
+  "from": {
+    "id": "271069a8-fc18-44f1-b38f-9d70a1695819"
+  },
+  "to": {
+    "id": "bf125d33-8b7f-4748-b804-671d86d891bf"
+  }
+}

examples/links/separate/2_build.started.json

@@ -0,0 +1,11 @@
+{
+  "chain_id": "97ef590e-0285-45ad-98bb-9660ffaa567e",
+  "link_type": "PATH",
+  "timestamp": "2023-03-20T14:37:23.315384Z",
+  "from": {
+    "id": "bf125d33-8b7f-4748-b804-671d86d891bf"
+  },
+  "to": {
+    "id": "965bbb79-32fe-44eb-8817-4657cea2ff47"
+  }
+}

examples/links/separate/3_build.finished.json

@@ -0,0 +1,11 @@
+{
+  "chain_id": "97ef590e-0285-45ad-98bb-9660ffaa567e",
+  "link_type": "PATH",
+  "timestamp": "2023-03-20T14:57:01.315384Z",
+  "from": {
+    "id": "965bbb79-32fe-44eb-8817-4657cea2ff47"
+  },
+  "to": {
+    "id": "bbb3814b-0c6a-42ea-8db2-10e290c61069"
+  }
+}

examples/links/separate/4_artifact.packaged.json

@@ -0,0 +1,11 @@
+{
+  "chain_id": "97ef590e-0285-45ad-98bb-9660ffaa567e",
+  "link_type": "PATH",
+  "timestamp": "2023-03-20T14:58:03.315384Z",
+  "from": {
+    "id": "965bbb79-32fe-44eb-8817-4657cea2ff47"
+  },
+  "to": {
+    "id": "bbb3814b-0c6a-42ea-8db2-10e290c61069"
+  }
+}

examples/linkend.json → examples/links/separate/5_artifact.published.json

@@ -1,14 +1,11 @@
 {
   "chain_id": "97ef590e-0285-45ad-98bb-9660ffaa567e",
   "link_type": "END",
-  "timestamp": "2023-03-20T14:27:05.315384Z",
+  "timestamp": "2023-03-20T15:01:11.315384Z",
   "from": {
     "id": "b7d9d61d-6f82-4bb9-a0dd-65748491df0e"
   },
   "end": {
-    "id": "bf9d3c52-1c12-4029-a8d6-e4aca6c69127"
-  },
-  "tags": {
-    "ci.environment": "prod"
+    "id": "0991eefb-609d-454e-b7fd-b6da60adf54f"
   }
 }

examples/links/separate/6_artifact.published.json

@@ -0,0 +1,13 @@
+{
+  "chain_id": "97ef590e-0285-45ad-98bb-9660ffaa567e",
+  "link_type": "RELATION",
+  "link_kind": "ARTIFACT",
+  "timestamp": "2023-03-20T15:01:11.315384Z",
+  "source": {
+    "id": "pkg:golang/mygit.com/myorg/myapp@234fd47e07d1004f0aed9c"
+  },
+  "target": {
+    "id": "mySubject123"
+  }
+}
+

schemas/links/embeddedlinkend.json

@@ -1,11 +1,5 @@
 {
-  "chain_id": {
-    "description": "This represents the full lifecycles of a series of events in CDEvents",
-    "type": "string",
-    "minLength": 1
-  },
   "link_type": {
-    "description": "An enum that represents the type of link, e.g. 'START', 'END', 'RELATION'",
     "type": "string",
     "enum": [
       "END"
@@ -31,10 +25,8 @@
   "additionalProperties": false,
   "type": "object",
   "required": [
-    "chain_id",
     "link_type",
     "timestamp",
-    "from",
     "end"
   ]
 }

schemas/links/embeddedlinkpath.json

@@ -1,13 +1,12 @@
 {
-  "chain_id": {
+  "link_type": {
     "type": "string",
-    "minLength": 1
-  },
-  "timestamp": {
-    "type": "string",
-    "format": "date-time"
+    "enum": [
+      "PATH"
+    ]
   },
-  "to": {
+  "from": {
+    "description": "When consuming a CDEvent, you are consuming a parent event. So, when looking at the 'from' key, this is the parent's parent.",
     "type": "object",
     "properties": {
       "id": {
@@ -22,9 +21,7 @@
   "additionalProperties": false,
   "type": "object",
   "required": [
-    "chain_id",
     "link_type",
-    "timestamp",
     "to"
   ]
 }