From 380506cc6789157ba5625c1bac8b09730ae580d5 Mon Sep 17 00:00:00 2001 From: Kris West Date: Fri, 6 May 2022 18:52:10 +0100 Subject: [PATCH 1/3] adding interopUse field to appD app record schema --- CHANGELOG.md | 1 + src/app-directory/specification/appd.yaml | 69 ++++++++++++++++++- .../static/schemas/next/app-directory.yaml | 69 ++++++++++++++++++- 3 files changed, 135 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 889ad023f..54127f9af 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -27,6 +27,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). * Added `lang` field to AppD application records to specify the primary language of an app and its appD record. ([#670](https://github.com/finos/FDC3/pull/670)) * Added `localizedVersions` field to AppD application records to support localized versions of descriptive fields in the app records and alternative launch details for localized versions of the applications themselves. ([#670](https://github.com/finos/FDC3/pull/670)) * Added `categories` field and recommended categories list to AppD application records to enable category based browsing of AppDs ([#673](https://github.com/finos/FDC3/pull/673)) +* Added `interopUse` field to AppD application records to description of an apps use of FDC3 and enable search for apps that 'interoperate' with a selected app ([#697](https://github.com/finos/FDC3/pull/697)) ### Changed * Consolidated `Listener` documentation with other types ([#404](https://github.com/finos/FDC3/pull/404)) diff --git a/src/app-directory/specification/appd.yaml b/src/app-directory/specification/appd.yaml index 74edb2c82..0a4658772 100644 --- a/src/app-directory/specification/appd.yaml +++ b/src/app-directory/specification/appd.yaml @@ -578,12 +578,13 @@ components: intents: type: array description: > - The list of intents implemented by the Application as defined by - https://github.com/FDC3/Intents/blob/master/src/Intent.yaml + The list of intents that the Application listens for via `fdc3.addIntentListener()` items: $ref: '#/components/schemas/Intent' hostManifests: $ref: '#/components/schemas/HostManifests' + interopUse: + $ref: '#/components/schemas/InteropUse' Application: description: > Defines an application retrieved from an FDC3 App Directory, which can @@ -877,6 +878,70 @@ components: additionalProperties: x-additionalPropertiesName: Language tag $ref: '#/components/schemas/BaseApplication' # due to a bug in redoc this may display as a recursive definition, it is not. It will render correctly in swagger and other OpenAPI parsers. + InteropUse: + type: object + description: >- + Optional metadata that describes how the application uses FDC3 APIs (beyond intents it listens for, + which are defined under the `intents` element). This metadata may be used, for example in an app catalog UI, + to find apps that 'interoperate with' other apps or to advertise app channels or intents that the application + use to other app developers and desktop assemblers. + The presence of this metadata does not imply any form of contract with the DesktopAgent and actual FDC3 API + use MAY vary from what is described. + properties: + raisesIntents: + type: object + description: Intents that are raised by the application and contexts they are raised with. + additionalProperties: + x-additionalPropertiesName: Intent name + type: array + description: Context types that the intent may be raised with + items: + type: string + raisesContexts: + type: array + description: >- + Contexts that are raised via `raiseIntentForContext` or `findIntentForContext`, which allow + the user to select an intent from those that are available via the Desktop Agent. + items: + type: string + userChannels: + type: object + description: Describes the application's use of context types on User Channels + properties: + broadcast: + type: array + description: Context types that are broadcast by the application + items: + type: string + listen: + type: array + description: Context types that the application listens for + items: + type: string + appChannels: + type: array + description: Describes the application's use of App Channels + items: + type: object + required: + - name + properties: + name: + type: string + description: The name of the App Channel + description: + type: string + description: A description of how the channel is used + broadcast: + type: array + description: Context types that are broadcast by the application on the channel + items: + type: string + listen: + type: array + description: Context types that the application listens for on the channel + items: + type: string examples: FDC3WorkbenchAppDefinition: value: diff --git a/website/static/schemas/next/app-directory.yaml b/website/static/schemas/next/app-directory.yaml index 74edb2c82..0a4658772 100644 --- a/website/static/schemas/next/app-directory.yaml +++ b/website/static/schemas/next/app-directory.yaml @@ -578,12 +578,13 @@ components: intents: type: array description: > - The list of intents implemented by the Application as defined by - https://github.com/FDC3/Intents/blob/master/src/Intent.yaml + The list of intents that the Application listens for via `fdc3.addIntentListener()` items: $ref: '#/components/schemas/Intent' hostManifests: $ref: '#/components/schemas/HostManifests' + interopUse: + $ref: '#/components/schemas/InteropUse' Application: description: > Defines an application retrieved from an FDC3 App Directory, which can @@ -877,6 +878,70 @@ components: additionalProperties: x-additionalPropertiesName: Language tag $ref: '#/components/schemas/BaseApplication' # due to a bug in redoc this may display as a recursive definition, it is not. It will render correctly in swagger and other OpenAPI parsers. + InteropUse: + type: object + description: >- + Optional metadata that describes how the application uses FDC3 APIs (beyond intents it listens for, + which are defined under the `intents` element). This metadata may be used, for example in an app catalog UI, + to find apps that 'interoperate with' other apps or to advertise app channels or intents that the application + use to other app developers and desktop assemblers. + The presence of this metadata does not imply any form of contract with the DesktopAgent and actual FDC3 API + use MAY vary from what is described. + properties: + raisesIntents: + type: object + description: Intents that are raised by the application and contexts they are raised with. + additionalProperties: + x-additionalPropertiesName: Intent name + type: array + description: Context types that the intent may be raised with + items: + type: string + raisesContexts: + type: array + description: >- + Contexts that are raised via `raiseIntentForContext` or `findIntentForContext`, which allow + the user to select an intent from those that are available via the Desktop Agent. + items: + type: string + userChannels: + type: object + description: Describes the application's use of context types on User Channels + properties: + broadcast: + type: array + description: Context types that are broadcast by the application + items: + type: string + listen: + type: array + description: Context types that the application listens for + items: + type: string + appChannels: + type: array + description: Describes the application's use of App Channels + items: + type: object + required: + - name + properties: + name: + type: string + description: The name of the App Channel + description: + type: string + description: A description of how the channel is used + broadcast: + type: array + description: Context types that are broadcast by the application on the channel + items: + type: string + listen: + type: array + description: Context types that the application listens for on the channel + items: + type: string examples: FDC3WorkbenchAppDefinition: value: From 73fcbc2ea68e67c442df56f98b1e5204b0bacc74 Mon Sep 17 00:00:00 2001 From: Kris West Date: Fri, 6 May 2022 18:53:58 +0100 Subject: [PATCH 2/3] changelog --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 54127f9af..cd2638dc9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -27,7 +27,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). * Added `lang` field to AppD application records to specify the primary language of an app and its appD record. ([#670](https://github.com/finos/FDC3/pull/670)) * Added `localizedVersions` field to AppD application records to support localized versions of descriptive fields in the app records and alternative launch details for localized versions of the applications themselves. ([#670](https://github.com/finos/FDC3/pull/670)) * Added `categories` field and recommended categories list to AppD application records to enable category based browsing of AppDs ([#673](https://github.com/finos/FDC3/pull/673)) -* Added `interopUse` field to AppD application records to description of an apps use of FDC3 and enable search for apps that 'interoperate' with a selected app ([#697](https://github.com/finos/FDC3/pull/697)) +* Added `interopUse` field to AppD application records to describe an app's use of FDC3 and enable search for apps that 'interoperate' with a selected app ([#697](https://github.com/finos/FDC3/pull/697)) ### Changed * Consolidated `Listener` documentation with other types ([#404](https://github.com/finos/FDC3/pull/404)) From aaad6d5c42efe12e77df1ef9190372f87721b7ce Mon Sep 17 00:00:00 2001 From: Kris West Date: Fri, 20 May 2022 17:56:34 +0100 Subject: [PATCH 3/3] move new elements to top-level of schema --- src/app-directory/specification/appd.yaml | 141 +++++++++-------- .../static/schemas/next/app-directory.yaml | 145 ++++++++++-------- 2 files changed, 164 insertions(+), 122 deletions(-) diff --git a/src/app-directory/specification/appd.yaml b/src/app-directory/specification/appd.yaml index 7c0c1fb8f..559860f52 100644 --- a/src/app-directory/specification/appd.yaml +++ b/src/app-directory/specification/appd.yaml @@ -428,8 +428,14 @@ components: $ref: '#/components/schemas/Intent' hostManifests: $ref: '#/components/schemas/HostManifests' - interopUse: - $ref: '#/components/schemas/InteropUse' + raiseIntent: + $ref: '#/components/schemas/RaiseIntent' + raiseIntentForContext: + $ref: '#/components/schemas/RaiseIntentForContext' + userChannels: + $ref: '#/components/schemas/UserChannels' + appChannels: + $ref: '#/components/schemas/AppChannels' Application: description: > Defines an application retrieved from an FDC3 App Directory, which can @@ -543,9 +549,13 @@ components: $ref: '#/components/schemas/NameValuePair' intents: type: array - description: > - The list of intents implemented by the Application as defined by + description: >- + The list of intents that the Application listens for and resolves as defined by https://github.com/FDC3/Intents/blob/master/src/Intent.yaml + Primarily used to implement intent resolution in a Desktop Agent, but may also be used, + for example in an app catalog UI, to find apps that 'interoperate with' other apps. + An Application MUST use the Desktop Agent's `addIntentListener` API to add an intent listener + for each intent listed here as soon as possible after it starts up. items: $ref: '#/components/schemas/IntentV1' AllApplicationsResponse: @@ -785,70 +795,81 @@ components: additionalProperties: x-additionalPropertiesName: Language tag $ref: '#/components/schemas/BaseApplication' # due to a bug in redoc this may display as a recursive definition, it is not. It will render correctly in swagger and other OpenAPI parsers. - InteropUse: + RaiseIntent: type: object description: >- - Optional metadata that describes how the application uses FDC3 APIs (beyond intents it listens for, - which are defined under the `intents` element). This metadata may be used, for example in an app catalog UI, - to find apps that 'interoperate with' other apps or to advertise app channels or intents that the application - use to other app developers and desktop assemblers. - The presence of this metadata does not imply any form of contract with the DesktopAgent and actual FDC3 API - use MAY vary from what is described. + Optional metadata that describes which Intents are raised by the application and context types they are + raised with. + This metadata may be used, for example in an app catalog UI, to find apps that 'interoperate with' other + apps or to advertise intents that the application uses. + The presence of this metadata does not imply any form of contract with the DesktopAgent and actual usage + MAY vary from what is described. + additionalProperties: + x-additionalPropertiesName: Intent name + type: array + description: Context types that the intent may be raised with + items: + type: string + RaiseIntentForContext: + type: array + description: >- + Contexts that are raised via `raiseIntentForContext` or `findIntentForContext`, which allow the user to + select an intent from those that are available via the Desktop Agent. + This metadata may be used, for example in an app catalog UI, to find apps that 'interoperate with' other + apps or to advertise intents that the application uses. + The presence of this metadata does not imply any form of contract with the DesktopAgent and actual usage + MAY vary from what is described. + additionalProperties: + items: + type: string + UserChannels: + type: object + description: >- + Describes the application's use of context types on User Channels. + This metadata may be used, for example in an app catalog UI, to find apps that 'interoperate with' other + apps or to advertise contexts that the application uses. + The presence of this metadata does not imply any form of contract with the DesktopAgent and actual usage + MAY vary from what is described. properties: - raisesIntents: - type: object - description: Intents that are raised by the application and contexts they are raised with. - additionalProperties: - x-additionalPropertiesName: Intent name - type: array - description: Context types that the intent may be raised with - items: - type: string - raisesContexts: + broadcast: type: array - description: >- - Contexts that are raised via `raiseIntentForContext` or `findIntentForContext`, which allow - the user to select an intent from those that are available via the Desktop Agent. + description: Context types that are broadcast by the application items: type: string - userChannels: - type: object - description: Describes the application's use of context types on User Channels - properties: - broadcast: - type: array - description: Context types that are broadcast by the application - items: - type: string - listen: - type: array - description: Context types that the application listens for - items: - type: string - appChannels: + listen: type: array - description: Describes the application's use of App Channels + description: Context types that the application listens for items: - type: object - required: - - name - properties: - name: - type: string - description: The name of the App Channel - description: - type: string - description: A description of how the channel is used - broadcast: - type: array - description: Context types that are broadcast by the application on the channel - items: - type: string - listen: - type: array - description: Context types that the application listens for on the channel - items: - type: string + type: string + AppChannels: + type: array + description: >- + Describes the application's use of App Channels. + This metadata may be used, for example in an app catalog UI, to find apps that 'interoperate with' other + apps or to advertise App channels and contexts that the application creates and uses. + The presence of this metadata does not imply any form of contract with the DesktopAgent and actual usage + MAY vary from what is described. + items: + type: object + required: + - name + properties: + name: + type: string + description: The name of the App Channel + description: + type: string + description: A description of how the channel is used + broadcast: + type: array + description: Context types that are broadcast by the application on the channel + items: + type: string + listen: + type: array + description: Context types that the application listens for on the channel + items: + type: string examples: FDC3WorkbenchAppDefinition: value: diff --git a/website/static/schemas/next/app-directory.yaml b/website/static/schemas/next/app-directory.yaml index db3ff3060..559860f52 100644 --- a/website/static/schemas/next/app-directory.yaml +++ b/website/static/schemas/next/app-directory.yaml @@ -428,8 +428,14 @@ components: $ref: '#/components/schemas/Intent' hostManifests: $ref: '#/components/schemas/HostManifests' - interopUse: - $ref: '#/components/schemas/InteropUse' + raiseIntent: + $ref: '#/components/schemas/RaiseIntent' + raiseIntentForContext: + $ref: '#/components/schemas/RaiseIntentForContext' + userChannels: + $ref: '#/components/schemas/UserChannels' + appChannels: + $ref: '#/components/schemas/AppChannels' Application: description: > Defines an application retrieved from an FDC3 App Directory, which can @@ -543,9 +549,13 @@ components: $ref: '#/components/schemas/NameValuePair' intents: type: array - description: > - The list of intents implemented by the Application as defined by + description: >- + The list of intents that the Application listens for and resolves as defined by https://github.com/FDC3/Intents/blob/master/src/Intent.yaml + Primarily used to implement intent resolution in a Desktop Agent, but may also be used, + for example in an app catalog UI, to find apps that 'interoperate with' other apps. + An Application MUST use the Desktop Agent's `addIntentListener` API to add an intent listener + for each intent listed here as soon as possible after it starts up. items: $ref: '#/components/schemas/IntentV1' AllApplicationsResponse: @@ -643,7 +653,7 @@ components: type: string description: >- A comma separated list of the types of contexts the intent offered by the application can process, - where the first part of the context type is the namespace e.g."fdc3.contact", "org.symphony.contact" + where the first part of the context type is the namespace e.g."fdc3.contact, org.symphony.contact" resultType: type: string description: >- @@ -704,7 +714,7 @@ components: LaunchDetails: description: >- 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 + vendor-agnostic and MAY be duplicated or overridden by details provided in the hostManifests object for a specific host. oneOf: - $ref: '#/components/schemas/WebAppDetails' @@ -785,70 +795,81 @@ components: additionalProperties: x-additionalPropertiesName: Language tag $ref: '#/components/schemas/BaseApplication' # due to a bug in redoc this may display as a recursive definition, it is not. It will render correctly in swagger and other OpenAPI parsers. - InteropUse: + RaiseIntent: type: object description: >- - Optional metadata that describes how the application uses FDC3 APIs (beyond intents it listens for, - which are defined under the `intents` element). This metadata may be used, for example in an app catalog UI, - to find apps that 'interoperate with' other apps or to advertise app channels or intents that the application - use to other app developers and desktop assemblers. - The presence of this metadata does not imply any form of contract with the DesktopAgent and actual FDC3 API - use MAY vary from what is described. + Optional metadata that describes which Intents are raised by the application and context types they are + raised with. + This metadata may be used, for example in an app catalog UI, to find apps that 'interoperate with' other + apps or to advertise intents that the application uses. + The presence of this metadata does not imply any form of contract with the DesktopAgent and actual usage + MAY vary from what is described. + additionalProperties: + x-additionalPropertiesName: Intent name + type: array + description: Context types that the intent may be raised with + items: + type: string + RaiseIntentForContext: + type: array + description: >- + Contexts that are raised via `raiseIntentForContext` or `findIntentForContext`, which allow the user to + select an intent from those that are available via the Desktop Agent. + This metadata may be used, for example in an app catalog UI, to find apps that 'interoperate with' other + apps or to advertise intents that the application uses. + The presence of this metadata does not imply any form of contract with the DesktopAgent and actual usage + MAY vary from what is described. + additionalProperties: + items: + type: string + UserChannels: + type: object + description: >- + Describes the application's use of context types on User Channels. + This metadata may be used, for example in an app catalog UI, to find apps that 'interoperate with' other + apps or to advertise contexts that the application uses. + The presence of this metadata does not imply any form of contract with the DesktopAgent and actual usage + MAY vary from what is described. properties: - raisesIntents: - type: object - description: Intents that are raised by the application and contexts they are raised with. - additionalProperties: - x-additionalPropertiesName: Intent name - type: array - description: Context types that the intent may be raised with - items: - type: string - raisesContexts: + broadcast: type: array - description: >- - Contexts that are raised via `raiseIntentForContext` or `findIntentForContext`, which allow - the user to select an intent from those that are available via the Desktop Agent. + description: Context types that are broadcast by the application items: type: string - userChannels: - type: object - description: Describes the application's use of context types on User Channels - properties: - broadcast: - type: array - description: Context types that are broadcast by the application - items: - type: string - listen: - type: array - description: Context types that the application listens for - items: - type: string - appChannels: + listen: type: array - description: Describes the application's use of App Channels + description: Context types that the application listens for items: - type: object - required: - - name - properties: - name: - type: string - description: The name of the App Channel - description: - type: string - description: A description of how the channel is used - broadcast: - type: array - description: Context types that are broadcast by the application on the channel - items: - type: string - listen: - type: array - description: Context types that the application listens for on the channel - items: - type: string + type: string + AppChannels: + type: array + description: >- + Describes the application's use of App Channels. + This metadata may be used, for example in an app catalog UI, to find apps that 'interoperate with' other + apps or to advertise App channels and contexts that the application creates and uses. + The presence of this metadata does not imply any form of contract with the DesktopAgent and actual usage + MAY vary from what is described. + items: + type: object + required: + - name + properties: + name: + type: string + description: The name of the App Channel + description: + type: string + description: A description of how the channel is used + broadcast: + type: array + description: Context types that are broadcast by the application on the channel + items: + type: string + listen: + type: array + description: Context types that the application listens for on the channel + items: + type: string examples: FDC3WorkbenchAppDefinition: value: