diff --git a/CHANGELOG.md b/CHANGELOG.md index 909df9ce7..889ad023f 100644 --- 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 index 95896a259..8d59b583b 100644 --- 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 index 261e87ca6..1f399df07 100644 --- 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 index e3b1759f8..676809953 100644 --- 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 "x" + description: Icon dimension formatted as `x` 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 `x` + 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 index e3b1759f8..676809953 100644 --- 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 "x" + description: Icon dimension formatted as `x` 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 `x` + 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,