From b8451fcb614458a5b9e3a69141d1be391dee4c5e Mon Sep 17 00:00:00 2001
From: Matthew Thomas <25988124+Ma11hewThomas@users.noreply.github.com>
Date: Sat, 24 Oct 2026 13:17:32 +0100
Subject: [PATCH] Document legacy test identifier removal in CTRF 1.0.0

---
 CHANGELOG.md                              |  2 ++
 schema/ctrf.schema.json                   |  2 +-
 spec/ctrf.md                              |  8 +++---
 tests/normative/valid-documents.test.json | 32 +++++++++++++++++++++++
 4 files changed, 40 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index fa513e1..c3c3444 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- Documented legacy `id` removal in 1.0.0 and version-based migration while retaining current acceptance and optional `testId`.
+
 - Clarified durable attachment references, optional producer-local paths and producer-defined digest metadata.
 
 - Added coordinated cross-process retry examples and clarified logical-run correlation and final-attempt duration.
diff --git a/schema/ctrf.schema.json b/schema/ctrf.schema.json
index 25bdba5..ee2a14f 100644
--- a/schema/ctrf.schema.json
+++ b/schema/ctrf.schema.json
@@ -138,7 +138,7 @@
             "required": [ "name", "status", "duration" ],
             "properties": {
               "id": {
-                "description": "Legacy identifier for the test case (UUID). New producers should prefer testId",
+                "description": "Deprecated test-case identifier (UUID), scheduled for removal in CTRF 1.0.0. Still accepted in this version; prefer optional testId when providing case identity",
                 "type": "string",
                 "format": "uuid",
                 "minLength": 1
diff --git a/spec/ctrf.md b/spec/ctrf.md
index 5abee8f..c603331 100644
--- a/spec/ctrf.md
+++ b/spec/ctrf.md
@@ -885,7 +885,7 @@ Each field within the test object is described in the subsections below.
 
 ### 9.1. `id`
 
-> **Legacy.** `id` is retained for backward compatibility. New producers SHOULD prefer `testId` (Section 9.2).
+> **Deprecated.** `id` is retained for backward compatibility and is scheduled for removal in CTRF 1.0.0. Producers SHOULD use `testId` (Section 9.2) instead when providing test-case identity; `testId` remains OPTIONAL.
 
 **Description:**  
 A unique, stable identifier for the test case.
@@ -895,7 +895,9 @@ A unique, stable identifier for the test case.
 If present, it MUST be a valid UUID as defined in [RFC9562].\
 Producers SHOULD prefer `testId` for new implementations.  
 When both `id` and `testId` are present, consumers SHOULD use `testId`.
-Consumers SHOULD treat `id` as legacy unless a producer documents stronger semantics.
+Consumers SHOULD treat `id` as legacy.
+
+Migration follows the document's declared specification version. Reports declaring CTRF 1.0.0 will be required to omit `id`; producers emitting earlier specification versions can continue to follow those versions' contracts. Consumers reading those earlier reports SHOULD use `testId` in preference to `id` when both are present. This deprecation notice does not remove `id` from the current schema or require producers to supply `testId`.
 
 ### 9.2. `testId`
 
@@ -2254,7 +2256,7 @@ to this specification.
             "required": [ "name", "status", "duration" ],
             "properties": {
               "id": {
-                "description": "Legacy identifier for the test case (UUID). New producers should prefer testId",
+                "description": "Deprecated test-case identifier (UUID), scheduled for removal in CTRF 1.0.0. Still accepted in this version; prefer optional testId when providing case identity",
                 "type": "string",
                 "format": "uuid",
                 "minLength": 1
diff --git a/tests/normative/valid-documents.test.json b/tests/normative/valid-documents.test.json
index 72b69d1..e7bc6f8 100644
--- a/tests/normative/valid-documents.test.json
+++ b/tests/normative/valid-documents.test.json
@@ -68,6 +68,38 @@
       "description": "Durable attachment references with producer-defined local paths and digests",
       "valid": true,
       "dataPath": "../../examples/portable-attachments.json"
+    },
+    {
+      "description": "Legacy id remains accepted alongside optional testId before 1.0.0",
+      "valid": true,
+      "data": {
+        "reportFormat": "CTRF",
+        "specVersion": "0.2.0",
+        "results": {
+          "tool": {
+            "name": "example-runner"
+          },
+          "summary": {
+            "tests": 1,
+            "passed": 1,
+            "failed": 0,
+            "pending": 0,
+            "skipped": 0,
+            "other": 0,
+            "start": 1609459200000,
+            "stop": 1609459201000
+          },
+          "tests": [
+            {
+              "name": "should pass",
+              "status": "passed",
+              "duration": 100,
+              "id": "12345678-1234-4234-8234-123456789abc",
+              "testId": "preferred-case-key"
+            }
+          ]
+        }
+      }
     }
   ]
 }