Clarify extra namespace guidance

[Ma11hewThomas]

Summary

Clarifies the CTRF extension mechanism for extra objects so producers can add tool-specific, vendor-specific, or domain-specific metadata without creating collisions or fragmenting the core format.

This PR keeps CTRF strict outside defined extension points while making the intended shape of extension data clearer inside extra.

What Changed

• Reworked Section 4.6 into clearer subsections for extension keys, extension values, and extension semantics.
• Clarified that objects named extra are the only supported extensibility points in CTRF.
• Clarified that consumers MUST ignore unrecognized fields within any extra object and MUST NOT reject otherwise valid documents solely because those fields are present.
• Added namespace guidance for extension keys:
  • extension keys SHOULD be namespaced to avoid collisions
  • extension keys SHOULD use a stable, recognizable owner prefix
  • extension keys SHOULD include a delimiter such as . or /
  • extension keys are opaque identifiers, not hierarchical paths
• Reserved the ctrf.* namespace for CTRF-defined extensions.
• Added guidance that related extension fields SHOULD be grouped under a single extension key as an object value.
• Added guidance that a producer SHOULD use the same namespace prefix consistently across extra objects in a single document.
• Updated examples to demonstrate the intended grouped object style using dotted namespace keys such as myorg.ci and acme.test-management.
• Updated examples/comprehensive.json so the standalone comprehensive example matches the spec guidance.

Why

CTRF already supports extra, but the previous guidance did not say enough about how extension keys should be named or structured. Without clearer guidance, producers could create incompatible shapes for similar metadata, consumers could treat extension content inconsistently, and the extra mechanism could become difficult to reason about as adoption grows.

The intent is to preserve a small, stable core schema while giving producers a predictable extension pattern:

• use extra for extension data
• use a stable namespace key to avoid collisions
• group related fields under that key
• keep extension keys opaque
• reserve ctrf.* for extensions defined by CTRF itself

Examples

Preferred grouped extension shape:

{
  "extra": {
    "microsoft.azure-devops": {
      "pipelineId": "42",
      "runId": "10891",
      "stageName": "test"
    }
  }
}

This avoids spreading related fields across many flat keys and makes ownership clearer for consumers that choose to understand a specific extension.

Impact

This is a documentation and example clarification. It does not change the JSON Schema and does not add required fields.

Expected impact:

• Producers get clearer guidance for extension naming and structure.
• Consumers get clearer guidance that unknown extra content must be ignored within the extension mechanism.
• CTRF retains strict validation outside extra while allowing safe extension inside extra.
• Existing valid CTRF documents remain valid.

Validation

• jsonschema validate schema/ctrf.schema.json examples/*.json
• jsonschema test tests/ctrf.test.json
• jsonschema test tests/normative
• jsonschema test tests/informative

[Copilot]

Pull request overview

This PR refines the CTRF specification’s guidance around the extra extension mechanism, focusing on namespaced extension keys, opaque semantics, and consumer behavior when encountering unknown extension content. It also updates the comprehensive example JSON so it matches the new guidance and records the change in the changelog.

Changes:

• Reworked spec section 4.6 into clearer subsections for extension keys, values, and semantics, with explicit ignore/forward-compat rules for extra.
• Updated spec/ctrf.md examples and examples/comprehensive.json to demonstrate grouped, namespaced extension objects (e.g., myorg.ci).
• Added a changelog entry describing the clarified namespace guidance.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
spec/ctrf.md	Rewrites the extension mechanism guidance and updates/adds examples for namespaced extra usage.
examples/comprehensive.json	Updates the comprehensive example to use grouped, namespaced extra extension keys.
CHANGELOG.md	Notes the spec/example clarification in the Unreleased changelog.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.