Add identity model

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- Added an optional identity model for CTRF documents, logical runs, test cases, executions, attempts, attachments, and shards ([#57](https://github.com/ctrf-io/ctrf/pull/57)).
 - Clarified namespace guidance for `extra` extension keys and examples ([#56](https://github.com/ctrf-io/ctrf/pull/56)).
 - Clarified immutability guidance for emitted CTRF report artifacts ([#55](https://github.com/ctrf-io/ctrf/pull/55)).
 - Clarified `tags` as simple keyless classifications and `labels` as structured key-value test metadata ([#54](https://github.com/ctrf-io/ctrf/pull/54)).

examples/comprehensive.json

@@ -2,6 +2,7 @@
   "reportFormat": "CTRF",
   "specVersion": "1.0.0",
   "reportId": "9d2c6a10-3f7a-4e22-9a8f-1a2b3c4d5e6f",
+  "runId": "run-2025-11-24-pr-123",
   "timestamp": "2025-11-24T12:00:00Z",
   "generatedBy": "example-ci",
   "extra": {
@@ -36,6 +37,8 @@
     "tests": [
       {
         "id": "550e8400-e29b-41d4-a716-446655440000",
+        "testId": "auth-login-user-can-login",
+        "executionId": "2cf7e0b4-ea0c-4ef4-a18a-b9d6f6f0e100",
         "name": "user can login",
         "status": "passed",
         "duration": 3500,
@@ -71,6 +74,8 @@
       },
       {
         "id": "550e8400-e29b-41d4-a716-446655440001",
+        "testId": "checkout-user-can-checkout",
+        "executionId": "2cf7e0b4-ea0c-4ef4-a18a-b9d6f6f0e101",
         "name": "user can checkout",
         "status": "passed",
         "duration": 5200,
@@ -93,6 +98,7 @@
         "retryAttempts": [
           {
             "attempt": 1,
+            "attemptId": "48c3f90b-95a9-4c13-a42f-0888bb0b1001",
             "status": "failed",
             "duration": 5100,
             "start": 1609459203500,
@@ -101,6 +107,7 @@
             "trace": "Error: Payment gateway timeout\n    at processPayment (payment.js:23:10)",
             "attachments": [
               {
+                "attachmentId": "72d531af-9d77-4f3b-bf67-0d8ec26c2001",
                 "name": "attempt-1-screenshot.png",
                 "contentType": "image/png",
                 "path": "/artifacts/retry-1.png"
@@ -109,6 +116,7 @@
           },
           {
             "attempt": 2,
+            "attemptId": "48c3f90b-95a9-4c13-a42f-0888bb0b1002",
             "status": "passed",
             "duration": 5200,
             "start": 1609459208700,
@@ -131,6 +139,8 @@
       },
       {
         "id": "550e8400-e29b-41d4-a716-446655440002",
+        "testId": "admin-dashboard-loads",
+        "executionId": "2cf7e0b4-ea0c-4ef4-a18a-b9d6f6f0e102",
         "name": "admin dashboard loads",
         "status": "failed",
         "duration": 8000,
@@ -163,16 +173,19 @@
         ],
         "attachments": [
           {
+            "attachmentId": "72d531af-9d77-4f3b-bf67-0d8ec26c2002",
             "name": "failure-screenshot.png",
             "contentType": "image/png",
             "path": "/artifacts/screenshots/admin-dashboard-fail.png"
           },
           {
+            "attachmentId": "72d531af-9d77-4f3b-bf67-0d8ec26c2003",
             "name": "trace.zip",
             "contentType": "application/zip",
             "path": "/artifacts/traces/admin-dashboard.trace.zip"
           },
           {
+            "attachmentId": "72d531af-9d77-4f3b-bf67-0d8ec26c2004",
             "name": "video.webm",
             "contentType": "video/webm",
             "path": "/artifacts/videos/admin-dashboard.webm"
@@ -214,6 +227,7 @@
       "repositoryUrl": "https://github.com/example/example-app",
       "commit": "a1b2c3d4e5f6",
       "branchName": "feature/new-dashboard",
+      "shardId": "shard-1",
       "osPlatform": "linux",
       "osRelease": "5.10.0",
       "osVersion": "Ubuntu 20.04",

schema/ctrf.schema.json

@@ -15,9 +15,15 @@
       "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"
     },
     "reportId": {
-      "description": "Unique identifier for this report instance (UUID)",
+      "description": "Unique identifier for this CTRF document instance (UUID). Identifies the serialized artifact",
       "type": "string",
-      "format": "uuid"
+      "format": "uuid",
+      "minLength": 1
+    },
+    "runId": {
+      "description": "Identifier for the logical test run. Shared across shards/documents belonging to the same run",
+      "type": "string",
+      "minLength": 1
     },
     "timestamp": {
       "description": "Report generation time (RFC 3339 / ISO 8601)",
@@ -132,9 +138,20 @@
             "required": [ "name", "status", "duration" ],
             "properties": {
               "id": {
-                "description": "Unique, stable identifier for the test case (UUID)",
+                "description": "Legacy identifier for the test case (UUID). New producers should prefer testId",
+                "type": "string",
+                "format": "uuid",
+                "minLength": 1
+              },
+              "testId": {
+                "description": "Stable identifier for the logical test case. Should be derived from stable test attributes when generated by a producer",
                 "type": "string",
-                "format": "uuid"
+                "minLength": 1
+              },
+              "executionId": {
+                "description": "Unique identifier for this specific execution of the test case within a run. UUID recommended",
+                "type": "string",
+                "minLength": 1
               },
               "name": {
                 "description": "Name or title of the test case",
@@ -255,6 +272,11 @@
                       "type": "integer",
                       "minimum": 1
                     },
+                    "attemptId": {
+                      "description": "Unique identifier for this individual retry attempt. UUID recommended",
+                      "type": "string",
+                      "minLength": 1
+                    },
                     "status": {
                       "description": "Outcome of this attempt",
                       "enum": [
@@ -315,6 +337,11 @@
                         "type": "object",
                         "required": [ "name", "contentType", "path" ],
                         "properties": {
+                          "attachmentId": {
+                            "description": "Unique identifier for this attachment reference instance. UUID recommended",
+                            "type": "string",
+                            "minLength": 1
+                          },
                           "name": {
                             "description": "Display name of the attachment",
                             "type": "string"
@@ -385,6 +412,11 @@
                   "type": "object",
                   "required": [ "name", "contentType", "path" ],
                   "properties": {
+                    "attachmentId": {
+                      "description": "Unique identifier for this attachment reference instance. UUID recommended",
+                      "type": "string",
+                      "minLength": 1
+                    },
                     "name": {
                       "description": "Display name of the attachment",
                       "type": "string"
@@ -546,6 +578,11 @@
               "description": "Logical test environment (e.g., 'staging', 'production')",
               "type": "string"
             },
+            "shardId": {
+              "description": "Shard or partition label identifying which part of a distributed run produced this document",
+              "type": "string",
+              "minLength": 1
+            },
             "healthy": {
               "description": "Indicates if the run is considered healthy",
               "type": "boolean"
@@ -611,7 +648,8 @@
         "reportId": {
           "description": "UUID of the baseline report",
           "type": "string",
-          "format": "uuid"
+          "format": "uuid",
+          "minLength": 1
         },
         "timestamp": {
           "description": "Generation time of the baseline report",