Merge pull request #675 from finos/Appd-better-align-with-web-applica…

…tion-manifest 561 Appd better align with web application manifest
finos · May 5, 2022 · b385d8c · b385d8c
2 parents 8753a65 + 7a85f5a
commit b385d8c
Show file tree

Hide file tree

Showing 5 changed files with 82 additions and 47 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -38,6 +38,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 * Moved the Icon type definition into the Types documentation page for consistency with other types. ([#493](https://github.com/finos/FDC3/pull/493)
 * The `fdc3.joinChannel()`, `fdc3.getCurrentChannel()` and `fdc3.leaveCurrentChannel()` functions have been made optional for FDC3 API compliance, but are recommended through the application of the SHOULD keyword. ([#512](https://github.com/finos/FDC3/pull/512)) 
 * All DesktopAgent and Channel API functions are now async for consistency, changing the return type of the `broadcast`, `addIntentListener`, `addContextListener` and `getInfo` functions ([#516](https://github.com/finos/FDC3/pull/516))
+* AppD `images` field was replaced with `screenshots` to better align the applicaiton record with web application manifest and match its format to that used by `icons` ([#675](https://github.com/finos/FDC3/pull/675))
 
 ### Deprecated
 * Removed details of the 'global' channel that was deprecated in FDC3 1.2. ([#496](https://github.com/finos/FDC3/pull/496))

diff --git a/docs/app-directory/overview.md b/docs/app-directory/overview.md
@@ -74,6 +74,10 @@ As a vendor, you prefer for all your customers to run your latest software. Howe
 
 By hosting our own appD we can easily combine applications from various providers into one cohesive directory. Alternatively, we can connect to directories from multiple providers (in standardized format) and provide a single view over them. This reduces fragmentation in the market, allows end-users more flexibility in what apps to include in their smart desktop, and obviates the need for vendors to provide application details in diverse formats or for their customers to work out these details for themselves.
 
+## Relationship to other standards
+The App Directory's application record is similar to application manifests defined in other standards, in particular the W3C's [Web Application Manifest](https://www.w3.org/TR/appmanifest/). However, the App Directory, and by extension the application record, serve a different set of use-cases specific to application interoperability on financial services desktops, which other standards do not fully address. 
+
+Wherever possible, FDC3 seeks to draw inspiration from, align itself with and reference other standards - ensuring that conventions and best practices developed by those standards are reused, along with the standard itself (e.g. data formats in ISO standard formats, external links to technology-specific manifest file formats etc.). For a list of standards that FDC3 references, see the [References](../references) page.
 
 ## Sections to review
 

diff --git a/docs/references.md b/docs/references.md
@@ -16,7 +16,7 @@ The following normative documents contain provisions, which, through reference i
 - **RFC 2782**, _A DNS RR for specifying the location of services (DNS SRV), February 2000_, [https://datatracker.ietf.org/doc/html/rfc2782].
 - **RFC 5646**, _Tags for Identifying Languages, September 2009_, [https://datatracker.ietf.org/doc/html/rfc5646].
 - **TypeScript Programming Language**, [https://www.typescriptlang.org/].
-
+- **Web Application Manifest**, _W3C Working Draft_, February 2022 [https://www.w3.org/TR/appmanifest/]
 
 The following documents may be useful in understanding certain aspects of this Standard; however, knowledge of them is not essential to the creation of a compliant implementation of this Standard:
 

diff --git a/src/app-directory/specification/appd.yaml b/src/app-directory/specification/appd.yaml
@@ -500,13 +500,20 @@ components:
  type: array
  items:
  type: string
- images:
+ 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'
+ screenshots:
  type: array
  description: >-
  Array of images to show the user when they are looking at app
  description. Each image can have an optional description/tooltip
  items:
- $ref: '#/components/schemas/AppImage'
+ $ref: '#/components/schemas/Screenshot'
  contactEmail:
  type: string
  format: email
@@ -524,14 +531,7 @@ components:
  description: >-
  The name of the company that owns the application. The publisher has
  control over their namespace/app/signature.
- 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:
+ customConfig:
  type: array
  description: >-
  An optional set of name value pairs that can be used to deliver
@@ -629,7 +629,7 @@ components:
  Array of images to show the user when they are looking at app
  description. Each image can have an optional description/tooltip
  items:
- $ref: '#/components/schemas/AppImage'
+ $ref: '#/components/schemas/AppImageV1'
  contactEmail:
  type: string
  format: email
@@ -706,7 +706,7 @@ components:
  description: Icon URL
  size:
  type: string
- description: Icon dimension formatted as "<height>x<width>"
+ description: Icon dimension formatted as `<height>x<width>`
  type:
  type: string
  description: Image media type. If not present the Desktop Agent may use the src file extension
@@ -717,7 +717,23 @@ components:
  type: string
  format: uri
  description: Icon URL
- AppImage:
+ Screenshot:
+ description: Images representing the app in common usage scenarios
+ properties:
+ src:
+ type: string
+ format: uri
+ description: App Image URL
+ size:
+ type: string
+ description: Icon dimension formatted as `<height>x<width>`
+ type:
+ type: string
+ description: Image media type. If not present the Desktop Agent may use the src file extension
+ label:
+ type: string
+ description: Optional caption for the image
+ AppImageV1:
  description: App Image holder
  properties:
  url:
@@ -837,9 +853,9 @@ components:
  lang: en-US
  icons:
  - src: 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
+ screenshots:
+ - src: https://fdc3.finos.org/docs/assets/fdc3-logo.png
+ label: FDC3 logo
  contactEmail: fdc3@finos.org
  supportEmail: fdc3-maintainers@finos.org
  moreInfo: https://fdc3.finos.org #update to point to implementations page when it exists
@@ -922,13 +938,12 @@ components:
  lang: en-US
  icons:
  - src: 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
- moreInfo: https://fdc3.finos.org #update to point to implementations page when it exists
- publisher: FDC3
+ screenshots:
+ - src: https://fdc3.finos.org/docs/assets/fdc3-logo.png,
+ label: FDC3 logo
+ contactEmail: fdc3@finos.org,
+ supportEmail: fdc3-maintainers@finos.org,
+ publisher: FDC3,
  intents: [{
  name: ViewChart,
  displayName: View Chart,

diff --git a/website/static/schemas/next/app-directory.yaml b/website/static/schemas/next/app-directory.yaml
@@ -500,13 +500,20 @@ components:
  type: array
  items:
  type: string
- images:
+ 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'
+ screenshots:
  type: array
  description: >-
  Array of images to show the user when they are looking at app
  description. Each image can have an optional description/tooltip
  items:
- $ref: '#/components/schemas/AppImage'
+ $ref: '#/components/schemas/Screenshot'
  contactEmail:
  type: string
  format: email
@@ -524,14 +531,7 @@ components:
  description: >-
  The name of the company that owns the application. The publisher has
  control over their namespace/app/signature.
- 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:
+ customConfig:
  type: array
  description: >-
  An optional set of name value pairs that can be used to deliver
@@ -629,7 +629,7 @@ components:
  Array of images to show the user when they are looking at app
  description. Each image can have an optional description/tooltip
  items:
- $ref: '#/components/schemas/AppImage'
+ $ref: '#/components/schemas/AppImageV1'
  contactEmail:
  type: string
  format: email
@@ -706,7 +706,7 @@ components:
  description: Icon URL
  size:
  type: string
- description: Icon dimension formatted as "<height>x<width>"
+ description: Icon dimension formatted as `<height>x<width>`
  type:
  type: string
  description: Image media type. If not present the Desktop Agent may use the src file extension
@@ -717,7 +717,23 @@ components:
  type: string
  format: uri
  description: Icon URL
- AppImage:
+ Screenshot:
+ description: Images representing the app in common usage scenarios
+ properties:
+ src:
+ type: string
+ format: uri
+ description: App Image URL
+ size:
+ type: string
+ description: Icon dimension formatted as `<height>x<width>`
+ type:
+ type: string
+ description: Image media type. If not present the Desktop Agent may use the src file extension
+ label:
+ type: string
+ description: Optional caption for the image
+ AppImageV1:
  description: App Image holder
  properties:
  url:
@@ -837,9 +853,9 @@ components:
  lang: en-US
  icons:
  - src: 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
+ screenshots:
+ - src: https://fdc3.finos.org/docs/assets/fdc3-logo.png
+ label: FDC3 logo
  contactEmail: fdc3@finos.org
  supportEmail: fdc3-maintainers@finos.org
  moreInfo: https://fdc3.finos.org #update to point to implementations page when it exists
@@ -922,13 +938,12 @@ components:
  lang: en-US
  icons:
  - src: 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
- moreInfo: https://fdc3.finos.org #update to point to implementations page when it exists
- publisher: FDC3
+ screenshots:
+ - src: https://fdc3.finos.org/docs/assets/fdc3-logo.png,
+ label: FDC3 logo
+ contactEmail: fdc3@finos.org,
+ supportEmail: fdc3-maintainers@finos.org,
+ publisher: FDC3,
  intents: [{
  name: ViewChart,
  displayName: View Chart,