Merge pull request #437 from finos/feat/update-application-schema

Update the Application schema

CHANGELOG.md

@@ -45,10 +45,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 * ES6 functions for `getInfo()` and `raiseIntentForContext()` ([#268](https://github.com/finos/FDC3/pull/268), [#324](https://github.com/finos/FDC3/pull/324))
 * `fdc3Ready()` utility function that wraps checks for the window.fdc3 global object and new `fdc3Ready` event ([#360](https://github.com/finos/FDC3/pull/360))
 * `compareVersionNumbers()` and `versionIsAtLeast()` utility functions to complement `getInfo()` ([#324](https://github.com/finos/FDC3/pull/324))
+* An example application definition ([#437](https://github.com/finos/FDC3/pull/437)
+* A test environment for the app directory specification and the example application definition ([#437](https://github.com/finos/FDC3/pull/437)
 
 ### Changed
 * `addContextListener(contextType, handler)` now supports passing `null` as the context type ([#329](https://github.com/finos/FDC3/pull/329))
 * All other API type changes and additions from the [FDC3 Standard 1.2](https://github.com/finos/FDC3/releases/tag/v1.2) release
+* The Application schema by removing the `manifestType` and `manifest` properties, introducing new `type` (required), `details` and `hostManifests` properties ([#437](https://github.com/finos/FDC3/pull/437)
 
 ### Deprecated
 * `addContextListener(handler)` ([#329](https://github.com/finos/FDC3/pull/329))

src/app-directory/specification/appd.yaml

@@ -115,17 +115,6 @@ paths:
 
  The same appName could occur in other directories. We are not
  currently specifying app name conventions in the document.
- - in: query
- name: manifest
- schema:
- type: string
- required: false
- description: >
- URI or full JSON of the application manifest providing all details related to launch
- and use requirements as described by the vendor.
-
- The format of this manifest is vendor specific, but can be identified by
- the manifestType attribute.
  - in: query
  name: version
  schema:
@@ -204,7 +193,7 @@ paths:
  $ref: '#/components/schemas/ErrorDTO'
  tags:
  - Application
- 
+
 servers:
  - url: /appd
 components:
@@ -227,14 +216,13 @@ components:
  Defines an application retrieved from an FDC3 App Directory, which can
  then be launched.
 
- Launching typically means running for a user on a desktop. 
+ 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:
+ required: # details are not required as the host type applications use the hostsManifests mapping instead
  - appId
  - name
- - manifest
- - manifestType
+ - type
  properties:
  appId:
  type: string
@@ -252,19 +240,14 @@ components:
 
  The same appName could occur in other directories. We are not
  currently specifying app name conventions in the document.
- manifest:
- type: string
- description: >
- URI or full JSON of the application manifest providing all details related to launch
- and use requirements as described by the vendor.
-
- The format of this manifest is vendor specific, but can be identified by
- the manifestType attribute.
- manifestType:
- type: string
- description: >
- The manifest type which relates to the format and structure of the manifest content.
- The definition is based on the vendor specific format and definition outside of this specification.
+ 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'
  version:
  type: string
  description: >-
@@ -323,6 +306,8 @@ components:
  https://github.com/FDC3/Intents/blob/master/src/Intent.yaml
  items:
  $ref: '#/components/schemas/Intent'
+ hostManifests:
+ $ref: '#/components/schemas/HostManifest'
  ApplicationSearchResponse:
  properties:
  applications:
@@ -380,10 +365,37 @@ components:
  items:
  type: string
  description: >-
- A comma sepaarted list of the types of contexts the intent offered by the application can process. 
+ A comma separated list of context-types that the application's intent(s) can process.
  where the first part of the context type is the namespace e.g."fdc3.contact, org.symphony.contact"
  customConfig:
  type: object
  description: >-
  Custom configuration for the intent that may be required for a
  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.).
+ enum:
+ - browser
+ - host
+ BrowserDetails:
+ description: Properties common to all browser applications.
+ required:
+ - url
+ properties:
+ url:
+ type: string
+ description: Application URL.
+ additionalProperties: false
+ HostManifest:
+ 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.
+ additionalProperties:
+ oneOf:
+ - type: string # URI pointing to a JSON containing all host specific properties
+ - type: object # object containing all host specific properties

src/app-directory/specification/examples/application/fdc3-workbench.js

@@ -0,0 +1,82 @@
+module.exports = {
+ "appId": "fdc3-workbench",
+ "name": "fdc3-workbench",
+ "title": "FDC3 Workbench",
+ "description": "Development and test tool for FDC3 desktop agents and apps",
+ "version": "1.0.0",
+ "tooltip": "FDC3 Workbench",
+ "icons": [
+ {
+ "url": "http://fdc3.finos.org/toolbox/fdc3-workbench/fdc3-icon-256.png"
+ }
+ ],
+ "images": [
+ {
+ "url": "https://fdc3.finos.org/docs/assets/fdc3-logo.png",
+ "tooltip": "FDC3 logo"
+ }
+ ],
+ "contactEmail": "fdc3@finos.org",
+ "supportEmail": "fdc3-maintainers@finos.org",
+ "publisher": "FDC3",
+ "intents": [
+ {
+ "name": "ViewChart",
+ "displayName": "View Chart",
+ "contexts": ["fdc3.instrument"]
+ }
+ ],
+ "type": "browser",
+ "details": {
+ "url": "https://fdc3.finos.org/toolbox/fdc3-workbench/"
+ },
+ "hostManifests": {
+ "Glue42": {
+ "type": "window",
+ "icon": "https://fdc3.finos.org/docs/assets/fdc3-logo.png",
+ "details": {
+ "height": 640,
+ "width": 560,
+ "left": 120,
+ "top": 120,
+ "mode": "tab",
+ "allowChannels": true,
+ "loader": {
+ "enabled": true,
+ "hideOnLoad": true
+ }
+ },
+ "customProperties": {
+ "folder": "FDC3 Toolbox"
+ }
+ },
+ "Finsemble": {
+ "window": {
+ "left": 120,
+ "top": 120,
+ "width": 800,
+ "height": 750,
+ "options": {
+ "minWidth": 75
+ }
+ },
+ "foreign": {
+ "components": {
+ "App Launcher": {
+ "launchableByUser": true
+ },
+ "Toolbar": {
+ "iconURL": "http://fdc3.finos.org/toolbox/fdc3-workbench/fdc3-icon-256.png"
+ },
+ "Window Manager": {
+ "FSBLHeader": true,
+ "persistWindowState": true
+ }
+ }
+ },
+ "interop": {
+ "autoConnect": true
+ }
+ }
+ }
+};

src/app-directory/specification/test/index.js

@@ -0,0 +1,24 @@
+const SwaggerParser = require('@apidevtools/swagger-parser');
+const { Validator } = require('jsonschema');
+const assert = require('assert');
+const exampleApplication = require('../examples/application/fdc3-workbench');
+
+(async () => {
+ try {
+ const api = await SwaggerParser.validate('../appd.yaml');
+
+ console.log(`API name: ${api.info.title}, Version: ${api.info.version}`);
+
+ const applicationSchema = api.components.schemas.Application;
+
+ const v = new Validator();
+
+ const validatorResult = v.validate(exampleApplication, applicationSchema);
+
+ assert(validatorResult.valid, `The example application definition does not comply with the Application schema: ${validatorResult.errors}`);
+
+ console.log('Successfully validated the specification and the example application definition!');
+ } catch (error) {
+ console.log(error.message || error);
+ }
+})();