Adding Context metadata details to Context and API specs

Author: kriswest

website/docs/api/spec.md

@@ -122,6 +122,7 @@ An FDC3 Standard compliant Desktop Agent implementation **MUST**:
 - Provide details of whether they implement optional features of the Desktop Agent API in the `optionalFeatures` property of the [`ImplementationMetadata`](ref/Metadata#implementationmetadata) object returned by the [`fdc3.getInfo()`](ref/DesktopAgent#getinfo) function.
 - Allow, by default, at least a 15 second timeout for an application, launched via [`fdc3.open`](../api/ref/DesktopAgent#open), [`fdc3.raiseIntent`](../api/ref/DesktopAgent#raiseintent) or [`fdc3.raiseIntentForContext`](../api/ref/DesktopAgent#raiseintentforcontext) to add any context listener (via [`fdc3.addContextListener`](../api/ref/DesktopAgent#addcontextlistener)) or intent listener (via [`fdc3.addIntentListener`](../api/ref/DesktopAgent#addintentlistener)) necessary to deliver context or intent and context to it on launch. This timeout only applies to listeners needed to receive context on launch; further intent and context listeners not required on launch MAY be added later.
 - For web applications: All public methods of FDC3 interface objects (e.g. `DesktopAgent`, `Channel`, `PrivateChannel`, `IntentResolution`) **MUST** be bound to their respective instances (e.g. using `.bind(this)` in constructors) to support correct behavior when methods are destructured in JavaScript.  See [DesktopAgentProxy implementation](../../FDC3/packages/fdc3-agent-proxy/src/DesktopAgentProxy.ts) for a reference.
+- Make metadata about each context message or intent and context message received (including the app that originated the message and any supported metadata provided by that application) available to the receiving application.
 
 An FDC3 Standard compliant Desktop Agent implementation **SHOULD**:
 
@@ -130,7 +131,6 @@ An FDC3 Standard compliant Desktop Agent implementation **SHOULD**:
 - Allow applications to register an [`IntentHandler`](ref/Types#intenthandler) for particular Intent and Context type pairs by providing `interop.intents.listensFor` metadata in their AppD record.
 - Adopt the [recommended set of User channel definitions](#recommended-user-channel-set).
 - Ensure that context messages broadcast by an application on a channel are not delivered back to that same application if they are joined to the channel.
-- Make metadata about each context message or intent and context message received (including the app that originated the message) available to the receiving application.
 - Prevent external apps from listening or publishing on a [`PrivateChannel`](ref/PrivateChannel) that they did not request or provide.
 - Enforce compliance with the expected behavior of intents (where Intents specify a contract that is enforceable by schema, for example, return object types) and return an error if the interface is not met.
 
@@ -247,6 +247,10 @@ If no exact match is found then a fully-qualified `appId` provided should be spl
 
 The matching of an unqualified `appId` value against a set of fully-qualified appIds may result in multiple matches. In such cases, Desktop Agents SHOULD attempt additional resolution via any suitable procedure. For API calls such as [`raiseIntent`](./ref/DesktopAgent#raiseintent) or [`raiseIntentForContext`](./ref/DesktopAgent#raiseintentforcontext) Desktop Agents SHOULD use the same approach as they do for resolving ambiguous intents, for example by displaying an Intent Resolver UI and allowing the user to select the desired application. Alternatively, Desktop Agents MAY apply an alternative procedure such as selecting the first matching `appId` or, in the case of `findInstances`, by returning results for all matching fully-qualified `appId` values. Each of the API calls accepting an [`AppIdentifier`](ref/Types#appidentifier) as input, returns details of the `appId` in its results (i.e. [`AppIdentifier`](ref/Types#appidentifier), [`AppMetadata`](ref/Metadata#appmetadata), [IntentResolution](ref/Metadata#intentresolution)), where the fully-qualified appId matched MUST be used.
 
+### Receive metadata about a Broadcast or Raised Intent
+
+Applications often need both the business data (Context) and delivery-related information (ContextMetadata) such as origin, timestamp, or trace identifiers. To keep Context definitions clean and focused on data, FDC3 delivers metadata separately. Handlers receive two arguments: Context and ContextMetadata, enabling apps to process data and optionally use metadata for provenance, security, or correlation. See the [Context Overview](../context/spec#context-metadata) for more details on the separation of COntext and Context Metadata.
+
 ## Raising Intents
 
 Raising an Intent is a method for an application to request functionality from another application and, if desired, defer the discovery and launching of the destination app to the Desktop Agent.
@@ -552,7 +556,7 @@ A single handler can be added for each specific intent. If the application attem
 
 ### Metadata
 
-See [[#Context_Metadata]]
+See [Context Metadata](#context-metadata).
 
 ### Compliance with Intent Standards
 
@@ -861,28 +865,38 @@ Channel interface provides the ability to [`clearContext`](ref/Channel.md#clearc
 
 ### Metadata
 
-See [[#Context_Metadata]]
+See [Context Metadata](#context-metadata).
 
 ## Context Metadata
 
-Optional metadata about each context or intent message received SHOULD be provided by the desktop agent implementation to registered intent handlers. As this metadata is optional, apps making use of it MUST handle cases where it is not provided.
+FDC3 separates **Context** (business data) from **ContextMetadata** (delivery and provenance information) to maintain clarity and interoperability. Metadata is optional and SHOULD be provided by the Desktop Agent to registered listeners, but apps MUST handle cases where it is absent. 
+
+For the rationale for separating `Context` and `ContextMetadata`, see the [Context Specification](../context/spec#context-metadata).
+
+### Metadata properties
+
+Registered listeners MUST receive:
 
-Registered listeners SHOULD receive the following properties:
-* traceId
-* timestamp
-* source
+*   `timestamp` – Indicates when the message was delivered.
+*   `source` – Identifies the originating app (`AppIdentifier`).
 
-Registered listeners MAY receive the following properties:
-* custom
-<!-- * signature -->
+Registered listeners MAY receive:
 
-### Trace information
+*   `traceId` – Correlates related actions and messages.
+*   `custom` – Implementation-specific metadata.
 
-The Desktop Agent SHOULD provide a `traceId` to intent handlers. If the originating app provides `traceId` information, the Desktop Agent SHOULD use provide the `traceId` from the app. If the originating app does not provide `traceId` information, the Desktop Agent SHOULD generate a uuid., 
+<!-- TODO insert security/signature field names here -->
 
-If an app receives a context (from a broadcast or raised intent), and then performs an action *as a result of*, the app MAY forward the `traceId`. The Desktop Agent MAY collect the use of trace information and timestamp information for observability features.
+### Trace Information
 
-Here is example code run by an app. It listens for Contact information to be broadcast. Once that Contact information is received, it starts a call to that Contact. Since the app is placing an action *as a result of* another FDC3 action, the app passes along the received traceId.
+The Desktop Agent MAY provide a `traceId` to intent handlers.
+
+*   If the originating app provides a `traceId`, the Desktop Agent MUST forward it.
+*   If not, the Desktop Agent MAY generate a UUID.
+
+Apps MAY propagate `traceId` when performing actions as a result of another FDC3 action. This supports observability and correlation across workflows.
+
+**Example:**
 
 ```js
 fdc3.addIntentListener("ViewContact", (contactContext, metadata) => {
@@ -891,33 +905,32 @@ fdc3.addIntentListener("ViewContact", (contactContext, metadata) => {
   {
     type: "fdc3.contact",
     name: "Jane Doe",
-    id: {
-        email: 'jane@mail.com'
-    }
+    id: { email: 'jane@mail.com' }
   }
 
   Received metadata: 
   {
     traceId: generated uuid,
-    source: {...}
+    source: {...},
     timestamp: ...
   }
   */
 
- fdc3.raiseIntent("Start Call", contactContext, {
-  traceId: metadata.traceId
- })
-})
+  // Forward traceId when raising a related intent
+  fdc3.raiseIntent("StartCall", contactContext, {
+    traceId: metadata.traceId
+  });
+});
 ```
 
 ### Timestamp
 
-The Desktop Agent MAY provide timestamp information to intent handlers. 
-
-Apps SHOULD NOT provide timestamp information. If an app provides a timestamp, the Desktop Agent MUST ignore the timestamp.
+The Desktop Agent MUST provide timestamp information.  
+Apps SHOULD NOT provide timestamps; if they do, the Desktop Agent MUST ignore them.
 
 ### Source
 
-The Desktop Agent MAY provide source information to intent handlers. If the source information is provided, it MUST be in the form of an [[AppIdentifier]].
+The Desktop Agent MUST provide source information in the form of an `AppIdentifier`.  
+Apps SHOULD NOT provide source; if they do, the Desktop Agent MUST ignore it.
 
-Apps SHOULD NOT provide source information. If an app provides a source, the Desktop Agent MUST ignore it.
+<!-- TODO insert security/signature field overviews here -->

website/docs/context/spec.md

@@ -232,6 +232,22 @@ E.g. `"CURRENCY_ISOCODE": "GBP"`
 ISO 4217 only includes major currency codes, conversions to minor currencies is the responsibility of the consuming system (where required).
 :::
 
+### Context Metadata
+
+FDC3 Context is intended to provide a common _data_ format that is used for messaging between applications. Context object definitions should avoid including fields that represent metadata.
+
+Metadata such as the originating application, timestamps, digital signatures, or trace identifiers are important for routing, auditing, and linking related interactions, but they do not form part of the business data that the Context represents. Mixing metadata with core data can lead to ambiguity, increase complexity for developers, and reduce interoperability between implementations.
+
+To maintain clarity and consistency, FDC3 separates metadata from Context objects. This ensures that:
+
+- Context remains focused on the business data being shared, making it easier to define, validate, and reuse across different workflows.
+- Metadata can evolve independently to support advanced features such as provenance, security, and correlation without impacting the core data model.
+- Handlers receive both `Context` and `ContextMetadata` explicitly, allowing applications to process data and metadata according to their respective concerns.
+
+This separation provides a cleaner architecture, improves interoperability, and supports future enhancements without breaking existing Context definitions.
+
+For more details on `ContextMetadata` please see the [FDC3 API overview](../api/spec#receive-metadata-about-a-broadcast-or-raised-intent) and [`ContextMetadata` reference](../api/ref/Metadata#contextmetadata).
+
 ## Context Data Standard Compliance
 
 An FDC3 Standard compliant application that supports the use of context data **MUST**: