openapi: 3.0.0 info: title: FDC3 Application Directory - App Specficiation description: > This spec is used to define the defintiion of an Application retrieved from an FDC3 App Directory. This document does not concern itself with any of the App Directory calls, and whilst it does define a few methods in order to be a valid Swagger spec they are not real. Some version of the types defined here are expected to be merged in with a full FDC3 App Directory Swagger spec after review. version: V0.0.3-for-review servers: - url: http://fdc3.glue42.com/app-store/ description: | This is not a valid URL, how should we host these kind of specs is GitHub and Confluence sufficient? Should we have a set of test servers for Swagger API and then for test/demo services. components: schemas: 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 NameValuePair: required: - name - value properties: name: type: string value: type: string description: The data for the field, typically JSon but this is not a requirement. AppImage: required: - name - url description: | Holds one or more images of an application, typically these are presented in a launcher that allows the user to browse application or possibly used in launchers. properties: name: type: string description: Name of the image, useful for implementing local cache tooltip: type: string description: optional tooltip for the image url: type: string description: The URL for the image. Not sure if we need to restrict the types of the image files. Icon: required: - url description: | Holds one or more images of an application, typically these are presented in a launcher that allows the user to browse application or possibly used in launchers. properties: iconType: type: string description: Describe the type of the Icon e.g. Windows App, Launcher Icon, Application Toolbar. The set of values are not formally specified. url: type: string Intent: description: | Describe an operation that an Application can carry out. NB The usage and meaning of Intents is still under discussion in the Intent WG (as of 27-Jun-18). In an FDC3 based environment there will typically be two types of Intent list both using this schema. There is a Global Intent list, this defines a standard list of intents, often based on the Intents defined by the FDC3 Intents WG with the possibility of site specific values. The Global Intent list is primarily used to provide 'override' values for Intent fields such as Display Name and Tooltip. This ensures that when there are multiple applications implementing the same Intent, there is a single definitive definition for these fields. It is NOT expected that an Intent definition in the Global Intent list will include a Context. Applications themselves then have a list of zero or more Intents that they offer, these Intents may be from the Global List or they could be application or Enterprise specific specific methods used by a small set of in-house applications. An Intent in an Application definition will typically have all fields specified so that the Intent can work irrespeive of the Global Intent list deployed at a site. However if the Intent name is in the Global List then the definition from the Global List overrides all of the application Intent fields except the Context. In otherwords in a correctly configured system, when an Application implements a Global Intent the only thing it specifies is the set of Contexts i.e. Constraints that it can accept. For 'local intents' allowing the Application to define all the values for an Intent avoids the need for app dev groups to have to submit their Intent definitions to the site adminstrators in order for them to work. These local Intents will typically be referenced from UI's via auto discovery and displayed in a context menu or posisbly coded directly into a local in-house application. NB. The App Directory WG needs to define how an Intent in an Application is triggered. This specification provides a launchHints which allows an application to indicates how the Intent should be initiated or invoked. For example in some cases the way that an Intent is carried out is by simply launching the application and supplying the appropriate context. In other cases the Intent is actioned via using some kind of interop to a running application, this case can use launchHint for extra info required: - intentName properties: name: type: string description: | The name of the intent. NB There are names of predefined intents. If this Intent definition is held in an Appliation and the intentName is one of the pre-defined list then the other values in this Intent definition will usually be ignored and the definitions from the standard/pre-defined definition will be used. displayName: type: string description: | An optional name to be used in Context menus instead of the intentName, which is typically going to be some structured name, possibly including vendor prefixes. tooltip: type: string description: Optional tooltip description for the Intent contexts: type: array description: An optinal list of 'contexts' for which the intent is valid. If this is empty or missing then default is ANY. items: $ref: '#/components/schemas/IntentContext' icons: type: array description: one or more icons that can be used to display the intent to the user. items: $ref: '#/components/schemas/Icon' launchHints: type: array description: | This optional structure can be used to contain launcher specific information on how to invole the Intent. This is important because the Intent definition will often be read in the context of an application and various types of Interop might be used to invoke the Intent method. items: $ref: '#/components/schemas/NameValuePair' IntentContext: required: - context description: | Holds a context that is typically used to 'restrict' an intent. properties: contextFormat: type: string description: | Should we allow multiple formats for a context e.g. OpenFIGI as well as FDC3, if the format is missing then it will be an FDC3 context If we are using OpenFIGI we may use a context like OpenFIGI.Equity.Common_Stock to represent an exchange traded equity. context: type: string description: The context i.e. object type on which the Intent is valid. Need to decide if we allow wild cards paths: /search: post: summary: Return a list of Applications matching the Query operationId: searchApps responses: '200': description: Successful response. content: application/json: schema: $ref: '#/components/schemas/Application'