[WIP] Expand broadcast, raise*, and open methods to include metadata #1595

julianna-ciq · 2025-05-21T16:34:42Z

Describe your change

Adds the metadata property at the end of the .broadcast(), .raiseIntent(), .raiseIntentForContext(), and .open() methods.
Includes schema updates, doc updates, and implementation updates.

Provides placeholder space for signature (see #1571) and hostParams (#1546).

Related Issue

Resolves #1290

Contributor License Agreement

I acknowledge that a contributor license agreement is required and that I have one in place or will seek to put one in place ASAP.

Review Checklist

netlify · 2025-05-21T16:34:46Z

❌ Deploy Preview for fdc3 failed. Why did it fail? →

Name	Link
🔨 Latest commit	`ecd4c72`
🔍 Latest deploy log	https://app.netlify.com/projects/fdc3/deploys/688a6d99dc0c810008202db5

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

website/docs/api/spec.md

robmoffat · 2025-05-22T12:08:54Z

website/docs/api/spec.md

+})
+```
+
+### Timestamp


do we need this? We already have a timestamp in the message meta I think

I agree, tinestamp could/should be DA provided rather than app provided - even if it's the client code generating it

It was in my notes as one of the few properties we should support. Let's discuss what metadata properties should be included at the next Web meeting.

robmoffat · 2025-07-08T09:47:37Z

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

 				"payload": {
 					"$ref": "#/$defs/OpenRequestPayload"
 				},
+				"metadata": {


@kriswest @julianna-ciq

I've been looking at this. It doesn't seem like this gets generated into OpenRequest object in BrowserTypes. I'm not enough of an expert on JSON schema to really say why, except that I can add the metadata into the base type, AppRequest and it seems to push through.

However, I think this is the wrong place for this: I think the context metadata belongs in the payload, along with the context. After all, the message already has a meta field (which is the meta of the message) so it seems like we need to have meta inside the payload (the meta of the payload).

I agree that we should create fields in the payload, rather than as a sibling of it. That will move it further from the meta element that relates to the "envelope" or message format and more clearly tie it to a particular API call.

The reason that its not generating out in the current location is that the extra property is not allowed in the AppRequest schema, so when OpenRequest has AppRequest composed with it (as all requests do) the field gets dropped - that is part of the role of AppRequest: to govern the shape of those things derived from it and prevent additionalProperties that should not be there.

I'd say just go ahead and move it into the payload for every API message that should transmit either the app provided or super-set of app and DA-provided metadata (i.e. requests include appProvided, responses include both app and DA provided).

robmoffat · 2025-07-21T13:33:14Z

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

+    context: Context,
+    app?: AppIdentifier,
+    metadata?: AppProvidableContextMetadata
+  ): Promise<IntentResolution>;


This allows metadata to go from the app raising the intent to the app receiving it. However, it doesn't on its own allow metadata to come back from the receiver back to the raiser. We might need to extend the IntentResolution interface to add getResultMetadata perhaps?

Good point! Changing the return type of IntentResolution.getResult() would not be ideal (breaking).

However, we should also conider the fact that IntentResolution is itself a metadata object and returns the source for the resolution at least:

what app did the DA deliver it to...,

what was the intent (could have been chosen by the user or DA if there was only one)

But it is returned before the result (should come back at the same time that intent is delivered - so before the result). Hence, before we pick a solution here, what additional metadata might someone want? I'd argue timestamp isn't as interesting in intents (as you can't getCurrentContext() and pick it up later). Signatures are interesting (and would have to come from the app, rather than the DA). Anything else? Signature is probably enough of a use case...

Spent some time with @julianna-ciq talking about this - its one of the harder parts to solve in the design because its difficult for IntentHandler functions to return metadata, currently they can return Context, Channel or void, but we'd need a compound type with the metadata to return.

Further, IntentResolution is itself a metadata object that overlaps with the ContextMetadata some already, in that it contains the source field. A trace_id is less useful as it should be the same value used in the original call if provided and its still connected to that call. timestamp is less interesting as we don't have a call like getCurrentCOntext to worry about where it will be received later.

The one case I thought it mattered on is signature, there is a workaround where an app could return a channel and deliver signed results over that instead.

Hence, with added complexity and reduced utility, we think this should just be left out for now, and revisited if anyone comes up with a solid us-case for needing it.

kriswest

Review comments for a week or two ago

kriswest · 2025-05-22T07:39:20Z

packages/fdc3-agent-proxy/src/apps/DefaultAppSupport.ts

        },
        context,
      },
+      metadata,


In all other cases, parameters to FDC3 functions go into the payload element... I think we should stick to that pattern

kriswest · 2025-05-22T07:39:40Z

packages/fdc3-agent-proxy/src/intents/DefaultIntentSupport.ts

+        app,
      },
-      meta: meta,
+      metadata: {


See previous comment about keeping this in the payload

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

kriswest · 2025-05-22T07:46:11Z

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

+  traceId?: string;
+}
+
+export interface DesktopAgentProvidableContextMetadata {


Given that most of these fields are forwarded on from app provided metadata, we should could/should just integrate it into ContextMetadata... I was expecting to see a relationship to that type as that is the one we currently return, containing source

ContextMetadata appears defunct after this change, so it either needs to be removed or these changes integrated into it. I prefer the latter (put the new fileds into that type and keep it)

Just in the #1644 meeting, we are discussing the CDM use case. In this case, a CDM message may be broken down into a number of different FDC3 contexts. e.g. a priceQuantity message contains, date, instrument, amount, exchange, each of which might be a different context broadcast.

In this case, to re-assemble the message, it would be nice to use a common traceId across them all, but also have a count metadata item, so you know how many broadcasts should be bundled together.

kriswest · 2025-05-22T07:52:41Z

website/docs/api/spec.md

+
+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.
+
+Registered listeners SHOULD receive the following properties:


YOu SHOULD be able to pass these - in which case it SHOULD or MUST be passed on. But it needs to be conditional on an app setting it (apart from source which DA MSUT provide and MUST NOT forward if passed by app to avoid spoofing).

kriswest · 2025-05-22T07:52:47Z

website/docs/api/spec.md

+
+Apps SHOULD NOT provide timestamp information. If an app provides a timestamp, the Desktop Agent MUST ignore the timestamp.
+
+### Source


I'd use the original label (Originating App Metadata) in the content somewhere to retain the link to the use case.

kriswest · 2025-05-22T07:53:24Z

website/docs/api/spec.md

 Intent handlers SHOULD be registered via [`fdc3.addIntentListener`](ref/DesktopAgent#addintentlistener) within 15 seconds of the application launch (the minimum timeout Desktop Agents are required to provide) in order to be widely compatible with Desktop Agent implementations. Individual Desktop Agent implementations MAY support longer timeouts or configuration to control or extend timeouts.

-### Originating App Metadata
+### Metadata


I'd add a brief textual description saying additional metadata may be passed ...

kriswest · 2025-05-22T12:16:17Z

website/docs/api/spec.md

+})
+```
+
+### Timestamp


I agree, tinestamp could/should be DA provided rather than app provided - even if it's the client code generating it

kriswest · 2025-07-08T13:18:12Z

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

 				"payload": {
 					"$ref": "#/$defs/OpenRequestPayload"
 				},
+				"metadata": {


I agree that we should create fields in the payload, rather than as a sibling of it. That will move it further from the meta element that relates to the "envelope" or message format and more clearly tie it to a particular API call.

The reason that its not generating out in the current location is that the extra property is not allowed in the AppRequest schema, so when OpenRequest has AppRequest composed with it (as all requests do) the field gets dropped - that is part of the role of AppRequest: to govern the shape of those things derived from it and prevent additionalProperties that should not be there.

I'd say just go ahead and move it into the payload for every API message that should transmit either the app provided or super-set of app and DA-provided metadata (i.e. requests include appProvided, responses include both app and DA provided).

kriswest · 2025-07-21T14:11:24Z

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

+    context: Context,
+    app?: AppIdentifier,
+    metadata?: AppProvidableContextMetadata
+  ): Promise<IntentResolution>;


Good point! Changing the return type of IntentResolution.getResult() would not be ideal (breaking).

However, we should also conider the fact that IntentResolution is itself a metadata object and returns the source for the resolution at least:

what app did the DA deliver it to...,

what was the intent (could have been chosen by the user or DA if there was only one)

But it is returned before the result (should come back at the same time that intent is delivered - so before the result). Hence, before we pick a solution here, what additional metadata might someone want? I'd argue timestamp isn't as interesting in intents (as you can't getCurrentContext() and pick it up later). Signatures are interesting (and would have to come from the app, rather than the DA). Anything else? Signature is probably enough of a use case...

linux-foundation-easycla · 2025-07-30T18:52:47Z

✅ login: julianna-ciq / name: Julianna Langston (bfbf987, d0fb59a, 675e788, 08afab6, 2099c6d, 1dde7d2)
❌ The email address for the commit (3d21281, a7f26f4, ecd4c72) is not linked to the GitHub account, preventing the EasyCLA check. Consult this Help Article and GitHub Help to resolve. (To view the commit's email address, add .patch at the end of this PR page's URL.) For further assistance with EasyCLA, please submit a support request ticket.

kriswest · 2025-08-07T17:49:05Z

Wouldn't you also have the single compound message with them all in? What is suggested in the current docs is that you compose one large context made up of smaller ones, broadcast all the smaller ones with the big one last. Apps can listen for whatever they support.

robmoffat · 2025-08-08T08:30:10Z

Wouldn't you also have the single compound message with them all in? What is suggested in the current docs is that you compose one large context made up of smaller ones, broadcast all the smaller ones with the big one last. Apps can listen for whatever they support.

Yeah makes sense.

Add *ProvidableContextMetadata types and prox-agent handling

675e788

julianna-ciq requested a review from a team as a code owner May 21, 2025 16:34

kriswest mentioned this pull request May 22, 2025

Standard WG Meeting - May 22nd, 2025 #1596

Closed

16 tasks

robmoffat reviewed May 22, 2025

View reviewed changes

julianna-ciq added 5 commits June 18, 2025 07:01

Update generated

08afab6

Merge branch 'main' into gh1290

1dde7d2

Address typo

bfbf987

Remove rejected property

2099c6d

Explicit type imports

d0fb59a

kriswest mentioned this pull request Jun 26, 2025

Standard WG Meeting - June 26th, 2025 #1623

Closed

20 tasks

robmoffat added this to the 2.3 candidates milestone Jul 8, 2025

robmoffat reviewed Jul 8, 2025

View reviewed changes

robmoffat mentioned this pull request Jul 8, 2025

FDC3 Security In MonoRepo - NOT READY TO REVIEW #1627

Draft

40 tasks

robmoffat reviewed Jul 21, 2025

View reviewed changes

kriswest reviewed Jul 23, 2025

View reviewed changes

Remove 'signature' parameter from *ContextMetadata

3d21281

Julianna Langston added 2 commits July 30, 2025 15:03

Consolidate ContextMetadata definitions

a7f26f4

Update agent-proxy

ecd4c72

kriswest mentioned this pull request Aug 21, 2025

FDC3 for Web Browsers & Bridging Discussion group - 21st Aug 2025 #1653

Closed

15 tasks

kriswest mentioned this pull request Aug 28, 2025

Standard WG Meeting - Aug 28th, 2025 #1656

Closed

22 tasks

kriswest mentioned this pull request Oct 16, 2025

FDC3 for Web Browsers & Bridging Discussion group - 16th October 2025 #1686

Open

18 tasks


		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.

		Registered listeners SHOULD receive the following properties:


		Apps SHOULD NOT provide timestamp information. If an app provides a timestamp, the Desktop Agent MUST ignore the timestamp.

		### Source

[WIP] Expand broadcast, raise*, and open methods to include metadata #1595

Are you sure you want to change the base?

[WIP] Expand broadcast, raise*, and open methods to include metadata #1595

Conversation

julianna-ciq commented May 21, 2025

Describe your change

Related Issue

Contributor License Agreement

Review Checklist

Uh oh!

netlify bot commented May 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

❌ Deploy Preview for fdc3 failed. Why did it fail? →

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kriswest left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

linux-foundation-easycla bot commented Jul 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kriswest commented Aug 7, 2025 via email • edited by robmoffat Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

robmoffat commented Aug 8, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

netlify bot commented May 21, 2025 •

edited

Loading

linux-foundation-easycla bot commented Jul 30, 2025 •

edited

Loading

kriswest commented Aug 7, 2025 via email •

edited by robmoffat

Loading