finos · kriswest · May 27, 2022 · Apr 4, 2022 · Apr 4, 2022 · Apr 19, 2022
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -22,6 +22,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 * Added details of FDC3's existing versioning and deprecation policies to the FDC3 compliance page ([#539](https://github.com/finos/FDC3/pull/539))
 * Added a new experimental features policy, which exempts features designated as experimental from the versioning and deprecation policies, to the FDC3 compliance page ([#549](https://github.com/finos/FDC3/pull/549))
 * Add `IntentDeliveryFailed` to the `ResolveError` enumeration to be used when delivery of an intent and context to a targetted app or instance fails. ([#601](https://github.com/finos/FDC3/pull/601))
+* Added `IntentDeliveryFailed` to the `ResolveError` enumeration to be used when delivery of an intent and context to a targetted app or instance fails. ([#601](https://github.com/finos/FDC3/pull/601))
+* Added a definition for "app directory record" to the FDC3 glossary to be used to refer to a single appD record ([#658](https://github.com/finos/FDC3/pull/658))
+* Added `/v2/` paths to the AppD's specification, allowing a single implementation to support serving both FDC3 v1.2 and v2.0 application records, enabling simpler migration ([#666](https://github.com/finos/FDC3/pull/666))
+* Added a `moreInfo` URL field to AppD application records to enable linking to a web page with more information on an app ([#669](https://github.com/finos/FDC3/pull/669))
+* Added `lang` field to AppD application records to specify the primary language of an app and its appD record. ([#670](https://github.com/finos/FDC3/pull/670))
+* Added `localizedVersions` field to AppD application records to support localized versions of descriptive fields in the app records and alternative launch details for localized versions of the applications themselves. ([#670](https://github.com/finos/FDC3/pull/670))
+* Added `type` and `details` elements to AppD application records to support vendor-agnostic launch details for both web and native apps ([#671](https://github.com/finos/FDC3/pull/671))
+* Added `categories` field and recommended categories list to AppD application records to enable category based browsing of AppDs ([#673](https://github.com/finos/FDC3/pull/673))
 
 ### Changed
 * Consolidated `Listener` documentation with other types ([#404](https://github.com/finos/FDC3/pull/404))
@@ -33,6 +41,9 @@ 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))
+* 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))
+* 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))
 
 ### 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
@@ -60,6 +60,12 @@ 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.
+
 ## Use Cases
 
 An application directory provides information about an application's identifiers, publisher details, intents that it supports, and metadata necessary to launch and integrate the application in a desktop agent.

diff --git a/docs/app-directory/spec.md b/docs/app-directory/spec.md
@@ -10,6 +10,10 @@ View the [full specification](/schemas/next/app-directory) in [OpenAPI v3.0](htt
 
  Endpoint           | Method | Description
  ------------------ | ------ | -----------
- `/v1/apps`         | POST   | Create a new application definition
- `/v1/apps/{appId}` | GET    | Retrieve an application defintion
- `/v1/apps/search`  | GET    | Retrieve a list of applications
+ `/v2/apps`         | GET    | Retrieve all application definitions
+ `/v2/apps/{appId}` | GET    | Retrieve an application defintion
+ `/v1/apps`         | POST   | (deprecated v1 API version) Create a new application definition
+ `/v1/apps/{appId}` | GET    | (deprecated v1 API version) Retrieve an application defintion
+ `/v1/apps/search`  | GET    | (deprecated v1 API version) Retrieve a list of applications
+
+App Directory implementations MAY extend the list of endpoints to provide other necessary functionality. However, FDC3 Desktop Agent implementations MUST support connection to app directories that only provide the minimum endpoints listed here.
diff --git a/docs/fdc3-glossary.md b/docs/fdc3-glossary.md
@@ -7,9 +7,11 @@ sidebar_label: Glossary
 For the purposes of this Standard, the following definitions apply. Other terms are defined when first used, at which place they appear in bold and italic type. Terms explicitly defined in this Standard are not to be presumed to refer implicitly to similar terms defined elsewhere. Terms not defined are assumed to be well-known in the financial services or software industries.
 
 
-- **app directory**: A repository of application metadata supporting discovery, for example via name or intent, and retrieval of metadata necessary to launch an application.
 - **app**: Shorthand for application.
+- **app directory**: A repository of application metadata supporting discovery, for example via name or intent, and retrieval of metadata necessary to launch an application.
+- **app directory record**: Metadata relating to a single application, encoded in JSON.
 - **appD**: Shorthand for app directory.
+- **appD record**: Shorthand for app directory record.
 - **application**: Any endpoint on the desktop that is registered with/known by a Desktop Agent, launchable by a Desktop Agent, addressable by a Desktop Agent or otherwise able to interact with the Desktop Agent.
 - **application, hybrid**: Any web application running within the context of a standalone native application that embeds a web view, typically based on Chromium.
 - **application, native**: A non-web-based application; i.e., one that runs outside the context of web browser, web view or web container. A user-written program—typically implemented in a language such as C++, C#, Java, or Python, rather than JavaScript or TypeScript.

diff --git a/docs/references.md b/docs/references.md
@@ -15,8 +15,9 @@ The following normative documents contain provisions, which, through reference i
 - **OpenAPI Standard v3.0**, [https://www.openapis.org/].
 - **RFC 2119**, _Keywords for use in RFCs to Indicate Requirement Levels, March 1997_, [https://datatracker.ietf.org/doc/html/rfc2119].
 - **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/README.md b/src/app-directory/README.md
@@ -12,8 +12,8 @@ The purpose of the Application Directory specification within FDC3 is to:
 
 ## Specification
 
-* [View the OpenAPI Specification in Swagger](https://editor.swagger.io/?url=https://fdc3.finos.org/schemas/1.1/app-directory.yaml)
-* [More about the Specification on the FDC3 Website](https://fdc3.finos.org/docs/1.1/app-directory/overview)
+* [View the OpenAPI Specification in Swagger](https://editor.swagger.io/?url=https://fdc3.finos.org/schemas/1.2/app-directory.yaml)
+* [More about the Specification on the FDC3 Website](https://fdc3.finos.org/docs/1.2/app-directory/overview)
 
 
 ## Directory structure