update(link): Relax link schemas to support domain-level identifiers

[xibz]

This change updates all link schemas (START, END, RELATION, and embedded variants) to allow references to either a CDEvent contextId, a domainId, or both.

Previously, links could only reference event context IDs. This limited cross-system connectivity and encouraged embedding execution identifiers in customData purely for graph reconstruction.

By allowing domainId alongside contextId:

• Links can represent relationships between domain executions (e.g., pipelinerun) as well as individual events.
• Connectivity metadata no longer needs to be embedded in event payloads.
• Chain-first modeling constraints are relaxed, enabling relation-first graph modeling.
• The change remains backward compatible.

At least one of contextId or domainId is now required for link endpoints. AdditionalProperties are restricted to prevent schema drift.

This preserves existing semantics while improving flexibility and reducing customData pollution.

[afrittoli]

Thanks @xibz - could you clarify the definition of domainId?

[xibz]

@afrittoli

The Core Problem

contextId requires the publisher to know the parent event's context ID.

But if the parent isn't a CDEvent, there is no context ID to know.

Today: GitHub doesn't emit CDEvents. So we use domainId to link to GitHub PRs explicitly.
Tomorrow: If/when GitHub emits CDEvents, we can migrate those links to contextId.
In the meantime: We have explicit causality without polluting customData.
This is a temporary bridge, not a permanent design.

Solution

Introduce a domain specific identifier which can be used to relate information

URNs will be used for domain IDs, where it follows the format of
urn:<provider>:<namespace>:<instance>:<type>:<resource id>

Examples:

• GitHub PR: urn:github:xibz:repo:pr:42
• Jira ticket: urn:jira:xibz:project:ticket:12345
• Datadog alert: urn:datadog:prod:monitor:alert:98765

Example 1 (GH to CI)

Build event wants to link to GitHub PR

Publisher asks: "What is the GitHub PR's contextId?"
Answer: GitHub doesn't emit CDEvents. There is no contextId.
Result: Can't use contextId. Forced into customData.

How domainId solves this

{
  "context": { "id": "build-event-789" },
  "links": [
    {
      "linkType": "RELATION",
      "linkKind": "triggeredBy",
      "target": {
        "domainId": "urn:github:xibz:repo:pr:42"
      }
    }
  ]
}

Example 2 (Jira to CI)

Imagine CircleCI wants to relate a Jira ticket

Build event links to CircleCI task:
{
  "links": [
    {
      "target": {
        "contextId": "circleci-task-event-456"  // ✓ Works, circle ci emits CDEvents
      }
    }
  ]
}

CircleCI task wants to link to Jira ticket:
{
  "links": [
    {
      "target": {
        "contextId": "???"  // ✗ Jira doesn't emit CDEvents. No contextId exists.
      }
    }
  ]
}

Result: CircleCI task can't link to Jira. Forced into customData.

Example 3: Datadog Alert Triggers Rollback Pipeline

Imagine you have a Datadog alert that monitors system health during releases.
If it detects an issue, it automatically triggers a rollback pipeline.

The rollback pipeline needs to link back to the alert that triggered it:

{
  "links": [
    {
      "linkType": "RELATION",
      "linkKind": "triggeredBy",
      "target": {
        "domainId": "urn:datadog:prod:monitor:alert:98765"
      }
    }
  ]
}

Example 4 Linking to Events Without Knowing Their Context ID

Imagine a consumer (like a dashboard or audit system) receives an event and wants to query for all related events, but doesn't know their context IDs upfront.

A deployment fails. You want to find:

• What build triggered it?
• What git commit caused the build?
• What PR introduced that commit?

Without domainId, you're stuck:

Deployment Failed event:
{
  "context": { "id": "deploy-event-999" },
  "customData": {
    "buildId": "build-789",
    "commitHash": "abc123def456",
    "prNumber": 42
  }
}

Problem: You have to parse customData and hope the IDs are there. No standardized way to query back.

With domainId, you can link forward AND backward:

Deployment Failed event:
{
  "context": { "id": "deploy-event-999" },
  "links": [
    {
      "linkType": "RELATION",
      "linkKind": "causedBy",
      "target": {
        "domainId": "urn:circleci:xibz:build:789"
      }
    },
    {
      "linkType": "RELATION",
      "linkKind": "causedBy",
      "target": {
        "domainId": "urn:github:xibz:repo:commit:abc123def456"
      }
    },
    {
      "linkType": "RELATION",
      "linkKind": "causedBy",
      "target": {
        "domainId": "urn:github:xibz:repo:pr:42"
      }
    }
  ]
}

with this:

• Consumer doesn't need to know CircleCI's context ID for build-789
• Consumer doesn't need to know GitHub's context ID for the commit
• Consumer can query by domainId URN directly
• Causality is explicit and discoverable without parsing customData

This shows that domainId isn't just for "non-CDEvent systems", but it's also useful for querying across systems when you don't have context IDs.

Why it works

Each system uses what it knows. Systems knows its own context IDs (contextId). Systems also knows how to identify triggering systems (domainId URN). No system needs to know another system's internal IDs or context IDs.

FAQS

Why link something outside CDEvents?

Because causality exists outside CDEvents.

• GitHub PRs cause builds.
• Jira tickets cause tasks.
• Datadog alerts cause rollbacks.

If you don't link them, you lose that causality. If you can't link them with contextId (because they're not CDEvents), you're forced to hide it in customData.

domainId lets you link anything, anywhere. That's why it matters.

If you don't solve cross-domain linking, who does?

Your engineers will. They'll put it in customData. Because causality is real whether CDEvents acknowledges it or not.

Doesn't this mean CDEvents becomes a catch-all for every system?

No. domainId is a stopgap until systems emit CDEvents natively.
As more systems adopt CDEvents, those domainId links naturally
migrate to contextId links. This is a temporary bridge, not a
permanent design decision.

[davidB]

Thanks, I now understand your proposal better, I guess.

• I'm not sure, it will be usable by the producer. Often, when they emit an event, there is no information about the cause/trigger (it's also why I'm looking for some other rules,...).
• IMO, domainId and subject.id should be matchable to allow correlation. If my dashboard, SIEM,... received a CDEvent about an incident, and then received a rollback with a link with a domainId (because the rollback system doesn't take CDEvent as input), then I want to be able to link both events to the same "incident".

Side questions: Is "links" just for "tigger", "causeby", or can it be used to define other types of relation? (eg for a test to define what the system under test is (a source, a change, an artifact), in which context (ci, environment), triggered by what (a scheduler, a change, a deployment, ...)

[xibz]

@davidB

Not every producer will always know the trigger or cause at emission time.

The proposal does not require links to always be present. It simply provides a standardized way to express causality when it is known.

If a producer does not know the trigger, it emits no link.

The key difference is:

Today:
When causality is known, it goes into customData in a tool-specific way.

With domainId:
When causality is known, it is expressed in a standard, traversable way.

This proposal does not require perfect causality capture. It enables correct modeling when information exists.

Regarding domainId and subject.id correlation

Correlation is exactly one of the motivations.

The intention is that domainId represents the canonical identity of an entity within its domain. subject.id is too flexible, hence the strict URN format.

If a system later emits a native CDEvent for that entity, the subject.id of that event should correspond to the same logical identifier represented in the domainId.

This allows dashboards, SIEM systems, and audit systems to correlate across both:
• native CDEvents (via contextId)
• API calls with no context.id (via domainId)

domainId is not meant to replace subject.id, but to provide a stable cross-domain reference when contextId is unavailable.

Are links only for trigger/cause?

Links are not limited to trigger/cause relationships.

They are intended to model typed relationships between entities.

Examples include:
• triggeredBy
• causedBy
• derivedFrom
• produced
• testedAgainst
• runsIn
• deployedTo
• dependsOn

The goal is not only causality modeling, but explicit relationship modeling.

This allows us to describe:
• what system was under test
• what artifact was deployed
• what environment was targeted
• what scheduler triggered execution