Add identity model

[Ma11hewThomas]

Summary

Adds an optional identity model to CTRF so reports can distinguish between document identity, logical run identity, stable test-case identity, execution identity, retry-attempt identity, attachment identity, and shard identity.

The goal is to avoid overloading a single id field and give producers and consumers clearer semantics for cross-run analysis, sharding, retries, artifact correlation, and future derived-report work.

What Changed

• Reworked the design principle currently focused on deterministic test identity into a broader Identity Model principle.
• Added a normative Identity Model section covering:
  • reportId for the emitted CTRF document artifact
  • runId for the logical test run
  • testId for the stable logical test case
  • executionId for a concrete test execution within a run
  • attemptId for an individual retry attempt
  • attachmentId for a specific attachment reference instance
  • shardId for the shard or partition that produced the document
• Clarified that reportId identifies the report artifact/content, not the logical test run.
• Clarified that retransmitting the same unchanged report should preserve the same reportId, while materially changed, regenerated, merged, filtered, or transformed reports should receive a new reportId.
• Added optional runId as a top-level field.
• Clarified tests[].id as a legacy compatibility field and stated that new producers should prefer tests[].testId.
• Added optional test-level testId and executionId.
• Added optional retry-attempt-level attemptId.
• Added optional attachment-level attachmentId in both test attachments and retry-attempt attachments.
• Added optional environment-level shardId.
• Added minLength: 1 constraints for identifier strings so empty IDs are rejected.
• Updated producer and consumer conformance guidance for identity fields.
• Updated Appendix B to describe deterministic testId generation with canonical strings as the primary producer-generated form, while keeping UUID v5 and hashes as optional deterministic encodings.
• Updated the comprehensive example in both the spec and standalone examples.
• Updated the JSON Schema and synced the embedded normative schema block in the spec.
• Added normative type-validation tests for the new identity fields.
• Added normative string-constraint tests for empty identifier strings.
• Added a valid normative example showing repeated testId with different executionId values.
• Added a changelog entry for the identity model.

Why

CTRF currently has reportId at the document level and id at the test level, but those identifiers do not cover all correlation needs clearly.

In practice, producers and consumers need to distinguish:

• the emitted CTRF document artifact
• a logical test run that may span shards or multiple CTRF documents
• a stable logical test case within a producer's chosen scope
• a specific execution of that test case
• individual retry attempts
• attachment reference instances
• the shard or partition that produced a document

This PR introduces those layers as optional fields so existing documents remain valid, while producers that need stronger correlation semantics have a clear standard shape.

Compatibility

This is intended to be backward compatible:

• All new identity fields are optional.
• Existing tests[].id remains valid.
• tests[].id is retained as a legacy compatibility field.
• Consumers MUST NOT assume that identity fields are present.
• Consumers SHOULD prefer testId when both id and testId are present.
• Consumers MUST NOT assume that testId values generated by different producers are globally comparable unless the producers document a shared generation scheme.

Out Of Scope

This PR defines identity primitives only. It does not define provenance, derivation, parent/child report relationships, transformation history, or trust metadata. Those concepts can build on these identifiers in a future change.

Assessment Notes

This branch was rebased onto the latest main after the immutability and namespace guidance changes landed.

During preparation:

• Conformance guidance conflicts were resolved by preserving both immutability guidance and identity guidance.
• Examples were kept aligned with the new namespaced extra guidance.
• The embedded JSON Schema block in spec/ctrf.md was synced exactly with schema/ctrf.schema.json.
• Uniqueness wording was softened so the spec describes intended identity scopes without making unrealistic global-enforcement claims.
• testId wording was tightened so producers keep it stable within their own documented scope, without implying independent producers will generate globally comparable values.

Follow-Up

This change will require downstream follow-up after the core spec/schema change lands.

Expected follow-up areas:

• ctrf-js: types, helpers, schema exports, fixtures, and deprecated id handling.
• ctrf-web: documentation, examples, and migration guidance for id to testId.
• ctrf-cli: bundled schema, validation fixtures, and user-facing validation/output messaging.
• Reporters and integrations: generated CTRF output, README examples, snapshots, runtime metadata APIs, and bundled schema copies.
• Non-JS implementations: schemas, generated output, fixtures, snapshots, and docs.

Validation

• jsonschema validate schema/ctrf.schema.json examples/*.json
• jsonschema test tests/ctrf.test.json
• jsonschema test tests/normative
• jsonschema test tests/informative
• Confirmed embedded CTRF JSON Schema block in spec/ctrf.md matches schema/ctrf.schema.json
• Confirmed standalone and embedded examples with extra use namespaced keys where present

[Copilot]

Pull request overview

This PR expands CTRF’s identifier semantics by introducing an optional, layered Identity Model (document, run, test case, execution, retry attempt, attachment, shard) and updates the spec, JSON Schema, examples, and normative tests to support these new fields while preserving backward compatibility with tests[].id.

Changes:

• Adds new optional identity fields (runId, testId, executionId, attemptId, attachmentId, shardId) and documents their intended scopes and stability in the spec.
• Updates schema/ctrf.schema.json (and the embedded normative schema in spec/ctrf.md) with the new fields plus minLength: 1 constraints for identifier strings.
• Extends normative test suites and examples to validate identity field types/constraints and demonstrate repeated testId with differing executionId.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/normative/valid-documents.test.json	Adds a valid normative case demonstrating repeated testId with different executionId values.
tests/normative/type-validation.test.json	Adds negative type-validation cases for the new identity fields.
tests/normative/string-constraints.test.json	Adds empty-string constraint cases for new identifier fields (and needs one more for baseline).
spec/ctrf.md	Introduces and normatively defines the Identity Model; updates field docs and embedded schema.
schema/ctrf.schema.json	Implements Identity Model fields and non-empty string constraints in the normative JSON Schema.
examples/comprehensive.json	Updates the comprehensive example to include the new identity fields.
CHANGELOG.md	Records the Identity Model addition in the changelog.

---

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