561 replace AppMetadata images field with screenshots, to match appD changes

CHANGELOG.md

@@ -59,6 +59,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 * 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))
 * `IntentResolution` now requires the name of the intent raised to included, allowing it to be used to determine the intent raised via `fdc3.raiseIntentForContext()`. ([#507](https://github.com/finos/FDC3/pull/507))
 * App Directory `images` field was replaced with `screenshots` to better align the application record with web application manifest and match its format to that used by `icons` ([#675](https://github.com/finos/FDC3/pull/675))
+* API `AppMetadata` type was updated to replace the `images` field with a `screenshots` field (an array of `Image` objects) matching the spec of the App Directory's `screenshots` field entries ([#736](https://github.com/finos/FDC3/pull/736))
 * App Directory endpoint for creating applications was removed as these will often be implementation dependent and should not be required for compliance ([#695](https://github.com/finos/FDC3/pull/695))
 * App Directory endpoint for searching applications was removed as searches over multiple app directories are better implemented by retrieving all the records and searching over the resulting combined dataset ([#696](https://github.com/finos/FDC3/pull/696))
 * Extended Intent Naming conventions and added hyperlinks for existing Intent spec definitions ([#701](https://github.com/finos/FDC3/pull/701))

docs/api/ref/Metadata.md

@@ -70,10 +70,8 @@ interface AppMetadata extends AppIdentifier {
    */
   readonly icons?: Array<Icon>;
 
-  /** A list of image URLs for the application that can be used to render UI
-   *  elements.
-   */
-  readonly images?: Array<string>;
+  /** Images representing the app in common usage scenarios that can be used to render UI elements */
+  readonly screenshots?: Array<Image>;
 
   /** The type of result returned for any intent specified during resolution. 
    *  May express a particular context type (e.g. "fdc3.instrument"), channel 
@@ -95,6 +93,7 @@ Note that as `AppMetadata` instances are also `AppIdentifiers` they may be passe
 * [`AppIdentifier`](Types#AppIdentifier)
 * [`AppIntent.apps`](#appintent)
 * [`Icon`](#icon)
+* [`Image`](#image)
 * [`DesktopAgent.open`](DesktopAgent#open)
 * [`DesktopAgent.findIntent`](DesktopAgent#findintent)
 * [`DesktopAgent.raiseIntent`](DesktopAgent#raiseintent)
@@ -160,6 +159,8 @@ interface Icon {
 }
 ```
 
+Metadata relating to a single icon image at a remote URL, used to represent an application in a user interface.
+
 AppMetadata includes an icons property allowing multiple icon types to be specified. Various properties may be used by the Desktop Agent to decide which icon is the most suitable to be used considering the application chooser UI, device DPI and formats supported by the system.
 
 #### Example
@@ -187,7 +188,7 @@ The fully qualified url to the icon.
 
 #### `size`
 
-The dimensions of the icon using formatted as "<height>x<width>"
+The dimensions of the Icon formatted as `<height>x<width>`.
 
 #### `type`
 
@@ -197,6 +198,58 @@ The media type of the icon. If not provided the Desktop Agent may refer to the s
 
 * [`AppMetadata`](Metadata#appmetadata)
 
+## `Image`
+
+```typescript
+interface Image {
+  src: string;
+  size?: string;
+  type?: string;
+  label?: string;
+}
+```
+
+Metadata relating to a single image at a remote URL, used to represent screenshot images.
+
+AppMetadata includes a screenshots property allowing multiple images to be specified. Various properties may be used by the Desktop Agent to decide which image(s) are the most suitable to be used considering the application chooser UI, device DPI and formats supported by the system.
+
+#### Example
+
+```js
+"screenshots": [
+  {
+    "src": "https://app.foo.icon/app_screenshots/dashboard.png",
+    "size": "800x600",
+    "type": "image/png",
+    "label": "Example app dashboard"
+  },
+  {
+    "src": "https://app.foo.icon/app_screenshots/notifications.png",
+    "size": "800x600",
+    "type": "image/png",
+    "label": "Order notifications view"
+  }
+]
+```
+
+#### Properties
+
+#### `src`
+
+The fully qualified url to the image.
+
+#### `size`
+
+The dimensions of the image formatted as `<height>x<width>`.
+
+#### `type`
+
+The media type of the image. If not provided the Desktop Agent may refer to the src file extension.
+
+#### See also
+
+* [`AppMetadata`](Metadata#appmetadata)
+
 ## `ImplementationMetadata`
 
 ```ts

src/api/AppMetadata.ts

@@ -5,6 +5,7 @@
 
 import { AppIdentifier } from './AppIdentifier';
 import { Icon } from './Icon';
+import { Image } from './Image';
 
 /**
  * Extends an `AppIdentifier`, describing an application or instance of an application, with additional descriptive metadata that is usually provided by an FDC3 App Directory that the desktop agent connects to.
@@ -40,7 +41,7 @@ export interface AppMetadata extends AppIdentifier {
   readonly icons?: Array<Icon>;
 
   /** A list of image URLs for the application that can be used to render UI elements */
-  readonly images?: Array<string>;
+  readonly images?: Array<Image>;
 
   /** The type of output returned for any intent specified during resolution. May express a particular context type (e.g. "fdc3.instrument"), channel (e.g. "channel") or a channel that will receive a specified type (e.g. "channel<fdc3.instrument>"). */
   readonly resultType?: string | null;

src/api/Icon.ts

@@ -7,9 +7,9 @@ export interface Icon {
   /** The icon url */
   readonly src: string;
 
-  /** The icon dimension */
+  /** The icon dimension, formatted as `<height>x<width>`. */
   readonly size?: string;
 
-  /** The icon media type */
+  /** Icon media type. If not present the Desktop Agent may use the src file extension. */
   readonly type?: string;
 }

src/api/Image.ts

@@ -0,0 +1,18 @@
+/**
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright FINOS FDC3 contributors - see NOTICE file
+ */
+
+export interface Image {
+  /** The image url. */
+  readonly src: string;
+
+  /** The image dimension, formatted as `<height>x<width>`. */
+  readonly size?: string;
+
+  /** Image media type. If not present the Desktop Agent may use the src file extension. */
+  readonly type?: string;
+
+  /** Caption for the image. */
+  readonly label?: string;
+}

src/app-directory/specification/appd.yaml

@@ -488,10 +488,10 @@ components:
           description: App Image URL
         size:
           type: string
-          description: Icon dimension formatted as `<height>x<width>`
+          description: Image 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
+          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

website/static/schemas/next/app-directory.yaml

@@ -488,10 +488,10 @@ components:
           description: App Image URL
         size:
           type: string
-          description: Icon dimension formatted as `<height>x<width>`
+          description: Image 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
+          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