From 6cc60fd39fd81249aa032ecb7549495b668b8b4e Mon Sep 17 00:00:00 2001 From: Kris West Date: Fri, 22 Apr 2022 18:20:48 +0100 Subject: [PATCH 1/3] add statement on alignment with other standards, changes appd images to screenshots and match format to icon/web app manifest --- docs/app-directory/overview.md | 4 ++ docs/references.md | 2 +- src/app-directory/specification/appd.yaml | 38 +++++++++++++----- .../static/schemas/next/app-directory.yaml | 40 +++++++++++++------ 4 files changed, 60 insertions(+), 24 deletions(-) diff --git a/docs/app-directory/overview.md b/docs/app-directory/overview.md index 95896a259..224d73af2 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 solve for. + +Whereever 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 e47838f9f..a706ed2fa 100644 --- a/src/app-directory/specification/appd.yaml +++ b/src/app-directory/specification/appd.yaml @@ -453,13 +453,13 @@ components: description: >- Description of the application. This will typically be a 1-2 paragraph style blurb about the application. Allow mark up language - images: + 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 @@ -582,7 +582,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 @@ -659,7 +659,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 @@ -670,7 +670,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: @@ -789,9 +805,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 @@ -872,9 +888,9 @@ components: tooltip: FDC3 Workbench 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, publisher: FDC3, diff --git a/website/static/schemas/next/app-directory.yaml b/website/static/schemas/next/app-directory.yaml index 6a61fb744..a706ed2fa 100644 --- a/website/static/schemas/next/app-directory.yaml +++ b/website/static/schemas/next/app-directory.yaml @@ -453,13 +453,13 @@ components: description: >- Description of the application. This will typically be a 1-2 paragraph style blurb about the application. Allow mark up language - images: + 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 @@ -582,7 +582,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 @@ -659,7 +659,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 @@ -670,7 +670,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: @@ -776,7 +792,7 @@ components: The keys to this object should be language tags as defined by IETF RFC 5646, e.g. en, en-GB or fr-FR. additionalProperties: x-additionalPropertiesName: Language tag - $ref: '#/components/schemas/BaseApplication' + $ref: '#/components/schemas/BaseApplication' # due to a bug in redoc this may display as a recursive definition, it is not. It will render correctly in swagger and other OpenAPI parsers. examples: FDC3WorkbenchAppDefinition: value: @@ -789,9 +805,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 @@ -872,9 +888,9 @@ components: tooltip: FDC3 Workbench 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, publisher: FDC3, From 29e3fe55c9829dd1ffa32459ed79b9b3a23e0e74 Mon Sep 17 00:00:00 2001 From: Kris West Date: Fri, 22 Apr 2022 18:36:12 +0100 Subject: [PATCH 2/3] changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 09eb8c3b5..a9beef2ef 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -37,6 +37,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)) From 8ace2edc4eecdefec27ca4777e81179e5bed0448 Mon Sep 17 00:00:00 2001 From: Kris West Date: Tue, 3 May 2022 13:05:26 +0100 Subject: [PATCH 3/3] Update docs/app-directory/overview.md --- docs/app-directory/overview.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/app-directory/overview.md b/docs/app-directory/overview.md index 224d73af2..8d59b583b 100644 --- a/docs/app-directory/overview.md +++ b/docs/app-directory/overview.md @@ -75,9 +75,9 @@ 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 solve for. +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. -Whereever 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. +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