analysis-constraints.md

CDEvents Conformance Analysis

Analysis of CDEvents schemas against the canonical fact constraints for the internal specification.

Constraint 1: Canonical facts must materially represent lifecycle state changes

FAIL — Several fields carry non-canonical data:

• labels (ticketcreated.json) — organizational/presentation metadata, not a lifecycle state
• milestone (ticketcreated.json) — organizational grouping, not a state transition
• description (incidentreported.json) — narrative text, not a lifecycle fact
• summary (ticketcreated.json) — human-readable title, not a structured lifecycle datum
• customData — explicitly designed as a catch-all; per spec.md: "typically require tool specific knowledge to be parsed" — this directly admits non-canonical content

---

Constraint 2: Every datum must be a canonical fact relevant to subject and predicate

FAIL — customData has no constraints to enforce relevance. The schema is:

"customData": {
  "oneOf": [
    { "type": "object" },
    { "type": "string", "contentEncoding": "base64" }
  ]
}

Any payload, canonical or not, passes validation. There is no mechanism to enforce that its contents are relevant to the event's subject or predicate.

---

Constraint 3: Relationships must use links; cross-system refs must use domainId or contextId; no foreign IDs in customData

PARTIAL FAIL:

• The links schema (embeddedlinkrelation.json, linkrelation.json) correctly uses contextId for event-to-event relationships.
• However, domainId does not exist anywhere in the schemas — it is not modeled at all. Cross-system references that need a domain-scoped identity have no structured field.
• artifactId (in buildfinished.json, servicedeployed.json, taskrunfinished.json) and ticketURI (in incidentreported.json) are plain opaque strings embedded in subject.content, not expressed as links. These are foreign entity references embedded as scalar values, not relationship links:

// buildfinished.json — foreign ID as plain string, not a link
"content": {
  "properties": {
    "artifactId": { "type": "string" }
  }
}

Compare to servicedeployed.json which uses the id/source pattern for environment, but still not a link.

---

Constraint 4: All datums must be structured and strongly typed; no free-form text for lifecycle semantics

FAIL — Multiple fields use unconstrained "type": "string" to convey lifecycle-relevant information:

Field	Schema	Problem
description	incidentreported.json	Free-form text conveying incident context
summary	ticketcreated.json	Free-form text conveying ticket purpose
reason	testcaserunfinished.json	Free-form text for test outcome reason
errors	taskrunfinished.json	Free-form text for failure description
pipelineName	pipelinerunstarted.json	Display name, not a structured identifier
taskName	taskrunstarted.json	Display name, not a structured identifier
name in testCase	testcaserunstarted.json	Display name nested in lifecycle object

None have length bounds, format constraints, or structural schemas.

---

Constraint 5: Datums must be stable across SDLC systems; no vendor-specific constructs

FAIL — The anyOf pattern used in ticket schemas explicitly allows vendor-specific values:

// ticketcreated.json
"ticketType": {
  "anyOf": [
    { "type": "string", "enum": ["bug", "enhancement", "incident", "task", "question"] },
    { "type": "string" }
  ]
},
"priority": {
  "anyOf": [
    { "type": "string", "enum": ["low", "medium", "high"] },
    { "type": "string" }
  ]
}

The second branch of anyOf makes the enum purely advisory. Tools can emit tool-specific values ("P0", "critical", "sev1") that cannot be deterministically consumed by other systems.

labels (array of unconstrained strings) similarly carries no cross-system semantics.

---

Constraint 6: CDEvents is not a metadata transport; non-canonical data must reside in the originating system, referenced by domainId or URI

FAIL — customData is architecturally designed for this exact purpose. The spec explicitly states it is for tool-specific data requiring "tool specific knowledge to parse." This is the definition of a metadata transport envelope. The spec should instead require that such data remain in the originating system and be referenced by URI.

---

Constraint 7: Attributes must be explicitly declared; no downstream inference from auxiliary fields

FAIL on two fronts:

1. customData is by definition undeclared attributes — the schema places no constraints on what keys or values appear inside it.

2. tags in link schemas uses additionalProperties: true:

// embeddedlinkrelation.json
"tags": {
  "type": "object",
  "additionalProperties": true
}

3. trigger in testcaserunstarted.json is missing additionalProperties: false, allowing arbitrary extension.

---

Summary

Constraint	Status	Key Issues
1. Canonical facts only	FAIL	labels, milestone, description, summary, customData
2. Datums relevant to subject/predicate	FAIL	customData is unconstrained
3. Relationships via links, cross-system via domainId/contextId	PARTIAL FAIL	artifactId as plain string; domainId absent from spec
4. Structured and strongly typed	FAIL	description, summary, reason, errors, *Name fields
5. Stable across SDLC systems	FAIL	ticketType/priority anyOf fallback allows vendor-specific strings
6. Not a metadata transport	FAIL	customData is explicitly a metadata transport
7. Explicitly declared attributes	FAIL	customData, tags with additionalProperties: true

The structural core (event envelope, context, subject identity) is well-formed with additionalProperties: false enforced consistently. The violations cluster around: (a) customData as a design primitive, (b) unstructured text fields on lifecycle-relevant properties, and (c) the open enum pattern in ticket schemas.