Make ContextMetadata traceId optional

CHANGELOG.md

@@ -65,6 +65,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ### Fixed
 
+* Made `ContextMetadata.traceId` optional in the schema-generated typings and conformance requirements, aligning them with the API type and the Desktop Agent's optional trace ID generation.
 * Fixed the basic conformance version check to use the exported FDC3 version and accept newer compatible Desktop Agents. ([#1966](https://github.com/finos/FDC3/pull/1966))
 * Reduced normal `getAgent` discovery console noise by ignoring unrelated `postMessage` traffic and reporting expected agent-not-found timeouts as warnings instead of errors. ([#1902](https://github.com/finos/FDC3/issues/1902))
 * Prevented the FDC3 for Web reference implementation from sending channel-changed events to applications that have not registered a matching listener. ([#1806](https://github.com/finos/FDC3/issues/1806))

packages/fdc3-schema/generated/api/BrowserTypes.ts

@@ -1299,7 +1299,7 @@ export interface ContextMetadata {
    * A unique identifier for the context or intent that can be used to trace the context or
    * intent through the system.
    */
-  traceId: string;
+  traceId?: string;
 }
 
 /**
@@ -5536,7 +5536,7 @@ const typeMap: any = {
       { json: 'signature', js: 'signature', typ: u(undefined, r('DetachedSignature')) },
       { json: 'source', js: 'source', typ: r('AppIdentifier') },
       { json: 'timestamp', js: 'timestamp', typ: Date },
-      { json: 'traceId', js: 'traceId', typ: '' },
+      { json: 'traceId', js: 'traceId', typ: u(undefined, '') },
     ],
     false
   ),

packages/fdc3-schema/generated/bridging/BridgingTypes.ts

@@ -4289,7 +4289,7 @@ export interface ContextMetadata {
    * A unique identifier for the context or intent that can be used to trace the context or
    * intent through the system.
    */
-  traceId: string;
+  traceId?: string;
 }
 
 /**
@@ -6608,7 +6608,7 @@ const typeMap: any = {
       { json: 'signature', js: 'signature', typ: u(undefined, r('DetachedSignature')) },
       { json: 'source', js: 'source', typ: r('AppIdentifier') },
       { json: 'timestamp', js: 'timestamp', typ: Date },
-      { json: 'traceId', js: 'traceId', typ: '' },
+      { json: 'traceId', js: 'traceId', typ: u(undefined, '') },
     ],
     false
   ),

packages/fdc3-schema/schemas/api/api.schema.json

@@ -397,8 +397,7 @@
             },
             "required": [
                 "source",
-                "timestamp",
-                "traceId"
+                "timestamp"
             ],
             "additionalProperties": false
         },

packages/fdc3-standard/src/api/ContextMetadata.ts

@@ -75,9 +75,10 @@ export interface AppProvidableContextMetadata {
  * Metadata relating to a context or intent received through the
  * `addContextListener` and `addIntentListener` functions.
  *
- * Includes delivery information provided by the Desktop Agent (`source`,
- * `timestamp`, `traceId`) and optional metadata forwarded from the
- * originating app (`signature`, `antiReplay`, `traceId`, `custom`).
+ * Includes required delivery information provided by the Desktop Agent
+ * (`source`, `timestamp`) and optional metadata forwarded from the originating
+ * app or generated by the Desktop Agent (`signature`, `antiReplay`, `traceId`,
+ * `custom`).
  */
 export interface ContextMetadata extends AppProvidableContextMetadata {
   /** The timestamp when the context was broadcast or the intent was raised. */

toolbox/fdc3-conformance/src/test/advanced/fdc3.raiseIntent-Result.ts

@@ -204,8 +204,6 @@ export default async () =>
       control.validateIntentResult(intentResult, IntentResultType.Context, ContextType.testContextY);
       const metadata = await control.getIntentResultMetadata(intentResolution);
       control.validateResultMetadata(metadata, intentResolution.source);
-      // DA-generated traceId must be present
-      expect(metadata.traceId, 'traceId should be a non-empty string').to.be.a('string').and.not.equal('');
     });
 
     const RaiseIntentChannelResultMetadata =

toolbox/fdc3-conformance/src/test/support/intent-support.ts

@@ -132,9 +132,6 @@ export class RaiseIntentControl {
     expect(metadata, 'getResultMetadata() should resolve to a ContextMetadata object').to.be.an('object');
     expect(metadata).to.have.property('source');
     expect(metadata).to.have.property('timestamp');
-    expect(metadata).to.have.property('traceId');
-    expect(typeof metadata.traceId).to.equal('string');
-    expect(metadata.traceId).to.not.equal('');
     if (expectedSource) {
       expect(metadata.source.appId, 'resultMetadata.source.appId should match the resolving app').to.equal(
         expectedSource.appId

website/docs/api/conformance/Intents-Tests.md

@@ -180,7 +180,7 @@ The optional `newInstance` argument to `raiseIntent` lets a calling application
 | Test   | 3. IntentResolution         | The `raiseIntent` call returns an `IntentResolution` object. |
 | B      | 4. Return plain Context     | B returns a plain `testContextY` instance (no metadata). |
 | Test   | 5. await getResultMetadata  | Test calls `await resolution.getResultMetadata()`. |
-| Test   | 6. Verify DA metadata       | The returned `ContextMetadata` MUST include `source` (with B's `appId` and `instanceId`), `timestamp` and `traceId` fields generated by the Desktop Agent. |
+| Test   | 6. Verify DA metadata       | The returned `ContextMetadata` MUST include `source` (with B's `appId` and `instanceId`) and `timestamp`. It MAY include a `traceId` generated by the Desktop Agent. |
 
 - `RaiseIntentContextResultMetadata` ![3.0+](https://img.shields.io/badge/FDC3-3.0+-purple): Perform the above test.
 
@@ -194,7 +194,7 @@ The optional `newInstance` argument to `raiseIntent` lets a calling application
 | B      | 4. Return ContextWithMetadata | B returns a `ContextWithMetadata` object: `{ context: testContextY, metadata: { traceId: "app-trace-id", signature: "app-sig", custom: { key: "value" } } }`. |
 | Test   | 5. await getResult          | Test calls `await resolution.getResult()`. The result MUST be the plain `testContextY` context, not the `ContextWithMetadata` wrapper. |
 | Test   | 6. await getResultMetadata  | Test calls `await resolution.getResultMetadata()`. |
-| Test   | 7. Verify merged metadata   | The returned `ContextMetadata` MUST include `source` (B's identity), `timestamp` and `traceId` from the Desktop Agent, AND the app-provided `signature` and `custom` fields. The Desktop Agent's `traceId` MUST take precedence over the app-provided one. |
+| Test   | 7. Verify merged metadata   | The returned `ContextMetadata` MUST include `source` (B's identity), `timestamp`, and the app-provided `traceId`, `signature`, and `custom` fields. |
 
 - `RaiseIntentContextWithMetadataResult` ![3.0+](https://img.shields.io/badge/FDC3-3.0+-purple): Perform the above test.
 
@@ -205,7 +205,7 @@ The optional `newInstance` argument to `raiseIntent` lets a calling application
 | Test   | 1. Raise                    | `fdc3.raiseIntent("sharedTestingIntent2", testContextY)` starts app **E**. |
 | E      | 2. Receive & return Channel | E returns a Channel (or void). |
 | Test   | 3. await getResultMetadata  | Test calls `await resolution.getResultMetadata()`. |
-| Test   | 4. Verify DA-only metadata  | The returned `ContextMetadata` MUST include `source`, `timestamp` and `traceId` generated by the Desktop Agent. No app-provided `signature` or `custom` fields should be present. |
+| Test   | 4. Verify DA-only metadata  | The returned `ContextMetadata` MUST include `source` and `timestamp`, and MAY include a `traceId` generated by the Desktop Agent. No app-provided `signature` or `custom` fields should be present. |
 
 - `RaiseIntentChannelResultMetadata` ![3.0+](https://img.shields.io/badge/FDC3-3.0+-purple): Perform the above test with a Channel result.
 - `RaiseIntentVoidResultMetadata` ![3.0+](https://img.shields.io/badge/FDC3-3.0+-purple): Perform the above test with a void result.

website/docs/api/ref/Types.md

@@ -561,7 +561,7 @@ interface IContextMetadata
 type ContextMetadata struct {
   Source     AppIdentifier          `json:"source"`
   Timestamp  time.Time              `json:"timestamp"`
-  TraceId    string                 `json:"traceId"`
+  TraceId    string                 `json:"traceId,omitempty"`
   Signature  *DetachedSignature     `json:"signature,omitempty"`
   AntiReplay *AntiReplayClaims      `json:"antiReplay,omitempty"`
   Custom     map[string]interface{} `json:"custom,omitempty"`