Question: Documentation or Types for Desktop Agent implementation of App Directory

[Roaders]

Question Area

• App Directory
• API
• Context Data
• Intents
• Use Cases
• Other

Question

We are close to implementing the app directory support for our Desktop Agent. I have been reading the docs but there does not seem to be any clear indication about how a Desktop Agent should handle app directory records - I am thinking specifically about how to open an app.

The only docs that I have found is the swagger. This is of some use but I was hoping for at least some Typescript d.ts files.

Is it specified anywhere how a DA should open an app? I have made some assumptions:

• the DA should look through the hostManifests until it finds one it recognises and then use that to open the app.
• the host manifests should be listed in order of priority (if the DA knows about the first one it will open that and ignore the rest)
• ideally a web manifest should always be included at the end of the list so that a DA can always open an app even if know nothing about the other manifests
• the url supplied in the details section is not used for opening the app but is just used for app identity

Are these assumptions correct?
Thanks

[kriswest]

Hi @Roaders, prior to FDC3 2.0 there was simply a manifest element in appD records that was used to start an application. However, manifest was vendor-specific and you could only provide one. In 2.0's appD we replaced manifest:

• a required details element expected to provide basic launch details that are vendor agnostic. It can contain a url property OR path and arguments for launching native apps, or alias and arguments for citrix apps or other app asset systems using aliases, or url again for ClickOnce apps.
• a required type element that determines how the details element should be interpreted.
• a hostManifests object, intended to contain vendor-specific launch properties.

How a DA launches apps, using the details in the appD is largely left as an implementation detail.

Regarding your assumptions:

1. • the DA should look through the hostManifests until it finds one it recognises and then use that to open the app.

   Valid. However, it should also consider the details and type elements - these can be overridden by the hostManifest:

   The manifest MAY duplicate or override information provided in the details field.

2. • the host manifests should be listed in order of priority (if the DA knows about the first one it will open that and ignore the rest)

   Not valid - there is no implied ordering in the object. The manifests each have a key which should be used to identify manifests that you support, all others should be ignored. The keys are not currently standardized (but should be IMHO), although a few examples are given. I think this is an area in which we could improve by standardizign keys - an issue should be raised for this.

3. • ideally a web manifest should always be included at the end of the list so that a DA can always open an app even if know nothing about the other manifests

   As commented above this is not a list but an object. The example shows a "Web App Manifest" key that you can use to pick this up, but as commented above the keys are not properly standardized, which we could change easily enough.

4. • the url supplied in the details section is not used for opening the app but is just used for app identity

   These elements predate any thoughts on app identity in FDC3 for the web and were absolutely intended to be used for launching apps, which is supported by the comments:

   type: The technology type that is used to launch and run the application. Each application type implies a particular set of launch details. The supported types include:

   • web: Web applications launched via a URL
   • native: Native applications pre-installed on a device and launch via a filesystem path
   • citrix: Apps virtualized via Citrixonline
   • Native: Native apps that have an online launcher, e.g. online ClickOnce app deployments.
   • other: Used to represent apps that do not conform to or cannot be launched via the other types, and are likely to be defined solely by a hostManifest.
     FDC3 Desktop Agents MUST support at least the web application type and MAY support any or all of the other types.

   details: The type specific launch details of the application. These details are intended to be vendor-agnostic and MAY be duplicated or overridden by details provided in the hostManifests object for a specific host.

   Rather FDC3 for the web is reusing the existing properties. There was also a suggestion that we should add an allowedDomains property to details to support identity validation (and multiple deployments/domains), but we never got around to adding it. If you (or any other participant from a fintech with on-prem deployments) ends up thinking that is needed it should be easy enough to add in.

If you are not seeing any of the comments quoted above in the appD spec, make sure you are clicking on the response elements, which pop open and provide the detail:

Theres an issue open to create a better docs page using a docusaurus plugin: #1001

Although we should probably get into the docusaurus update first (to avoid having to repeat that): #1371

We could also add some content to the main overview on using the appD standard, which it currently lacks: https://fdc3.finos.org/docs/2.0/app-directory/overview
The last round of changes to that address use cases after these were reconfirmed, following a rejected issue that sought to remove appD from the standard...

I'd be happy to help improve this content if an issue is raised (or this converted into an issue to improve the docs).

[kriswest]

P.S. You are also correct that there are no generated or maintained TS types for appD records. The closest that we have is the AppMetadata type which extends AppIdentifier and is a stripped down set of the metadata from the AppD record. Personally, I don't think the reaction of info from the appD record was necessary, but past FDC3 maintainers had strong opinions on that. Personally I think the biggest omission from app metadata is a URL for the appD record! This can be determined from a fully qualified appId (see https://fdc3.finos.org/docs/2.0/app-directory/overview#shrinking-the-uri and https://fdc3.finos.org/docs/2.0/app-directory/overview#fully-qualified-appid-namespace-syntax-host-resolution) so I have never understood the lack of a more explicit/easier to use link to the record.

As the security discussion group is looking to make greater use of the appD records for signing and encryption, it may be time to address this issue (in FDC3 2.3?) and add an explicit link to the appD record used for launch into either AppIdentifier or AppMetadata. We could import the whole record into AppMetadata (which is retrievable via getAppMetadata()) but I don't think that will be appropriate for the security group's use cases as they need the protection of the DNS system, rather than just going on info returned by the DA (as the use cases include protecting apps from nefarious DA implementations).

@Yannick-Malins @paulgoldsmith

[Roaders]

Thanks Kris

It seems like a good idea to provide more guidance on how a desktop agent should handle the app directory record. Ideally we would not have different behavior between different vendor implementations with the same app directory records. I am fine waiting for this to happen until after #1371 has been handled.

Would there be an objection to a PR adding types generated from the app directory schemas as we do for the browser types?

[kriswest]

To a certain extent there are differences in handling between agents baked into the concept of the hostManifests records - but we can manage that by starting to standardize the keys used (which seems long overdue).

I see no issue, and several benefits to, creating some client code for working with app directories! There are a couple of related issues worth mentioning:

• Provide better documentation and examples for AppD auth support #559
  • Client code should be able to deal with auth, however, there is no current reference implementation for either the server of client side of an appD. Although I do know of an implementation of an appD and could talk to the owner about contributing it...
• Create an AppD reference implementation #563
  • As above - need that reference implementation.

(related as client code should come with tests against a reference implementation)

@robmoffat also created an implementation for the FINOS appD, but has commented that it might not be an ideal ref implementation.

Next, it might be worth thinking about the OpenAPI spec as a client for an appD can be generated directly from that, along with associated types I believe. E.g. with https://github.com/hey-api/openapi-ts
Alternatively, we could partition the OpenAPI spec into schemas for the records and an OpenAPI schema that imports them, then generate TS types from the record schemas to include in the FDC3 module (I suggest code generation as it prevents us having to maintain both schemas and matching types). Types can at least provide inline docs to developers working with appD records. We could also simply write some additional documentation... although I do prefer a 'single source of truth' so we avoid repeating ourselves/double maintenance.

We can ignore #1371 for generated types, it shouldn't affect doing that. I mentioned it earlier in regards to having a better docs page for the existing schema - but it doesn't stop us improving the docs in the schema itself, nor generating things from it!

Hence, we can start by adding some comments based on the above clarifications to the OpenAPI spec then agree what we are going to do with that... I'm happy to add this to the next SWG agenda and come up with a plan? If its something you want to start in on go for it - otherwise I'm happy to help.

[Roaders]

Thanks for the as always detailed reply @kriswest .

Yes, the hostManifests records allow differnet vendor implementations to behave differently but some guidance on what to do if multiple or no host manifests are known would be useful for example.

For the types, yes I was planning on using some type generation magic to generate them automatically from the schemas. Can we use the same mechanism as we do for BrowserTypes or is the source of truth different in this case. You mention the OpenAPI schema - that's still a json schema isn't it? Can't we use the same tools to convert that to TS as we do for BrowserTypes?

[kriswest]

@Roaders there is a historical relationship between OpenAPI and JSON schema - they are partially compatible in OpenAPI 3.0 (which appD is still specified in), but I think fully compatible in 3.1. More details here: https://apisyouwonthate.com/blog/openapi-v3-1-and-json-schema/

If we separate the schemas for the records out, the OpenAPI schema can import them. At that point we can use the same quicktype tooling to generate types for the record schemas. Generators for OpenAPI are different in that they generate REST server skeletons and REST clients (in many languages) which (I presume) also come with types for the API messages (the records returned and other responses). Hence, we have a couple of possible routes.

Lists of OpenAPI generators:

• https://tools.openapis.org/categories/code-generators.html
• https://openapi-generator.tech/docs/generators/

I guess the quesiton is, are full generated clients more useful or types for the AppD records for rolling your own client and handling code?