Introduce a general, host independent, fdc3.general.app.manifest manifest type describing an application

[ggeorgievx]

Enhancement Request

Introduce a general fdc3.general.app.manifest manifest type describing an application. The specification would cover exe and browser type applications and would allow for host specific configurations. It would be defined with extensibility in mind.

The JSON schema of the manifest type would be:

{
    "id": "/fdc3.general.app.manifest",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "fdc3.general.app.manifest",
    "type": "object",
    "required": ["type", "details"],
    "additionalProperties": false,
    "properties": {
        "type": {
            "enum": [
                "browser",
                "exe"
            ]
        },
        "details": {
            "oneOf": [
                {
                    "$ref": "#/definitions/BrowserDetails"
                },
                {
                    "$ref": "#/definitions/ExeDetails"
                }
            ]
        },
        "hostManifests": {
            "type": "array",
            "items": {
                "$ref": "#/definitions/hostManifest"
            }
        }
    },
    "definitions": {
        "BrowserDetails": {
            "type": "object",
            "required": ["url"],
            "additionalProperties": false,
            "properties": {
                "url": {
                    "type": "string"
                }
            }
        },
        "ExeDetails": {
            "type": "object",
            "required": ["path"],
            "additionalProperties": false,
            "properties": {
                "path": {
                    "type": "string"
                }
            }
        },
        "hostManifest": {
            "type": "object",
            "required": [
                "name",
                "manifest"
            ],
            "properties": {
                "name": {
                    "type": "string"
                },
                "manifest": {
                    "type": "object"
                },
                "schema": {
                    "type": "string"
                }
            }
        }
    }
}

Please note:

• An alternative approach would be to modify the Application interface of the App Directory specification and introduce the type and details properties as first class citizens (similarly to how we do it at Glue42). In this case the new general fdc3.general.app.manifest manifest would only include the optional hostManifest property.
• Having additionalProperties: false would prevent developers from adding new properties that would otherwise need to be inside of the hostManifests thereby enforcing the specification.
• An alternative shape to the hostManifests property (currently an array of hostManifests) would be an object with the host name as key e.g.:

{
    ...
    "hostManifests": {
        "Glue42": {
            "manifest": {
                ...
            },
            "schema": "..."
        },
        "Finsemble": {
            "manifest": {
                ...
            },
            "schema": "..."
        },
        ...
    }
}

Use Case:

1. Let's assume that we are an application vendor. After completing the development of our application we would naturally like to make it available to the outside world. For that we want to create our own App Directory that serves our applications. This would allow hosts to connect to the App Directory and discover our applications. An important note is that our applications are host agnostic. During the development phase we test them and make sure they run unchanged on all hosts (Finsemble, Glue42, etc.) The problem we now face is that our App Directory needs to expose multiple definitions for the same applications as the different hosts use different manifest types.

It would be really convenient if there was a standard manifest type that allowed us to define one single definition per application that also included all the host specific configurations.

2. Going back to the idea of a Toolbar from some of the other issues (e.g. Introduce a new fdc3.applications() method #311). Having a general manifest type would also allow the Toolbar to launch any application, regardless of the vendor, as it would know where to look for the URL.

3. A general manifest type would also allow for reuse of existing App Directories. Let's say we want to create a quick FDC3 PoC - we wouldn't have to write our own App Directory and could instead use an existing one (e.g. Nick Kolba's) that follows the common manifest type that everyone understands.

Workflow Description

Every host would need to be adapted to understand the new manifest type. It would have to look inside of the parsed manifest for its host specific application manifest.

Workflow Examples

Here is an example of an application definition using the new manifest type:

const testDefinition = {
    appId: 'test-appId',
    name: 'test-name',
    title: 'Test title',
    description: 'Test description',
    version: '1.0.0',
    tooltip: 'Test tooltip',
    images: [
        {
            description: 'Test image',
            url: 'https://upload.wikimedia.org/wikipedia/commons/thumb/d/da/Yahoo_Finance_Logo_2019.svg/1200px-Yahoo_Finance_Logo_2019.svg.png'
        }
    ],
    contactEmail: 'test@contactEmail.com',
    supportEmail: 'test@supportEmail.com',
    publisher: 'Glue42',
    icons: [
        {
            description: 'Test icon',
            url: 'https://upload.wikimedia.org/wikipedia/commons/thumb/d/da/Yahoo_Finance_Logo_2019.svg/1200px-Yahoo_Finance_Logo_2019.svg.png'
        }
    ],
    customConfig: [],
    intents: [{
        name: 'test-intent',
        displayName: 'Test displayName',
        contexts: [],
        customConfig: {},
    }],
    manifestType: 'fdc3.general.app.manifest',
    manifest: `{
        "type": "browser",
        "details": {
            "url": "https://finance.yahoo.com/",
        },
        "hostManifests": [{
            "name": "Glue42",
            "manifest": {
                {
                    "height": 640,
                    "width": 560,
                    "left": 120,
                    "top": 120,
                    "mode": "tab",
                    "allowChannels": true
                }
            },
            "schema": "<url-to-a-schema-describing-the-shape-of-the-glue42-host-specific-manifest>"
        }]
    }`
};

Additional Information

A PR for this issue would include the schema, tests and examples.

[thorsent]

This is a good proposal and would let vendors fully standardize vendor independent manifests. I think the first alternative, of raising type and details to AppD's top level is probably superior in the long run (keeping all standardized fields at top level) assuming that the community is comfortable with making a breaking change.

[rikoe]

Thanks @thorsent - we are targeting this for v2.0 so that we can make breaking changes, so fingers crossed!

[lspiro-Tick42]

Thanks @thorsent - we are targeting this for v2.0 so that we can make breaking changes, so fingers crossed!

We will be adding support for this draft format into our 1.2 version, so that we can start to show container independent app stores.
It might be interesting if other container vendors (@thorsent ?) did that so that we could actually show rival containers sharing the same App D.
I think this would be a strong message to show to App Vendors looking to commit to FDC3.

[kriswest]

I propose we drop the manifestType field and make this manifest format required, particularly as custom manifests types can always be added under hostManifests. Otherwise, we invite divergence from the vendor-independent manifest unnecessarily.

We could also integrate this proposal directly into the application schema as it's pretty fundamental to the definition of an application - that would make the hostManifest schemas the only external references, which keeps things clean and simple.

[lspiro-Tick42]

Kris,

I like the idea of this being the one and only FDC3 Manifest type, with Desktop Agent specific overrides.

If we do this, then I think it would be useful to add some kind of 'requires' field, so that an app which could run in Finsemble or Glue42 could indicate that.

On a related note, I also wonder if we should separate Container and Browser applications. In Glue42 we also support Node.JS as a type of app for loading background service type apps, so maybe we could allow this, or else make the app type extensible.

[rikoe]

I think everyone is pretty much on the same page with this one. @ggeorgievx would you mind raising a PR for this?

We have agreed above:

• move 'type' and 'details' to the top level of the application defintion
• add additionalProperties: false
• add hostManifest array/object
• remove manifestType at top level

Anything I've forgotten? @lspiro-Tick42 I don't understand what you mean by the requires field.

[rikoe]

This is a full example, based on the above discussion:

const appDefinition = {
  appId: "myApp-v1.0.0-prod",
  name: "my-app",
  title: "My App",
  description: "My description",
  type: "browser", // options: browser, native (exe)
  details: {
    url: "https://finance.yahoo.com/", // or "path"
  },
  version: "1.0.0",
  tooltip: "My tooltip",
  images: [
    {
      url: "https://my-app/my-image.png",
    },
  ],
  contactEmail: "contact@my-app.com",
  supportEmail: "support@my-app.com",
  publisher: "Glue42",
  icons: [
    {
      src: "https://my-app/my-icon-48.png",
      sizes: "48x48",
      type: "image/png",
    },
    {
      src: "https://my-app/my-icon-72.png",
      sizes: "72x72",
      type: "image/png",
    },
  ],
  hostManifests: [
    {
      name: "Glue42",
      manifest: {
        height: 640,
        width: 560,
        left: 120,
        top: 120,
        mode: "tab",
        allowChannels: true,
      },
      schema: "https://glue42.com/schema.json",
    },
  ],
};

[rikoe]

Some comments:

• We should try not to use exe for type, it is platform specific
• Should the hostManifests be an array or keyed object?
• Should we use a different name than hostManifests? It is not very descriptive of what this section is for. What about hostLaunchDetails or something like that?
• It may be worth considering explicit support for W3C web app manifests, as this is a widely used standard (e.g. for PWAs): https://www.w3.org/TR/appmanifest/