From 22fd63389fcea2e432d2691b5e6c05fcbef271a3 Mon Sep 17 00:00:00 2001
From: xibz <bjp@apple.com>
Date: Mon, 9 Feb 2026 21:59:17 -0600
Subject: [PATCH] feat: add semantic _defs and link from schemas

Introduce initial opinionated semantic definitions under `_defs` and
reference them from event schemas.

Definitions are versioned alongside schemas, allowing terminology to
evolve explicitly if scope or meaning changes in future CDEvents
revisions.

Signed-off-by: xibz <bjp@apple.com>
---
 schemas/_defs/artifact.json     | 19 +++++++++++++++++++
 schemas/_defs/pipelinerun.json  | 19 +++++++++++++++++++
 schemas/_defs/started.json      | 22 ++++++++++++++++++++++
 schemas/pipelinerunstarted.json |  6 +++++-
 4 files changed, 65 insertions(+), 1 deletion(-)
 create mode 100644 schemas/_defs/artifact.json
 create mode 100644 schemas/_defs/pipelinerun.json
 create mode 100644 schemas/_defs/started.json

diff --git a/schemas/_defs/artifact.json b/schemas/_defs/artifact.json
new file mode 100644
index 0000000..5b8d08f
--- /dev/null
+++ b/schemas/_defs/artifact.json
@@ -0,0 +1,19 @@
+{
+  "$id": "cdevents/_defs/artifact",
+  "term": "Artifact",
+  "definition": "A versioned, immutable output of a build or packaging process that represents a deliverable unit intended for consumption by downstream systems.",
+  "notes": [],
+  "examples": [
+    "A container image produced by a CI pipeline",
+    "A compiled binary packaged for release",
+    "A versioned deployment bundle generated from source"
+  ],
+  "out_of_scope": [
+    "Source code repositories or branches",
+    "Intermediate or temporary build outputs",
+    "Logs, metrics, or diagnostic data",
+    "Configuration files not intended for distribution",
+    "Runtime state or dynamically generated data"
+  ]
+}
+
diff --git a/schemas/_defs/pipelinerun.json b/schemas/_defs/pipelinerun.json
new file mode 100644
index 0000000..5b275e4
--- /dev/null
+++ b/schemas/_defs/pipelinerun.json
@@ -0,0 +1,19 @@
+{
+  "$id": "cdevents/_defs/pipelinerun",
+  "term": "PipelineRun",
+  "definition": "A PipelineRun is a concrete invocation of a pipeline definition, representing one complete attempt to execute that pipeline’s workflow from start to termination.",
+  "notes": [
+    "A PipelineRun is not a pipeline definition",
+    "A PipelineRun may fail, succeed, or be aborted"
+  ],
+  "examples": [
+    "Tekton PipelineRun",
+    "GitHub Actions workflow run",
+    "Spinnaker pipeline execution"
+  ],
+  "out_of_scope": [
+    "Pipeline templates",
+    "Reusable pipeline graphs"
+  ]
+}
+
diff --git a/schemas/_defs/started.json b/schemas/_defs/started.json
new file mode 100644
index 0000000..11924d1
--- /dev/null
+++ b/schemas/_defs/started.json
@@ -0,0 +1,22 @@
+{
+  "$id": "cdevents/_defs/started",
+  "term": "Started",
+  "definition": "Indicates that execution of an entity has begun and that the system has committed to performing the associated work.",
+  "notes": [
+    "A started event does not imply successful execution or completion.",
+    "The associated execution may still fail, be canceled, or terminate early."
+  ],
+  "examples": [
+    "A pipeline run entering its first execution step",
+    "A task beginning execution on a worker",
+    "A deployment process initiating rollout"
+  ],
+  "out_of_scope": [
+    "Scheduling or queuing of work",
+    "Validation or pre-flight checks",
+    "Completion of execution",
+    "Failure or cancellation outcomes",
+    "Progress or intermediate execution states"
+  ]
+}
+
diff --git a/schemas/pipelinerunstarted.json b/schemas/pipelinerunstarted.json
index 1a2425e..04c16cd 100644
--- a/schemas/pipelinerunstarted.json
+++ b/schemas/pipelinerunstarted.json
@@ -1,6 +1,10 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://cdevents.dev/0.6.0-draft/schema/pipelinerun-started-event",
+  "x-cdevents-semantics": {
+    "subject": "cdevents/_defs/pipelinerun",
+    "predicate": "cdevents/_defs/started"
+  },
   "properties": {
     "context": {
       "properties": {
@@ -108,4 +112,4 @@
     "context",
     "subject"
   ]
-}
\ No newline at end of file
+}