562 AppD vendor agnostic native apps

CHANGELOG.md

@@ -26,6 +26,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 * Added a `moreInfo` URL field to AppD application records to enable linking to a web page with more information on an app ([#669](https://github.com/finos/FDC3/pull/669))
 * 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 `type` and `details` elements to AppD application records to support vendor-agnostic launch details for both web and native apps ([#671](https://github.com/finos/FDC3/pull/671))
 
 ### Changed
 * Consolidated `Listener` documentation with other types ([#404](https://github.com/finos/FDC3/pull/404))

src/app-directory/specification/appd.yaml

@@ -425,11 +425,7 @@ components:
         type:
           $ref: '#/components/schemas/Type'
         details:
-          description: >-
-            The type specific details of the application. Currently only the "browser" type is standardized.
-            "host" type applications should use the hostManifest's object for all application details.
-          oneOf:
-            - $ref: '#/components/schemas/BrowserDetails'
+          $ref: '#/components/schemas/LaunchDetails'
         version:
           type: string
           description: >-
@@ -508,10 +504,11 @@ components:
         Launching typically means running for a user on a desktop.
         The details around 'launching' including who or what might do it, and how the launch action is initiated are
         discussed elsewhere in the FDC3 App Directory spec.
-      required:            # details are not required as the host type applications use the hostsManifests mapping instead
+      required:
         - appId
         - name
         - type
+        - details
       allOf:
         - $ref: '#/components/schemas/BaseApplication'
         - type: object
@@ -736,14 +733,71 @@ components:
             particular desktop agent.
     Type:
       type: string
-      description: >-
-        Enumeration describing the supported application types. Currently only the browser application type is officially supported.
-        The host application type allows for host specific application types (e.g. exe, workspaces, citrix, etc.).
+      description: |
+        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 Citrix
+        - `onlineNative`: 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.
       enum:
-        - browser
-        - host
-    BrowserDetails:
-      description: Properties common to all browser applications.
+        - web
+        - native
+        - citrix
+        - onlineNative
+        - other
+    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 
+        object for a specific host.
+      oneOf:
+        - $ref: '#/components/schemas/WebAppDetails'
+        - $ref: '#/components/schemas/NativeAppDetails'
+        - $ref: '#/components/schemas/CitrixAppDetails'
+        - $ref: '#/components/schemas/OnlineNativeAppDetails'
+        - $ref: '#/components/schemas/OtherAppDetails'
+    WebAppDetails:
+      description: 'Properties used to launch apps with `type: web`.'
+      required:
+        - url
+      properties:
+        url:
+          type: string
+          formt: uri
+          description: Application start URL.
+      additionalProperties: false
+    NativeAppDetails:
+      description: 'Properties used to launch apps with `type: native` that are already installed on the device.'
+      required:
+        - path
+      properties:
+        path:
+          type: string
+          description: The path on disk from which the application is launched.
+        arguments:
+          type: string
+          description: Arguments that must be passed on the command line to launch the app in the expected configuration.
+      additionalProperties: false
+    CitrixAppDetails:
+      description: 'Properties used to launch apps virtualized apps with `type: citrix`.'
+      required:
+        - alias
+      properties:
+        alias:
+          type: string
+          description: The Citrix alias / name of the virtual app (passed to the Citrix SelfService qlaunch parameter).
+        arguments:
+          type: string
+          description: Arguments that must be passed on the command line to launch the app in the expected configuration.
+      additionalProperties: false
+    OnlineNativeAppDetails:
+      description: 'Properties used to launch a native apps with `type: onelineNative` that have an online launcher, e.g. online ClickOnce app deployments.'
       required:
         - url
       properties:
@@ -752,14 +806,18 @@ components:
           format: uri
           description: Application URL.
       additionalProperties: false
+    OtherAppDetails:
+      description: 'Apps with `type: other` are defined by a hostManifest and do not require other details.'
+      additionalProperties: false
     HostManifests:
       type: object
       description: >-
-        A mapping from host string to a host-specific application manifest object or URI
-        from which that manifest can be retrieved. The manifest should provide all details required to
-        launch and use the application within the specified host.
+        A mapping from host name to a host-specific application manifest object or URI
+        from which that manifest can be retrieved. The manifest should provide details required to
+        launch and use the application within the specified host. The manifest _MAY_ duplicate or 
+        override information provided in the `details` field.
       additionalProperties:
-        x-additionalPropertiesName: Host
+        x-additionalPropertiesName: Host name
         oneOf:
           - type: string   # URI pointing to a JSON containing all host specific properties
             format: uri

website/static/schemas/next/app-directory.yaml

@@ -425,11 +425,7 @@ components:
         type:
           $ref: '#/components/schemas/Type'
         details:
-          description: >-
-            The type specific details of the application. Currently only the "browser" type is standardized.
-            "host" type applications should use the hostManifest's object for all application details.
-          oneOf:
-            - $ref: '#/components/schemas/BrowserDetails'
+          $ref: '#/components/schemas/LaunchDetails'
         version:
           type: string
           description: >-
@@ -508,10 +504,11 @@ components:
         Launching typically means running for a user on a desktop.
         The details around 'launching' including who or what might do it, and how the launch action is initiated are
         discussed elsewhere in the FDC3 App Directory spec.
-      required:            # details are not required as the host type applications use the hostsManifests mapping instead
+      required:
         - appId
         - name
         - type
+        - details
       allOf:
         - $ref: '#/components/schemas/BaseApplication'
         - type: object
@@ -736,14 +733,71 @@ components:
             particular desktop agent.
     Type:
       type: string
-      description: >-
-        Enumeration describing the supported application types. Currently only the browser application type is officially supported.
-        The host application type allows for host specific application types (e.g. exe, workspaces, citrix, etc.).
+      description: |
+        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 Citrix
+        - `onlineNative`: 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.
       enum:
-        - browser
-        - host
-    BrowserDetails:
-      description: Properties common to all browser applications.
+        - web
+        - native
+        - citrix
+        - onlineNative
+        - other
+    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 
+        object for a specific host.
+      oneOf:
+        - $ref: '#/components/schemas/WebAppDetails'
+        - $ref: '#/components/schemas/NativeAppDetails'
+        - $ref: '#/components/schemas/CitrixAppDetails'
+        - $ref: '#/components/schemas/OnlineNativeAppDetails'
+        - $ref: '#/components/schemas/OtherAppDetails'
+    WebAppDetails:
+      description: 'Properties used to launch apps with `type: web`.'
+      required:
+        - url
+      properties:
+        url:
+          type: string
+          formt: uri
+          description: Application start URL.
+      additionalProperties: false
+    NativeAppDetails:
+      description: 'Properties used to launch apps with `type: native` that are already installed on the device.'
+      required:
+        - path
+      properties:
+        path:
+          type: string
+          description: The path on disk from which the application is launched.
+        arguments:
+          type: string
+          description: Arguments that must be passed on the command line to launch the app in the expected configuration.
+      additionalProperties: false
+    CitrixAppDetails:
+      description: 'Properties used to launch apps virtualized apps with `type: citrix`.'
+      required:
+        - alias
+      properties:
+        alias:
+          type: string
+          description: The Citrix alias / name of the virtual app (passed to the Citrix SelfService qlaunch parameter).
+        arguments:
+          type: string
+          description: Arguments that must be passed on the command line to launch the app in the expected configuration.
+      additionalProperties: false
+    OnlineNativeAppDetails:
+      description: 'Properties used to launch a native apps with `type: onelineNative` that have an online launcher, e.g. online ClickOnce app deployments.'
       required:
         - url
       properties:
@@ -752,14 +806,18 @@ components:
           format: uri
           description: Application URL.
       additionalProperties: false
+    OtherAppDetails:
+      description: 'Apps with `type: other` are defined by a hostManifest and do not require other details.'
+      additionalProperties: false
     HostManifests:
       type: object
       description: >-
-        A mapping from host string to a host-specific application manifest object or URI
-        from which that manifest can be retrieved. The manifest should provide all details required to
-        launch and use the application within the specified host.
+        A mapping from host name to a host-specific application manifest object or URI
+        from which that manifest can be retrieved. The manifest should provide details required to
+        launch and use the application within the specified host. The manifest _MAY_ duplicate or 
+        override information provided in the `details` field.
       additionalProperties:
-        x-additionalPropertiesName: Host
+        x-additionalPropertiesName: Host name
         oneOf:
           - type: string   # URI pointing to a JSON containing all host specific properties
             format: uri
@@ -776,7 +834,7 @@ components:
         The keys to this object should be language tags as defined by IETF RFC 5646, e.g. en, en-GB or fr-FR.
       additionalProperties:
         x-additionalPropertiesName: Language tag
-        $ref: '#/components/schemas/BaseApplication'
+        $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.
   examples:
     FDC3WorkbenchAppDefinition:
       value: