CDEvents Namespacing Proposal (WSDL-Inspired)

[sol-duara]

CDEvents Namespacing Proposal (WSDL-Inspired)

Purpose

Propose a standardized, extensible namespacing convention for CDEvents to support:

• Organizational and vendor-defined events
• Experimental schemas
• Clear schema versioning
• Collision-free graph traversal in a SDLC workflow orchestrator or similar system
• Smooth consumption via DSLs and typed libraries
• Explicit schema validation via schemaUri

Background

As CDEvents adoption grows, contributors and implementers face the need to:

• Extend existing events for domain- or org-specific use cases
• Define new events without a central coordination delay
• Maintain semantic interoperability across toolchains
• Validate events consistently in code and DSLs

This proposal draws from WSDL’s targetNamespace model and extends it with structured event typing, schema binding, and semantic versioning.

---

Event Type Format

We define a structured event type format as follows:

<namespace>.<subject>.<predicate>.<version>

Component	Description
namespace	Owning org or domain (e.g., dev.cdevents, org.jpmc, com.harness)
subject	The entity or process the event describes (e.g., pipelineRun, branch, testCaseRun)
predicate	The state change or intent (e.g., started, finished, initialCommit)
version	The semantic version of the event schema (e.g., v0.1.0, v1.0.0)

Each fully qualified event type (e.g. dev.cdevents.pipelineRun.started.v0.4.1) should be paired with a schemaUri field in the event’s context, pointing to a schema that validates the full structure of the event.

---

Examples

Use Case	Event Type
Official CDEvents	dev.cdevents.pipelineRun.started.v0.4.1
Experimental SIG	dev.cdeventsx.cdf-branch.initialCommit.v0.1.0
Vendor-specific	com.harness.artifact.approvalGranted.v1.2.0
Org-internal	org.jpmc.secops.scanner.failed.v0.3.1

---

Semantic Versioning Rules

Semantic Versioning governs the schema of the event, not the CDEvents spec as a whole. It enables the independent evolution of event types.

Version Change	Definition	Examples	Compatibility Requirement
MAJOR	Breaking change to the event’s schema or field types	Removing required fields, changing types	❌ Incompatible with consumers expecting previous version
MINOR	Additive changes (e.g., new optional fields)	Adding optional customData keys	✅ Backward compatible
PATCH	Metadata clarifications or documentation fixes	Updating field descriptions	✅ Safe upgrade

Each namespaced event type must include a schemaUri that matches its declared version and structure. This schema:

• MUST be a superset of the base event’s schema
• MUST validate any namespaced customData extensions

---

Base Event Contract Model

All CDEvents (standard, vendor, org-defined, or experimental) must declare a baseEvent in the context section. This creates a clear inheritance tree and enforces semantic interoperability.

Base Event Requirements

• Inheriting events must:
  • Preserve all required fields from the base schema
  • Not alter types or semantics
  • Add fields only
• A schemaUri must be provided for each versioned event

Understanding the Roles

schemaUri: This field points to the JSON Schema that defines the event's structure. It enables consumers to validate the event and generate code bindings.

baseEvent: This field indicates the event type from which the current event inherits. It serves as a semantic reference, allowing consumers to understand the event's lineage and apply appropriate processing logic.

Example Metadata Snippet

"context": {
  "type": "com.somecompany.change.created.v0.1.0",
  "baseEvent": "dev.cdevents.change.created.v0.4.1",
  "schemaURI": "https://somecompany.com/cdevents/V1/ci/change/created",
  "version": "0.1.0"
}

---

Empty Base Event

A new root-level "empty" base event is introduced for net-new event types that do not extend an existing CDEvent. These must align structurally with the CDEvents envelope.

JSON Envelope

{
  "context": {
    "type": "dev.cdevents.base.empty.v0.1.0",
    "version": "0.4.1",
    "id": "<uuid>",
    "source": "<source-uri>",
    "timestamp": "<timestamp>"
  },
  "subject": {},
  "customData": {}
}

---

Namespaced Plugin Routing via customData

CDEvents may include customData keys using the reserved ns: prefix to denote plugin-specific logic:

"customData": {
  "ns:jenkins": {
    "jobName": "build-api",
    "buildNumber": 5432
  },
  "ns:homedepot": {
    "complianceZone": "blue"
  }
}

• Conduit (SDLC Workflow Orchestrator) uses these keys to route payloads to registered plugins.
• Plugins are version-controlled and resolved by name+version from segment definitions.
• Each plugin SHOULD publish a schema under a known URI and conform to that shape.

---

Plugin Declaration in Segment YAML

segment: build
plugins:
  - name: jenkins
    version: 1.3.2
  - name: homedepot
    version: 2025.04

At runtime, Conduit looks up plugin versions from its internal registry and applies them to interpret and validate any ns: extensions in customData.

---

Developer Consumption Model

Schemas linked via schemaUri support:

• Runtime validation
• SDK generation
• DSL autocomplete
• Policy enforcement
• Trust and contract stability

---

Acknowledgements

Inspired by:

• WSDL targetNamespace
• Kubernetes Group-Version-Resource (GVR)
• XSD schema compatibility principles
• Practical implementations in the Conduit project
• Collaborative design by Dadisi Sanyika and Benjamin Powell

[sol-duara]

We should take a step back and ensure that we need this. I think this might only be needed when duplicating keys, but I am left with why you would need multiple keys with the same name originating from the same tool?

The case would look like:

some_id: "some_value"
team.some_id: "some_other_value"
company.some_id: "yet_another_value"

Other than testing, I don't know when you'd need this.