From 20274c5838c8cf023f00cd5aa016d753e44bc749 Mon Sep 17 00:00:00 2001 From: Kris West Date: Tue, 14 Jun 2022 12:14:05 +0100 Subject: [PATCH 1/6] Redrafting compliance page and providing compliance summary in both the Desktop Agent and App Directory API specs --- docs/api/ref/DesktopAgent.md | 114 +++++++++++++++++------------------ docs/api/ref/Errors.md | 65 ++++++++++---------- docs/api/spec.md | 75 ++++++++++++++++++----- docs/app-directory/spec.md | 28 ++++++++- docs/fdc3-compliance.md | 33 +++++----- 5 files changed, 192 insertions(+), 123 deletions(-) diff --git a/docs/api/ref/DesktopAgent.md b/docs/api/ref/DesktopAgent.md index 4f16ed178..a88e5596a 100644 --- a/docs/api/ref/DesktopAgent.md +++ b/docs/api/ref/DesktopAgent.md @@ -34,7 +34,7 @@ interface DesktopAgent { createPrivateChannel(): Promise; getUserChannels(): Promise>; - // optional channel management functions + // OPTIONAL channel management functions joinUserChannel(channelId: string) : Promise; getCurrentChannel() : Promise; leaveCurrentChannel() : Promise; @@ -183,6 +183,59 @@ fdc3.broadcast(instrument); * [addContextListener](#addcontextlistener) +### `createPrivateChannel` + +```ts +createPrivateChannel(): Promise; +``` + +Returns a `Channel` with an auto-generated identity that is intended for private communication between applications. Primarily used to create channels that will be returned to other applications via an IntentResolution for a raised intent. + +If the `PrivateChannel` cannot be created, the returned promise MUST be rejected with an error string from the [`ChannelError`](Errors#channelerror) enumeration. + +The `PrivateChannel` type is provided to support synchronisation of data transmitted over returned channels, by allowing both parties to listen for events denoting subscription and unsubscription from the returned channel. `PrivateChannels` are only retrievable via raising an intent. + +It is intended that Desktop Agent implementations: + +* SHOULD restrict external apps from listening or publishing on this channel. +* MUST prevent `PrivateChannels` from being retrieved via fdc3.getOrCreateChannel. +* MUST provide the `id` value for the channel as required by the `Channel` interface. + +#### Example + +```js +fdc3.addIntentListener("QuoteStream", async (context) => { + const channel = await fdc3.createPrivateChannel(); + const symbol = context.id.ticker; + + // This gets called when the remote side adds a context listener + const addContextListener = channel.onAddContextListener((contextType) => { + // broadcast price quotes as they come in from our quote feed + feed.onQuote(symbol, (price) => { + channel.broadcast({ type: "price", price}); + }); + }); + + // This gets called when the remote side calls Listener.unsubscribe() + const unsubscriberListener = channel.onUnsubscribe((contextType) => { + feed.stop(symbol); + }); + + // This gets called if the remote side closes + const disconnectListener = channel.onDisconnect(() => { + feed.stop(symbol); + }); + + return channel; +}); +``` + +#### See also + +* [`PrivateChannel`](PrivateChannel) +* [`raiseIntent`](#raiseintent) +* [`addIntentListener`](#addintentlistener) + ### `findInstances` ```ts @@ -359,7 +412,7 @@ await fdc3.raiseIntent(startChat.intent.name, context, selectedApp); getCurrentChannel() : Promise; ``` -Optional function that returns the `Channel` object for the current User channel membership. In most cases, an application's membership of channels SHOULD be managed via UX provided to the application by the desktop agent, rather than calling this function directly. +OPTIONAL function that returns the `Channel` object for the current User channel membership. In most cases, an application's membership of channels SHOULD be managed via UX provided to the application by the desktop agent, rather than calling this function directly. Returns `null` if the app is not joined to a channel. @@ -434,59 +487,6 @@ catch (err){ * [`Channel`](Channel) -### `createPrivateChannel` - -```ts -createPrivateChannel(): Promise; -``` - -Returns a `Channel` with an auto-generated identity that is intended for private communication between applications. Primarily used to create channels that will be returned to other applications via an IntentResolution for a raised intent. - -If the `PrivateChannel` cannot be created, the returned promise MUST be rejected with an error string from the [`ChannelError`](Errors#channelerror) enumeration. - -The `PrivateChannel` type is provided to support synchronisation of data transmitted over returned channels, by allowing both parties to listen for events denoting subscription and unsubscription from the returned channel. `PrivateChannels` are only retrievable via raising an intent. - -It is intended that Desktop Agent implementations: - -* SHOULD restrict external apps from listening or publishing on this channel. -* MUST prevent `PrivateChannels` from being retrieved via fdc3.getOrCreateChannel. -* MUST provide the `id` value for the channel as required by the `Channel` interface. - -#### Example - -```js -fdc3.addIntentListener("QuoteStream", async (context) => { - const channel = await fdc3.createPrivateChannel(); - const symbol = context.id.ticker; - - // This gets called when the remote side adds a context listener - const addContextListener = channel.onAddContextListener((contextType) => { - // broadcast price quotes as they come in from our quote feed - feed.onQuote(symbol, (price) => { - channel.broadcast({ type: "price", price}); - }); - }); - - // This gets called when the remote side calls Listener.unsubscribe() - const unsubscriberListener = channel.onUnsubscribe((contextType) => { - feed.stop(symbol); - }); - - // This gets called if the remote side closes - const disconnectListener = channel.onDisconnect(() => { - feed.stop(symbol); - }); - - return channel; -}); -``` - -#### See also - -* [`PrivateChannel`](PrivateChannel) -* [`raiseIntent`](#raiseintent) -* [`addIntentListener`](#addintentlistener) - ### `getUserChannels` ```ts @@ -512,7 +512,7 @@ const redChannel = userChannels.find(c => c.id === 'red'); joinUserChannel(channelId: string) : Promise; ``` -Optional function that joins the app to the specified User channel. In most cases, applications SHOULD be joined to channels via UX provided to the application by the desktop agent, rather than calling this function directly. +OPTIONAL function that joins the app to the specified User channel. In most cases, applications SHOULD be joined to channels via UX provided to the application by the desktop agent, rather than calling this function directly. If an app is joined to a channel, all `fdc3.broadcast` calls will go to the channel, and all listeners assigned via `fdc3.addContextListener` will listen on the channel. @@ -545,7 +545,7 @@ fdc3.joinUserChannel(selectedChannel.id); leaveCurrentChannel() : Promise; ``` -Optional function that removes the app from any User channel membership. In most cases, an application's membership of channels SHOULD be managed via UX provided to the application by the desktop agent, rather than calling this function directly. +OPTIONAL function that removes the app from any User channel membership. In most cases, an application's membership of channels SHOULD be managed via UX provided to the application by the desktop agent, rather than calling this function directly. Context broadcast and listening through the top-level `fdc3.broadcast` and `fdc3.addContextListener` will be a no-op when the app is not joined to a User channel. diff --git a/docs/api/ref/Errors.md b/docs/api/ref/Errors.md index 76ab4070e..1dfd27f9f 100644 --- a/docs/api/ref/Errors.md +++ b/docs/api/ref/Errors.md @@ -4,6 +4,39 @@ title: Errors Some FDC3 API operations return promises that can result in errors. +## `ChannelError` + +```typescript +enum ChannelError { + /** Returned if the specified channel is not found when attempting to join a + * channel via the `joinUserChannel` function of the DesktopAgent (`fdc3`). + */ + NoChannelFound = 'NoChannelFound', + + /** SHOULD be returned when a request to join a user channel or to a retrieve + * a Channel object via the `joinUserChannel` or `getOrCreateChannel` methods + * of the DesktopAgent (`fdc3`) object is denied. + */ + AccessDenied = 'AccessDenied', + + /** SHOULD be returned when a channel cannot be created or retrieved via the + * `getOrCreateChannel` method of the DesktopAgent (`fdc3`). + */ + CreationFailed = 'CreationFailed', +} +``` + +Contains constants representing the errors that can be encountered when calling channels using the [`joinUserChannel`](DesktopAgent#joinuserchannel) or [`getOrCreateChannel`](DesktopAgent#getorcreatechannel) methods, or the [`getCurrentContext`](Channel#getcurrentcontext), [`broadcast`](Channel#broadcast) or [`addContextListener`](Channel#addcontextlistener) methods on the `Channel` object. + +#### See also + +* [`DesktopAgent.createPrivateChannel`](DesktopAgent#createprivatechannel) +* [`DesktopAgent.joinUserChannel`](DesktopAgent#joinuserchannel) +* [`DesktopAgent.getOrCreateChannel`](DesktopAgent#getorcreatechannel) +* [`Channel.broadcast`](Channel#broadcast) +* [`Channel.addContextListener`](Channel#addcontextlistener) +* [`Channel.getCurrentContext`](Channel#getcurrentcontext) + ## `OpenError` ```typescript @@ -107,35 +140,3 @@ Contains constants representing the errors that can be encountered when calling * [`DesktopAgent.addIntentListener`](DesktopAgent#addintentlistener) * [`DesktopAgent.raiseIntent`](DesktopAgent#raiseintent) * [`IntentResolution`](Metadata#intentresolution) - -## `ChannelError` - -```typescript -enum ChannelError { - /** Returned if the specified channel is not found when attempting to join a - * channel via the `joinUserChannel` function of the DesktopAgent (`fdc3`). - */ - NoChannelFound = 'NoChannelFound', - - /** SHOULD be returned when a request to join a user channel or to a retrieve - * a Channel object via the `joinUserChannel` or `getOrCreateChannel` methods - * of the DesktopAgent (`fdc3`) object is denied. - */ - AccessDenied = 'AccessDenied', - - /** SHOULD be returned when a channel cannot be created or retrieved via the - * `getOrCreateChannel` method of the DesktopAgent (`fdc3`). - */ - CreationFailed = 'CreationFailed', -} -``` - -Contains constants representing the errors that can be encountered when calling channels using the [`joinUserChannel`](DesktopAgent#joinuserchannel) or [`getOrCreateChannel`](DesktopAgent#getorcreatechannel) methods, or the [`getCurrentContext`](Channel#getcurrentcontext), [`broadcast`](Channel#broadcast) or [`addContextListener`](Channel#addcontextlistener) methods on the `Channel` object. - -#### See also - -* [`DesktopAgent.joinUserChannel`](DesktopAgent#joinuserchannel) -* [`DesktopAgent.getOrCreateChannel`](DesktopAgent#getorcreatechannel) -* [`Channel.broadcast`](Channel#broadcast) -* [`Channel.addContextListener`](Channel#addcontextlistener) -* [`Channel.getCurrentContext`](Channel#getcurrentcontext) diff --git a/docs/api/spec.md b/docs/api/spec.md index c312dd589..e23450136 100644 --- a/docs/api/spec.md +++ b/docs/api/spec.md @@ -40,27 +40,14 @@ Examples of endpoints include: ## Desktop Agent Implementation -The FDC3 API specification consists of interfaces. It is expected that each Desktop Agent will implement these interfaces. A typical implemention would provide instantiable classes for the following interfaces: +The FDC3 API specification consists of interfaces. It is expected that each Desktop Agent will implement these interfaces. A typical implemention would provide implementations for the following interfaces: - [`DesktopAgent`](ref/DesktopAgent) - [`Channel`](ref/Channel) - [`PrivateChannel`](ref/PrivateChannel) - [`Listener`](ref/Types#listener) -Other interfaces defined in the spec are not critical to define as concrete types. Rather, the Desktop Agent should expect to have objects of the interface shape passed into or out of their library. These interfaces include: - -- [`AppIntent`](ref/Metadata#appintent) -- [`AppMetadata`](ref/Metadata#appmetadata) -- [`Context`](ref/Types#context) -- [`ContextHandler`](ref/Types#contexthandler) -- [`DisplayMetadata`](ref/Metadata#displaymetadata) -- [`Icon`](ref/Types#icon) -- [`ImplementationMetadata`](ref/Metadata#implementationmetadata) -- [`IntentHandler`](ref/Types#intenthandler) -- [`IntentResult`](ref/Types#intentresult) -- [`IntentMetadata`](ref/Metadata#intentmetadata) -- [`IntentResolution`](ref/Metadata#intentresolution) -- [`TargetApp`](ref/Types#targetapp) +Other interfaces defined in the spec are not critical to define as concrete types. Rather, the Desktop Agent should expect to have objects of the interface shape passed into or out of their library. ### API Access @@ -105,6 +92,62 @@ Desktop Agent interop is supported by common standards for APIs for App discover An actual connection protocol between Desktop Agents is not currently available in the FDC3 standard, but work on creating one for a future version of the standard is underway (see [GitHub discussion #544](https://github.com/finos/FDC3/discussions/544) for details). +### Desktop Agent API Standard Compliance + +An FDC3 Standard compliant Desktop Agent implementation **MUST**: + +- Provide the FDC3 API to web applications via a global accessible as [`window.fdc3`](#api-access). +- Provide a global [`fdc3Ready`](#api-access) event that is fired when the API is ready for use. +- Provide a method of resolving ambiguous intents (i.e. those that might be resolved by multiple applications) or unspecified intents (calls to raiseIntentForCOntext that return multiple options), usch as a resolver UI. + - Intent resolution MUST take into account any specified input or return context types + - Requests for resolution to apps returning a channel MUST include any apps that are registered as returning a channel with a specific type. +- Return Errors from the [`ChannelError`](ref/Errors#channelerror), [`OpenError`](ref/Errors#openerror), [`ResolveError`](ref/Errors#resolveerror) and [`ResultError`](ref/Errors#resulterror) enumerations as appropriate. +- Accept as input and return as output data structures that are compatibile with the interfaces defined in this Standard. +- Include implementations of the following [Desktop Agent](ref/DesktopAgent) API functions, as defined in this Standard: + - [`addContextListener`](ref/DesktopAgent#addcontextlistener) + - [`addIntentListener`](ref/DesktopAgent#addintentlistener) + - [`broadcast`](ref/DesktopAgent#broadcast) + - [`createPrivateChannel`](ref/DesktopAgent#createprivatechannel) + - [`findInstances`](ref/DesktopAgent#findinstances) + - [`findIntent`](ref/DesktopAgent#findintent) + - [`findIntentsByContext`](ref/DesktopAgent#findintentsbycontext) + - [`getCurrentChannel`](ref/DesktopAgent#getcurrentchannel) + - [`getInfo`](ref/DesktopAgent#getinfo) + - [`getOrCreateChannel`](ref/DesktopAgent#getorcreatechannel) + - [`getUserChannels`](ref/DesktopAgent#getuserchannels) + - [`open`](ref/DesktopAgent#open) + - [`raiseIntent`](ref/DesktopAgent#raiseintent) + - [`raiseIntentForContext`](ref/DesktopAgent#raiseintentforcontext) +- Provide an ID for each [`PrivateChannel`](ref/PrivateChannel) created via [`createPrivateChannel`](ref/DesktopAgent#createprivatechannel) and prevent them from being retrieved via [`getOrCreateChannel`](ref/DesktopAgent#getorcreatechannel) by ID. +- Only require app directories that they connect to to have implemented only the minimum requirements specified in the [App Directory API Part](../app-directory/spec) of this Standard. + +An FDC3 Standard compliant Desktop Agent implementation **SHOULD**: + +- Support connection to one or more App Directories meeting the [FDC3 App Directory Standard](../app-directory/overview). +- Qualify `appId` values received from an app directory with the hostname of the app directory server (e.g. `myAppId@name.domain.com`) [as defined in the app directory standard](../app-directory/overview#application-identifiers). +- 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. + +An FDC3 Standard compliant Desktop Agent implementation **MAY**: + +- Make the Desktop Agent API available through modules, imports, or other means. +- Implement the following OPTIONAL [Desktop Agent](ref/DesktopAgent) API functions: + - [`joinUserChannel`](ref/DesktopAgent#joinuserchannel) + - [`leaveCurrentChannel`](ref/DesktopAgent#leavecurrentchannel) + - [`getCurrentChannel`](ref/DesktopAgent#getcurrentchannel) +- Implement the following deprecated API functions: + - [`addContextListener`](ref/DesktopAgent#addcontextlistener-deprecated) (without a contextType argument) + - [`getSystemChannels`](ref/DesktopAgent#getsystemchannels-deprecated) (renamed getUserChannels) + - [`joinChannel`](ref/DesktopAgent#joinchannel-deprecated) (renamed joinUserChannel) + - [`open`](ref/DesktopAgent#open-deprecated) (deprecated version that addresses apps via `name` field) + - [`raiseIntent`](ref/DesktopAgent#raiseintent-deprecated) (deprecated version that addresses apps via `name` field) + - [`raiseIntentForContext`](ref/DesktopAgent#raiseintentforcontext-deprecated) (deprecated version that addresses apps via `name` field) + +For more details on FDC3 Standards compliance (including the versioning, deprecation and experimental features policies) please see the [FDC3 Compliance page](../fdc3-compliance). + ## Functional Use Cases ### Retrieve Metadata about the Desktop Agent implementation @@ -350,7 +393,7 @@ When an app joins a User channel, or adds a context listener when already joined It is possible that a call to join a User channel could be rejected. If for example, the desktop agent wanted to implement controls around what data apps can access. -Joining channels in FDC3 is intended to be a behavior initiated by the end user. For example: by color linking or apps being grouped in the same workspace. Most of the time, it is expected that apps will be joined to a channel by mechanisms outside of the app. To support programmatic management of joined channels and the implementation of channel selector UIs other than those provided outside of the app, Desktop Agent implementations MAY provide [`fdc3.joinChannel()`](ref/DesktopAgent#joinchannel), [`fdc3.getCurrentChannel()](ref/DesktopAgent#getcurrentchannel) and [`fdc3.leaveCurrentChannel()`](ref/DesktopAgent#leavecurrentchannel) functions and if they do, MUST do so as defined in the [Desktop Agent API reference](ref/DesktopAgent). +Joining channels in FDC3 is intended to be a behavior initiated by the end user. For example: by color linking or apps being grouped in the same workspace. Most of the time, it is expected that apps will be joined to a channel by mechanisms outside of the app. To support programmatic management of joined channels and the implementation of channel selector UIs other than those provided outside of the app, Desktop Agent implementations MAY provide [`fdc3.joinChannel()`](ref/DesktopAgent#joinchannel), [`fdc3.getCurrentChannel()`](ref/DesktopAgent#getcurrentchannel) and [`fdc3.leaveCurrentChannel()`](ref/DesktopAgent#leavecurrentchannel) functions and if they do, MUST do so as defined in the [Desktop Agent API reference](ref/DesktopAgent). There SHOULD always be a clear UX indicator of what channel an app is joined to. diff --git a/docs/app-directory/spec.md b/docs/app-directory/spec.md index f2b77ab28..65fd136fd 100644 --- a/docs/app-directory/spec.md +++ b/docs/app-directory/spec.md @@ -16,4 +16,30 @@ View the [full specification](/schemas/next/app-directory) in [OpenAPI v3.0](htt `/v1/apps/{appId}` | GET | (deprecated v1 API version) Retrieve an application defintion `/v1/apps/search` | GET | (deprecated v1 API version) Retrieve a list of applications -App Directory implementations MAY extend the list of endpoints to provide other necessary functionality. However, FDC3 Desktop Agent implementations MUST support connection to app directories that only provide the minimum endpoints listed here. +App Directory implementations MAY extend the list of endpoints to provide other necessary functionality. However, FDC3 Desktop Agent implementations that connect to app direcotries MUST support connection to app directories that only provide the minimum endpoints listed here. + +## App Directory Standard Compliance + +An FDC3 Standard compliant App Directory implementation **MUST**: + +* Implement the specified `/v2` endpoints for retrieving app definitions as defined in the [app directory OpenAPI specification](/schemas/next/app-directory#tag/Application/paths/~1v2~1apps~1{appId}/get): + * `/v2/apps` (GET) + * `/v2/apps/{appId}` (GET) +* Ensure that `appId` field values assigned to applications are unique within the directory. +* Ensure that app directory records served meet the minimum requirements specified in the [app directory OpenAPI specification](/schemas/next/app-directory#tag/Application/paths/~1v2~1apps~1{appId}/get) +* Support retrieval of app directory records via either the raw appId (e.g. `myAppId`) or fully-qualified appId (e.g. `myAppId@host.domain.com`) as defined in the [app directory overview](overview#shrinking-the-uri). + +An FDC3 Standard compliant App Directory implementation **SHOULD**: + +* Support authentication (where required) via the HTTP Authorization header and Bearer authentication schema (implemented via JWT tokens) +* Select any `categories` field values from the recommended list. +* Encourage the use of the `lang` and `localizedVersions` fields in appD records to support localisation and accessibility. + +An FDC3 Standard compliant App Directory implementation **MAY**: + +* Support filtering of application records returned by user entitlement, where authentication is enabled. +* Implement the deprecated `/v1` endpoints provided for backwards compatability with prior version of the standard: + * `/v1/apps` (POST) + * `/v1/apps/{appId}` (GET) + * `/v1/apps/search` (GET) +* Extend the implementation with additional endpoints. diff --git a/docs/fdc3-compliance.md b/docs/fdc3-compliance.md index 424f18322..595b29d55 100644 --- a/docs/fdc3-compliance.md +++ b/docs/fdc3-compliance.md @@ -20,32 +20,31 @@ In general, the ratified FDC3 specs represent a lowest common denominator interf These rules would apply only to standards work within FDC3. Today, this covers the API, App Directory, Context Data, and Intents specifications. ## Personas -FDC3 implementors generally fall into 2 categories: platform providers, and application providers. A platform provider supplies an implementation of the FDC3 API for applications to use. Implicitly, it connects to one or more App Directories. +FDC3 implementors generally fall into 2 categories: platform providers, and application providers. A platform provider supplies an implementation(s) of the FDC3 APIs (The Desktop Agent API and Applkication Directory) for applications to use. An application provider is largely a downstream consumer of FDC3 standards. It MAY use the API, it MAY use Context Data, it MAY use Intents. Application providers are only required to comply with the standards they make use of. Depending on persona, implementation compliance with FDC3 will mean different things. ### Platform Provider -For platform providers FDC3 compliance requires: +For platform providers FDC3 compliance requires that they meet the requirements of the APIs that they implement: -* Support for connections to 1 or more App Directories meeting the FDC3 App Directory standards SHOULD be provided -* An API implementation that meets the FDC3 API standards MUST be provided to all applications running in the context of the platform, including: - * Support for the FDC3 Context Data and Intents standards - * Support for intent and context resolution using a resolver UI - * Support for retrieving information about the version of the FDC3 specification supported by a Desktop Agent implementation and the name of the implementation provider -* In the case of web applications, a Desktop Agent MUST provide the FDC3 API via a global accessible as `window.fdc3`. +* [Desktop Agent API compliance requirements](api/spec#desktop-agent-api-standard-compliance). +* [App Directory compliance requirements](app-directory/spec#app-directory-standard-compliance). ### Application Provider -For application providers FDC3 compliance requires: -* If intents are supported by the application, they SHOULD favor supporting applicable FDC3 defined standard intents over proprietary ones. -* If FDC3 defined intents are supported, they MUST meet the expected context and behavior defined for the intent. -* If proprietary intents are handled, those intents SHOULD follow the recommended naming conventions in the specification. -* If intents are supported, the application SHOULD use the `addIntentListener` API to set up a handler. -* If context data is supported by the application, they SHOULD favor supporting applicable FDC3 defined context data types over proprietary ones. -* If FDC3 defined context data is supported, it MUST meet the interface defined for that type of context data. -* If proprietary context data properties are handled, they SHOULD follow any recommended naming conventions in the specification. -* If context data is supported, the application SHOULD use the `addContextListener` API to set up a handler. +For application providers FDC3 compliance requires that they interact with the FDC3 APIs as intended. Specifically: + +* If Intents are supported by the application: + * FDC3 defined standard intents used MUST meet the expected context and behavior defined for the intent. + * Where available, FDC3 defined standard intents SHOULD be used in preference to proprietary intents. + * Proprietary intents used SHOULD follow the recommended naming conventions in the specification. + * The application MUST use the `addIntentListener` API to set up a handler when it starts up. +* If context data sharing via channels is supported by the application: + * FDC3 defined standard context types used MUST meet the interface defined for that type of context data. + * Where available, FDC3 defined standard context types SHOULD used in preference to proprietary contexts. + * Proprietary context data types SHOULD follow any recommended naming and format conventions in the specification. + * Where Channels are supported or an app is intended to receive context from `fdc3.open` calls, the application MUST use the `addContextListener` API to set up appropriate handlers when it starts up (for User channels and for receiving context from `fdc3.open`) or when the channel is first created or retrieved (for App and Private channels). ## Versioning Typically, a Standard that has marketplace relevance is revised from time to time, to correct errors and/or to add functionality to support new use cases. Hence, there exist multiple versions of the standard. As FDC3 is a standards project, we don't follow semver, which is meant for libraries. We use the versioning scheme `.`, e.g. `1.1` or `2.3`. From 23a352497ddabaea0e466f43fd1941c597feb3d0 Mon Sep 17 00:00:00 2001 From: Kris West Date: Tue, 14 Jun 2022 14:49:25 +0100 Subject: [PATCH 2/6] Adding intent and context data standard compliance details for app providers --- docs/context/spec.md | 60 +++++++++++++++++++++++++++-------------- docs/fdc3-compliance.md | 37 +++++++++++++------------ docs/intents/spec.md | 22 ++++++++++++++- 3 files changed, 79 insertions(+), 40 deletions(-) diff --git a/docs/context/spec.md b/docs/context/spec.md index d44d03503..477796af6 100644 --- a/docs/context/spec.md +++ b/docs/context/spec.md @@ -10,12 +10,12 @@ Context objects are used when raising [intents](../intents/spec) and when broadc There are two main use cases for exchanging context data: -* __Transmitting reference data between applications.__ +* **Transmitting reference data between applications.** The source application will send as many known identifiers as possible, and the target application will try to match the entity based on the identifiers. It may then choose to map to its own internal domain representation for rendering purposes. An example of this is sending an instrument or contact, when only an ISIN or email is required to reference the same data in another application. -* __Transferring information between applications.__ +* **Transferring information between applications.** The source application may have data required to compose a workflow with another application, e.g. a list of contacts that have been selected, or a complex object representing an RFQ request. In many such cases there aren't any sensible reference identifiers that can be shared, it is instead the data itself being transferred. @@ -135,31 +135,50 @@ E.g. `"CURRENCY_ISOCODE": "GBP"` > Note: ISO 4217 only includes major currency codes, conversions to minor currencies is the responsibility of the consuming system (where required). +## Context Data Standard Compliance + +An FDC3 Standard compliant application that supports the use of context data **MUST**: + +* Ensure that any FDC3-defined standard context types used meet the interface defined for that type of context data. +* Where Channels are supported or an app is intended to receive context from [`fdc3.open`](api/ref/DesktopAgent#open) calls, use the [`fdc3.addContextListener`](api/ref/DesktopAgent#addcontextlistener) API call to set up appropriate handlers on start-up (for User channels and for receiving context from [`fdc3.open`](api/ref/DesktopAgent#open)) or when the channel is first created or retrieved (for App and Private channels). + +An FDC3 Standard compliant application that supports the use of context data **SHOULD**: + +* Prefer FDC3-defined standard context types over proprietary contexts, where a suitable FDC3-defined stanrd context type is available. +* Ensure that any proprietary context data types fefined follow any the recommended [namespacing](#namespacing) and [field type conventions](#field-type-conventions) in the specification. + +An FDC3 Standard compliant application that supports the use of context data **MAY**: + +* Define proprietary context data types to support use cases not currently supported via FDC3-defined standard context types. + +For more details on FDC3 Standards compliance (including the versioning, deprecation and experimental features policies) please see the [FDC3 Compliance page](../fdc3-compliance). + ## Standard Context Types The following are standard FDC3 context types: -- [`fdc3.chart`](ref/Chart) ([schema](/schemas/next/chart.schema.json)) -- [`fdc3.chat.initSettings`](ref/ChatInitSettings) ([schema](/schemas/next/chatInitSettings.schema.json)) -- [`fdc3.contact`](ref/Contact) ([schema](/schemas/next/contact.schema.json)) -- [`fdc3.contactList`](ref/ContactList) ([schema](/schemas/next/contactList.schema.json)) -- [`fdc3.country`](ref/Country) ([schema](/schemas/next/country.schema.json)) -- [`fdc3.currency`](ref/Currency) ([schema](/schemas/next/currency.schema.json)) -- [`fdc3.email`](ref/Email) ([schema](/schemas/next/email.schema.json)) -- [`fdc3.instrument`](ref/Instrument) ([schema](/schemas/next/instrument.schema.json)) -- [`fdc3.instrumentList`](ref/InstrumentList) ([schema](/schemas/next/instrumentList.schema.json)) -- [`fdc3.organization`](ref/Organization) ([schema](/schemas/next/organization.schema.json)) -- [`fdc3.portfolio`](ref/Portfolio) ([schema](/schemas/next/portfolio.schema.json)) -- [`fdc3.position`](ref/Position) ([schema](/schemas/next/position.schema.json)) -- [`fdc3.nothing`](ref/Nothing) ([schema](/schemas/next/nothing.schema.json)) -- [`fdc3.timerange`](ref/TimeRange) ([schema](/schemas/next/timerange.schema.json)) -- [`fdc3.valuation`](ref/Valuation) ([schema](/schemas/next/valuation.schema.json)) - -__Note:__ The below examples show how the base context data interface can be used to define specific context data objects. +* [`fdc3.chart`](ref/Chart) ([schema](/schemas/next/chart.schema.json)) +* [`fdc3.chat.initSettings`](ref/ChatInitSettings) ([schema](/schemas/next/chatInitSettings.schema.json)) +* [`fdc3.contact`](ref/Contact) ([schema](/schemas/next/contact.schema.json)) +* [`fdc3.contactList`](ref/ContactList) ([schema](/schemas/next/contactList.schema.json)) +* [`fdc3.country`](ref/Country) ([schema](/schemas/next/country.schema.json)) +* [`fdc3.currency`](ref/Currency) ([schema](/schemas/next/currency.schema.json)) +* [`fdc3.email`](ref/Email) ([schema](/schemas/next/email.schema.json)) +* [`fdc3.instrument`](ref/Instrument) ([schema](/schemas/next/instrument.schema.json)) +* [`fdc3.instrumentList`](ref/InstrumentList) ([schema](/schemas/next/instrumentList.schema.json)) +* [`fdc3.organization`](ref/Organization) ([schema](/schemas/next/organization.schema.json)) +* [`fdc3.portfolio`](ref/Portfolio) ([schema](/schemas/next/portfolio.schema.json)) +* [`fdc3.position`](ref/Position) ([schema](/schemas/next/position.schema.json)) +* [`fdc3.nothing`](ref/Nothing) ([schema](/schemas/next/nothing.schema.json)) +* [`fdc3.timerange`](ref/TimeRange) ([schema](/schemas/next/timerange.schema.json)) +* [`fdc3.valuation`](ref/Valuation) ([schema](/schemas/next/valuation.schema.json)) + +**Note:** The below examples show how the base context data interface can be used to define specific context data objects. ### Examples #### Contact + ```json { "type": "fdc3.contact", @@ -171,6 +190,7 @@ __Note:__ The below examples show how the base context data interface can be use ``` #### Email + ```json { "type": "fdc3.email", @@ -187,6 +207,7 @@ __Note:__ The below examples show how the base context data interface can be use ``` #### Instrument + ```json { "type" : "fdc3.instrument", @@ -231,4 +252,3 @@ e.g. as a JSON payload: }, } ``` - diff --git a/docs/fdc3-compliance.md b/docs/fdc3-compliance.md index 595b29d55..003766d5c 100644 --- a/docs/fdc3-compliance.md +++ b/docs/fdc3-compliance.md @@ -9,17 +9,18 @@ In general, the ratified FDC3 specs represent a lowest common denominator interf >6. **Guidance in the use of these Imperatives** > -> Imperatives of the type defined in this memo must be used with care -> and sparingly. In particular, they MUST only be used where it is -> actually required for interoperation or to limit behavior which has -> potential for causing harm (e.g., limiting retransmisssions) For -> example, they must not be used to try to impose a particular method -> on implementors where the method is not required for -> interoperability. +> Imperatives of the type defined in this memo must be used with care +> and sparingly. In particular, they MUST only be used where it is +> actually required for interoperation or to limit behavior which has +> potential for causing harm (e.g., limiting retransmisssions) For +> example, they must not be used to try to impose a particular method +> on implementors where the method is not required for +> interoperability. These rules would apply only to standards work within FDC3. Today, this covers the API, App Directory, Context Data, and Intents specifications. ## Personas + FDC3 implementors generally fall into 2 categories: platform providers, and application providers. A platform provider supplies an implementation(s) of the FDC3 APIs (The Desktop Agent API and Applkication Directory) for applications to use. An application provider is largely a downstream consumer of FDC3 standards. It MAY use the API, it MAY use Context Data, it MAY use Intents. Application providers are only required to comply with the standards they make use of. @@ -27,29 +28,25 @@ An application provider is largely a downstream consumer of FDC3 standards. It M Depending on persona, implementation compliance with FDC3 will mean different things. ### Platform Provider + For platform providers FDC3 compliance requires that they meet the requirements of the APIs that they implement: * [Desktop Agent API compliance requirements](api/spec#desktop-agent-api-standard-compliance). * [App Directory compliance requirements](app-directory/spec#app-directory-standard-compliance). ### Application Provider -For application providers FDC3 compliance requires that they interact with the FDC3 APIs as intended. Specifically: - -* If Intents are supported by the application: - * FDC3 defined standard intents used MUST meet the expected context and behavior defined for the intent. - * Where available, FDC3 defined standard intents SHOULD be used in preference to proprietary intents. - * Proprietary intents used SHOULD follow the recommended naming conventions in the specification. - * The application MUST use the `addIntentListener` API to set up a handler when it starts up. -* If context data sharing via channels is supported by the application: - * FDC3 defined standard context types used MUST meet the interface defined for that type of context data. - * Where available, FDC3 defined standard context types SHOULD used in preference to proprietary contexts. - * Proprietary context data types SHOULD follow any recommended naming and format conventions in the specification. - * Where Channels are supported or an app is intended to receive context from `fdc3.open` calls, the application MUST use the `addContextListener` API to set up appropriate handlers when it starts up (for User channels and for receiving context from `fdc3.open`) or when the channel is first created or retrieved (for App and Private channels). + +For application providers FDC3 compliance requires that they interact with the FDC3 APIs as intended and meet the requirements of the Intents and Context Data Standards. Specifically: + +* [Intents Standard compliance requirements](intents/spec#intents-standard-compliance) +* [Context Data Standard compliance requirements](context/spec#context-data-standard-compliance) ## Versioning + Typically, a Standard that has marketplace relevance is revised from time to time, to correct errors and/or to add functionality to support new use cases. Hence, there exist multiple versions of the standard. As FDC3 is a standards project, we don't follow semver, which is meant for libraries. We use the versioning scheme `.`, e.g. `1.1` or `2.3`. ## Deprecation Policy + Over time, it is not uncommon for certain things in a standard to be marked for removal in a future version, possibly being replaced by an alternative. That is, they are deprecated. Often, they are retained in the standard because of their widespread use, but their use in new projects is discouraged. FDC3 adopts the following deprecation policy: @@ -61,6 +58,7 @@ FDC3 adopts the following deprecation policy: 5. Breaking change should only be made in a major version of the Standard. ## Experimental Features + Occasionally, a change to FDC3 may be proposed where the design is tentative, and because of this, we need feedback from the community to finalise its inclusion in the Standard. In such cases, a feature may be designated as _experimental_ to indicate that its design may change in future and that it is exempted from the normal versioning and deprecation polices in order to facilitate that change. However, designating a feature as experimental is likely to reduce its uptake by the community, hence, this designation should be used sparingly. FDC3 adopts the following experimental features policy: @@ -73,6 +71,7 @@ FDC3 adopts the following experimental features policy: 6. The experimental designation may be removed from a feature in a minor version release (as this will be considered an additive change). ## Intellectual Property Claims + Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide diff --git a/docs/intents/spec.md b/docs/intents/spec.md index 5b2528b2e..6565d5114 100644 --- a/docs/intents/spec.md +++ b/docs/intents/spec.md @@ -22,6 +22,7 @@ Naming of Intents SHOULD follow the below guidelines: > **Note:** The naming guidelines should be adhered to when creating future Intents. This is to ensure they meet the criteria for addition to the FDC3 standard and to provide a consistent user experience. ### Characteristics + When creating Intents they should be: * Recognizable @@ -124,6 +125,25 @@ const intentsAndApps = await fdc3.findIntentsByContext({ }); ``` +## Intents Standard Compliance + +An FDC3 Standard compliant application that supports intents **MUST**: + +* Meet the expected context and behavior defined for any FDC3-defined standard intents used. +* Use the [`fdc3.addIntentListener`](api/ref/DesktopAgent#addintentlistener) API call to set up a handler for each supported intent as soon as possible when it starts up. This facilitates delivery of raised intents to the application. + +An FDC3 Standard compliant application that supports intents **SHOULD**: + +* Prefer FDC3-defined standard intents over proprietary intents, where a suitable standardized intent is available. +* Ensure that proprietary intents follow the recommended naming conventions in the specification. +* Apply [namespacing](#namespaces) to proprietary intent names, where it is necessary to avoid collision with those created by other applications. + +An FDC3 Standard compliant application that supports intents **MAY**: + +* Define proprietary intents to support use cases not currently supported via FDC3-defined standard intents. + +For more details on FDC3 Standards compliance (including the versioning, deprecation and experimental features policies) please see the [FDC3 Compliance page](../fdc3-compliance). + ## Standard Intents A list of standardized intents are defined in the following pages: @@ -148,7 +168,7 @@ A list of standardized intents are defined in the following pages: ## Using Intents without a context -As the [Desktop Agent API](../api/ref/DesktopAgent) and [App Directory](../app-directory/overview) both require a context to be specified wherever intents are used, using an intent without a context is achieved through the use of the explicit `null` context type `fdc3.nothing`. By using an explicit type to represent an absence of context we allow applications to declare their support for an absence of context. +As the [Desktop Agent API](../api/ref/DesktopAgent) and [App Directory](../app-directory/overview) both require a context to be specified wherever intents are used, using an intent without a context is achieved through the use of the explicit `null` context type [`fdc3.nothing`](../context/ref/Nothing). By using an explicit type to represent an absence of context we allow applications to declare their support for an absence of context. ```javascript const intentsAndApps = await fdc3.findIntentsByContext({ From fe7c5d2746f547fc0cbb96e3cdaedd6df2731d25 Mon Sep 17 00:00:00 2001 From: Kris West Date: Tue, 14 Jun 2022 15:09:04 +0100 Subject: [PATCH 3/6] markdownlint readme file to trigger preview deployment --- website/README.md | 35 ++++++++++++++++++++++++----------- 1 file changed, 24 insertions(+), 11 deletions(-) diff --git a/website/README.md b/website/README.md index 0ecf96b76..2a7390cc9 100644 --- a/website/README.md +++ b/website/README.md @@ -16,6 +16,7 @@ This website was created with [Docusaurus](https://docusaurus.io/). # Install dependencies $ yarn ``` + 2. Run your dev server: ```sh @@ -50,11 +51,11 @@ my-docusaurus/ # Versioning -Docusaurus uses the `docusaurus-version` command to create a snapshot of the documents in the `docs` folder with a particular version number, -and places them in the `versioned_docs/version-` folder. It also creates a `versioned_sidebars/version--sidebars.json` -to save the navigation structure at the time the snapshot was taken. +Docusaurus uses the `docusaurus-version` command to create a snapshot of the documents in the `docs` folder with a particular version number, +and places them in the `versioned_docs/version-` folder. It also creates a `versioned_sidebars/version--sidebars.json` +to save the navigation structure at the time the snapshot was taken. -See https://docusaurus.io/docs/en/versioning for more info. +See for more info. ## Versioning scheme @@ -67,22 +68,27 @@ Before creating a version, please make sure docs/fdc3-intro.md has been updated Since the website also uses some generated and copied static files (like schemas), extra tasks need to be performed as part of creating a new version. To create a new version, use this command: + ```sh VERSION= yarn run version ``` + e.g. + ```sh VERSION=1.2 yarn run version ``` The `VERSION` environment variable and `version` script are used to: -- Run the `docusaurus-version` command -- Copy schemas from the `/website/static/schemas/next` (which matches `master`) to `/website/static/schemas/` -- Copy the app-directory OpenAPI html file from `/website/pages/schemas/next` to `/website/pages/schemas/` -- Update paths referring to `/schemas/next` to point to `/schemas/` -- Update the version number in the app directory schema from `version: next` to `version: ` + +* Run the `docusaurus-version` command +* Copy schemas from the `/website/static/schemas/next` (which matches `master`) to `/website/static/schemas/` +* Copy the app-directory OpenAPI html file from `/website/pages/schemas/next` to `/website/pages/schemas/` +* Update paths referring to `/schemas/next` to point to `/schemas/` +* Update the version number in the app directory schema from `version: next` to `version: ` After a new version is created with the script, the following step also needs to be performed: + 1. Change `defaultVersionShown` in `siteConfig.js` to match the latest version (if the new version is now the latest version). 2. Change `versions.json` to have the version `stable` at the top, followed by the actual version numbers in descending order, e.g. `[stable, 1.3, 1.2, 1.1]`. (Docusaurus will add the new version number at the top of the array.) @@ -91,10 +97,13 @@ These steps are needed because we follow a workaround for an [issue with permane ## Delete a version To delete a version, use this command: + ```sh VERSION= yarn run version:delete ``` + e.g. + ```sh VERSION=1.2 yarn run version:delete ``` @@ -125,6 +134,7 @@ For more information about docs, click [here](https://docusaurus.io/docs/en/navi Edit blog posts by navigating to `website/blog` and editing the corresponding post: `website/blog/post-to-be-edited.md` + ```markdown --- id: post-needs-edit @@ -174,6 +184,7 @@ For more information about adding new docs, click [here](https://docusaurus.io/d 1. Make sure there is a header link to your blog in `website/siteConfig.js`: `website/siteConfig.js` + ```javascript headerLinks: [ ... @@ -204,6 +215,7 @@ For more information about blog posts, click [here](https://docusaurus.io/docs/e 1. Add links to docs, custom pages or external links by editing the headerLinks field of `website/siteConfig.js`: `website/siteConfig.js` + ```javascript { headerLinks: [ @@ -228,6 +240,7 @@ For more information about the navigation bar, click [here](https://docusaurus.i 1. If you want your page to show up in your navigation header, you will need to update `website/siteConfig.js` to add to the `headerLinks` element: `website/siteConfig.js` + ```javascript { headerLinks: [ @@ -243,7 +256,7 @@ For more information about custom pages, click [here](https://docusaurus.io/docs ## Custom CSS & Design Changes -1. Changing logos for the Header and Footer and Favicon are done in website/siteConfig.js file in the /* path to images for header/footer */ section +1. Changing logos for the Header and Footer and Favicon are done in website/siteConfig.js file in the /*path to images for header/footer*/ section Note: make sure that you add your new logos to the website/static/img folder first. @@ -253,7 +266,7 @@ Note: make sure that you add your new logos to the website/static/img folder fir 3. Change the background color and the background transparent image in the website/static/css/custom.css file. -Go to the section labeled: .homeContainer +Go to the section labeled: .homeContainer Change "background-image" - and insert your new background image file. Note - make sure you add your new background transparent image file to the website/static/img folder first. From 11ce6f0e2b44e9d23f572962f7deffedf5671284 Mon Sep 17 00:00:00 2001 From: Kris West Date: Thu, 23 Jun 2022 12:21:55 +0100 Subject: [PATCH 4/6] adding optional feature info in ImplementationMetadata to docs and compliance info --- docs/api/ref/DesktopAgent.md | 2 +- docs/api/ref/Metadata.md | 13 +++++++++++++ docs/api/spec.md | 1 + src/api/ImplementationMetadata.ts | 21 +++++---------------- 4 files changed, 20 insertions(+), 17 deletions(-) diff --git a/docs/api/ref/DesktopAgent.md b/docs/api/ref/DesktopAgent.md index 10c134a2d..988e6164b 100644 --- a/docs/api/ref/DesktopAgent.md +++ b/docs/api/ref/DesktopAgent.md @@ -454,7 +454,7 @@ let current = await fdc3.getCurrentChannel(); getInfo(): Promise; ``` -Retrieves information about the FDC3 Desktop Agent implementation, including the supported version of the FDC3 specification, the name of the provider of the implementation, its own version number and the metadata of the calling application according to the desktop agent. +Retrieves information about the FDC3 Desktop Agent implementation, including the supported version of the FDC3 specification, the name of the provider of the implementation, its own version number, details of whether optional API features are implemented and the metadata of the calling application according to the desktop agent. Returns an [`ImplementationMetadata`](Metadata#implementationmetadata) object. This metadata object can be used to vary the behavior of an application based on the version supported by the Desktop Agent and for logging purposes. diff --git a/docs/api/ref/Metadata.md b/docs/api/ref/Metadata.md index 336dafbae..780d5a40d 100644 --- a/docs/api/ref/Metadata.md +++ b/docs/api/ref/Metadata.md @@ -268,6 +268,19 @@ interface ImplementationMetadata { */ readonly providerVersion?: string; + /** Metadata indicating whether the Desktop Agent implements optional features of + * the Desktop Agent API. + */ + readonly optionalFeatures: { + /** Used to indicate whether the exposure of 'origninating app metadata' for + * context and intent messages is supported by the Desktop Agent.*/ + "OriginatingAppMetadata": boolean; + /** Used to indicate whether the optional `fdc3.joinUserChannel`, + * `fdc3.getCurrentChannel` and `fdc3.leaveCurrentChannel` are implemented by + * the Desktop Agent.*/ + "UserChannelMembershipAPIs": boolean; + }; + /** The calling application instance's own metadata, according to the * Desktop Agent (MUST include at least the `appId` and `instanceId`). */ diff --git a/docs/api/spec.md b/docs/api/spec.md index 2ed87b958..2f56b7d87 100644 --- a/docs/api/spec.md +++ b/docs/api/spec.md @@ -120,6 +120,7 @@ An FDC3 Standard compliant Desktop Agent implementation **MUST**: - [`raiseIntentForContext`](ref/DesktopAgent#raiseintentforcontext) - Provide an ID for each [`PrivateChannel`](ref/PrivateChannel) created via [`createPrivateChannel`](ref/DesktopAgent#createprivatechannel) and prevent them from being retrieved via [`getOrCreateChannel`](ref/DesktopAgent#getorcreatechannel) by ID. - Only require app directories that they connect to to have implemented only the minimum requirements specified in the [App Directory API Part](../app-directory/spec) of this Standard. +- 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. An FDC3 Standard compliant Desktop Agent implementation **SHOULD**: diff --git a/src/api/ImplementationMetadata.ts b/src/api/ImplementationMetadata.ts index f1312082d..3f428e787 100644 --- a/src/api/ImplementationMetadata.ts +++ b/src/api/ImplementationMetadata.ts @@ -5,22 +5,6 @@ import { AppMetadata } from './AppMetadata'; -/** - * Enumeration defining keys for optional API features that developers may need - * to know are supported or not supported in the Desktop Agent Implementation - * that they are working in. - */ -export enum OptionalFeatures { - /** Used to indicate whether the exposure of 'origninating app metadata' for - * context and intent messages is supported by the Desktop Agent.*/ - OriginatingAppMetadata = 'OriginatingAppMetadata', - - /** Used to indicate whether the optional `fdc3.joinUserChannel`, - * `fdc3.getCurrentChannel` and `fdc3.leaveCurrentChannel` are implemented by - * the Desktop Agent.*/ - UserChannelMembershipAPIs = 'UserChannelMembershipAPIs', -} - /** * Metadata relating to the FDC3 Desktop Agent implementation and its provider. */ @@ -40,7 +24,12 @@ export interface ImplementationMetadata { * the Desktop Agent API. */ readonly optionalFeatures: { + /** Used to indicate whether the exposure of 'origninating app metadata' for + * context and intent messages is supported by the Desktop Agent.*/ OriginatingAppMetadata: boolean; + /** Used to indicate whether the optional `fdc3.joinUserChannel`, + * `fdc3.getCurrentChannel` and `fdc3.leaveCurrentChannel` are implemented by + * the Desktop Agent.*/ UserChannelMembershipAPIs: boolean; }; From 6ca77c6c1aaec882a1ac1c0a09604fada0731394 Mon Sep 17 00:00:00 2001 From: Kris West Date: Thu, 23 Jun 2022 12:36:11 +0100 Subject: [PATCH 5/6] fix Methods.ts tests --- test/Methods.test.ts | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/test/Methods.test.ts b/test/Methods.test.ts index 62388aaad..991a75236 100644 --- a/test/Methods.test.ts +++ b/test/Methods.test.ts @@ -386,6 +386,10 @@ describe('test version comparison functions', () => { fdc3Version: '1.2', provider: 'test', appMetadata: { appId: 'dummy', name: 'dummy' }, + optionalFeatures: { + OriginatingAppMetadata: true, + UserChannelMembershipAPIs: false, + }, }; expect(versionIsAtLeast(metaOneTwo, '1.1')).toBe(true); expect(versionIsAtLeast(metaOneTwo, '1.2')).toBe(true); @@ -396,6 +400,10 @@ describe('test version comparison functions', () => { fdc3Version: '1.2.1', provider: 'test', appMetadata: { appId: 'dummy', name: 'dummy' }, + optionalFeatures: { + OriginatingAppMetadata: true, + UserChannelMembershipAPIs: false, + }, }; expect(versionIsAtLeast(metaOneTwoOne, '1.1')).toBe(true); expect(versionIsAtLeast(metaOneTwoOne, '1.2')).toBe(true); From b7bc50020a3facf0bd317410dd554b99cddc21b1 Mon Sep 17 00:00:00 2001 From: Kris West Date: Fri, 29 Jul 2022 11:29:25 +0100 Subject: [PATCH 6/6] Apply suggestions from code review Co-authored-by: Hugh Troeger --- docs/api/spec.md | 2 +- docs/app-directory/spec.md | 2 +- docs/context/spec.md | 4 ++-- docs/fdc3-compliance.md | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/api/spec.md b/docs/api/spec.md index 2f56b7d87..d7db2120f 100644 --- a/docs/api/spec.md +++ b/docs/api/spec.md @@ -98,7 +98,7 @@ An FDC3 Standard compliant Desktop Agent implementation **MUST**: - Provide the FDC3 API to web applications via a global accessible as [`window.fdc3`](#api-access). - Provide a global [`fdc3Ready`](#api-access) event that is fired when the API is ready for use. -- Provide a method of resolving ambiguous intents (i.e. those that might be resolved by multiple applications) or unspecified intents (calls to raiseIntentForCOntext that return multiple options), usch as a resolver UI. +- Provide a method of resolving ambiguous intents (i.e. those that might be resolved by multiple applications) or unspecified intents (calls to `raiseIntentForContext` that return multiple options), such as a resolver UI. - Intent resolution MUST take into account any specified input or return context types - Requests for resolution to apps returning a channel MUST include any apps that are registered as returning a channel with a specific type. - Return Errors from the [`ChannelError`](ref/Errors#channelerror), [`OpenError`](ref/Errors#openerror), [`ResolveError`](ref/Errors#resolveerror) and [`ResultError`](ref/Errors#resulterror) enumerations as appropriate. diff --git a/docs/app-directory/spec.md b/docs/app-directory/spec.md index 65fd136fd..8115fb575 100644 --- a/docs/app-directory/spec.md +++ b/docs/app-directory/spec.md @@ -27,7 +27,7 @@ An FDC3 Standard compliant App Directory implementation **MUST**: * `/v2/apps/{appId}` (GET) * Ensure that `appId` field values assigned to applications are unique within the directory. * Ensure that app directory records served meet the minimum requirements specified in the [app directory OpenAPI specification](/schemas/next/app-directory#tag/Application/paths/~1v2~1apps~1{appId}/get) -* Support retrieval of app directory records via either the raw appId (e.g. `myAppId`) or fully-qualified appId (e.g. `myAppId@host.domain.com`) as defined in the [app directory overview](overview#shrinking-the-uri). +* Support retrieval of app directory records via either the raw `appId` (e.g. `myAppId`) or fully-qualified appId (e.g. `myAppId@host.domain.com`) as defined in the [app directory overview](overview#shrinking-the-uri). An FDC3 Standard compliant App Directory implementation **SHOULD**: diff --git a/docs/context/spec.md b/docs/context/spec.md index 477796af6..92aab3692 100644 --- a/docs/context/spec.md +++ b/docs/context/spec.md @@ -144,8 +144,8 @@ An FDC3 Standard compliant application that supports the use of context data **M An FDC3 Standard compliant application that supports the use of context data **SHOULD**: -* Prefer FDC3-defined standard context types over proprietary contexts, where a suitable FDC3-defined stanrd context type is available. -* Ensure that any proprietary context data types fefined follow any the recommended [namespacing](#namespacing) and [field type conventions](#field-type-conventions) in the specification. +* Prefer FDC3-defined standard context types over proprietary contexts, where a suitable FDC3-defined standard context type is available. +* Ensure that any proprietary context data types defined follow any the recommended [namespacing](#namespacing) and [field type conventions](#field-type-conventions) in the specification. An FDC3 Standard compliant application that supports the use of context data **MAY**: diff --git a/docs/fdc3-compliance.md b/docs/fdc3-compliance.md index 003766d5c..380251017 100644 --- a/docs/fdc3-compliance.md +++ b/docs/fdc3-compliance.md @@ -21,7 +21,7 @@ These rules would apply only to standards work within FDC3. Today, this covers t ## Personas -FDC3 implementors generally fall into 2 categories: platform providers, and application providers. A platform provider supplies an implementation(s) of the FDC3 APIs (The Desktop Agent API and Applkication Directory) for applications to use. +FDC3 implementors generally fall into 2 categories: platform providers, and application providers. A platform provider supplies an implementation(s) of the FDC3 APIs (The Desktop Agent API and Application Directory) for applications to use. An application provider is largely a downstream consumer of FDC3 standards. It MAY use the API, it MAY use Context Data, it MAY use Intents. Application providers are only required to comply with the standards they make use of.