Swagger for proposed Application and Intent schema
I have uploaded a Swagger/OpenApi YAML file that holds the Glue42 proposal for an Application definition and for an Intent definition.
Discussion of the Intent definition may be out of scope for the Working Group but I have included it because it is referenced in the schema. The spec also holds some null services so I can test and view the spec in the Swagger Editor UI.
I am not sure how to prepare the data for viewing in Confluence. I am going to include the definition of the Application here for people who are not going to download and read the full spec,
There are two key points to highlight :
- The applications now have a type which can be Desktop Exe, Browser and Container to allow an App Directory to specify multiple app types. This is particularly useful for in-house App Directories used in an Enterprise setting.
We also allow custom types to support specific local features like storing 'Layouts' in an App Directory. - A Container application can support multiple containers, this is a way to move all the container specific configuration outside the spec. This will allow 3rd parties to publish application definitions which can run on a variety of desktop containers/
| Code Block |
|---|
Application:
description: >
Defines an application retrieved from an FDC3 App Directory, which can then be launched.
Launching typically means running for a user on a desktop, but the concepts around laucnhing including
who or what might do it, and how the launch action is initiated are discussed elsewhere in the FDC3 App Directory spec.
required:
- name
- appType
- appDetails
properties:
name:
type: string
description: |
The name of the application.
The name should be unique within an FDC3 App Directory instance. The exception to the uniqueness constraint is that an App Directory can hold definitions for
multiple versions of the same app.
The same appName could occur in other directories. We are not currently specifying app name conventions in the document.
appType:
type: string
description: |
The type of the application. There should be predefined values, the different application types would also have different data fields.
Custom values will also be allowed to enable the use of in-house or 3rd party specific values such as layouts to be specified.
Launchers are expected to ignore applications of a custom type that they do not support.
The standard values proposed are
- DesktopExe. Some executable on the desktop. The detailed definitions could allow for Windows and Mac. This would mainly be used for specifying in-house applications
developed using .Net.
- Container. A Web Application detined to run in a container. The Container application type coud include meta data for the various container types that an
application vendor may support.
- Custom.{Vendor}.{CustomAppType}. Additional private application types can be specified. It reuqires co-ordination between the launcher and the App Directory instances to
allow these values to be used. An example would be to allow Desktop Layouts to be specified in an in-house App Directory Instance
version:
type: string
description: Version of the application. This allows multiple app versions to be defined using the same app name. This can be a triplet but can also include things like 1.2.5 (BETA)
title:
type: string
description: Optional title for the application, if missing use appName, typically used in a launcher UI.
tooltip:
type: string
description: Optional tooltip description e.g. for a launcher
description:
type: string
description: Description of the application. This will typically be a 1-2 paragraph style blurb about the application. Allow mark up langua
images:
type: array
description: Array of images to show the user when they are looking at app descritpion. Each image can have an optional description/tooltip
items:
$ref: '#/components/schemas/AppImage'
contactEmail:
type: string
description: Optional e-mail to receive queries about the application
supportEmail:
type: string
description: Optional e-mail to receive support requests for the application
publisher:
type: string
description: The name of the company that owns the application. The publisher has control over their namespace/app/signature(see diagram).
icons:
type: array
description: Holds Icons used for the application, a Launcher may be able to use multiple Icon sizes or there may be a 'button' Icon
items:
$ref: '#/components/schemas/Icon'
customConfig:
type: array
description: An optional set of name value pairs that can be used to deliver custom data from an App Directroy to a launcher.
items:
$ref: '#/components/schemas/NameValuePair'
intents:
type: array
description: |
The list of intents implemented by the Application.
NB The usage and meaning of Intents is still under discussion in the Intent WG (as of 27-Jun-18). See the comment on '#/components/schemas/Intent' for details.
I think the essence of the 'debate' is around how closely the terminology should match that used in Android.
I believe that in Android this intents field (within the Application definition) would be called actions and would effectively hold an Intent name and a Context,
where a context is an object type like Contact or Symbol.Equity that serves as a restriction on where the Intent/Action is valid.
However the current Intent definition can hold a Context so the split between action and intent is not strictly necessary.
items:
$ref: '#/components/schemas/Intent'
appDetails:
description: Depending on appType, expect to see one of the following for the app details
oneOf:
- $ref: '#/components/schemas/AppExe'
- $ref: '#/components/schemas/AppBrowser'
- $ref: '#/components/schemas/AppContainer'
- $ref: '#/components/schemas/AppCustom'
AppExe:
required:
- exePath
description: Holds data for an appType=Exe
properties:
exePath:
type: string
description: URI to the application, expect to use FILE:\\ style URI
allowMultiple:
type: boolean
description: SHould a launcher create a new instance or try and focus an existing instance
AppBrowser:
required:
- url
description: Holds data for an appType=Browser. It is up to the Launcher to select which Browser to use, typically this will be the default desktop browser.
properties:
url:
type: string
description: The URL to display in a browser window.
config:
type: array
description: optional set of Config values for displaying the browser, for example select a Kiosk mode. Values need to be 'agreed' between Launcher and App Directrory.
items:
$ref: '#/components/schemas/NameValuePair'
AppContainer:
required:
- manifests
description: Holds data for an appType=Container
properties:
url:
type: string
description: |
The initial URL of the application. This may need to be repeated in the container specific manifest.
We would recommend that Manifests can reference this URL via macros
signature:
type: string
description: The domain or public key that the application lives under. For example, the manifest_url would not be able to live under cdn.openfin2.co. Public Key would be a 1:1 ratio to an application but you can have many applications under a domain. Only required if app type is container.
manifests:
type: array
description: |
List of Container specific manifests for the application.
Maybe allow a short cut to just have a single manifest for sites with only a single container.
The discriminated list is of more use for companies offering an application supported in multiple containers.
items:
$ref: '#/components/schemas/ContainerManifest'
AppCustom:
description: Holds data for any other app type, it is assumed that the launcher and app directory will have agreed values to store here, outside the scope of FDC3
properties:
config:
type: array
description: The set of custom data, I prefer to give this as a list of name/value pairs with the value typically being a JSon object rather than a single value.
items:
$ref: '#/components/schemas/NameValuePair'
ContainerManifest:
required:
- containerType
- manifest
properties:
containerType:
type: string
description: |
name of the Container, agreed between container vendor and launcher.
Should we allow companies to register standard container names like OpenFin, Autobahn or Glue42
manifest:
type: string
description: |
The application manifest for the chosen container type.
Should we allow companies to register standard container names like OpenFin or Glue42
|