Copying markdown docs for contexts into schema files

docs/agent-bridging/spec.md

@@ -41,7 +41,7 @@ In any Desktop Agent Bridging scenario, it is expected that each DA is being ope
 
 ## Bridging Desktop Agents
 
-The Desktop Agent Bridge Part of the FDC3 Standard is composed of three components:
+The Desktop Agent Bridging Part of the FDC3 Standard is composed of three components:
 
 - **[Connection](#connection)**: A means for Desktop Agents to communicate with a bridge, and through that bridge, with each other.
 - **[Connection Protocol](#connection-protocol)**: A protocol defining message exchanges necessary to connect to a Bridge and to perform initial state synchronization.
@@ -53,7 +53,7 @@ Detail on each of these components is defined in the following sections.
 
 Although this specification defines a particular [connection](#connection) type (based on a websocket server), it has been divided into parts so that the protocol definitions might be reused to implement a bridge over an alternative connection in future.
 
-:::
+::: 
 
 :::tip
 
@@ -67,6 +67,10 @@ However, Bridging should still be visible to applications, which is achieved thr
 
 Agent Bridging is introduced in FDC3 2.1 as an [@experimental](../fdc3-compliance#experimental-features) feature of the FDC3 Standard, included to enable implementation by and feedback from the FDC3 community. As such, it is currently optional for the purposes of compliance and is exempted from the normal versioning and deprecation polices in order to facilitate any refinement needed.
 
+### JSON Message Protocol & JSON Schema
+
+The connection and messaging protocols that the Desktop Agent Bridging Part defines are based on messages encoded in JSON. [JSON Schema](https://json-schema.org/) is used to define the format of each message in the protocol and should be considered the 'source of truth' for each and may be used to validate that individual messages are in the correct format. However, examples are provided in the documentation in TypeScript and JavaScript formats for convenience. TypeScript interfaces for individual messages, included in the FDC3 NPM module, are generated from the JSON Schema source files using [quicktype](https://quicktype.io/).
+
 ## Connection
 
 ### Topology

docs/context/ref/Action.md

@@ -6,12 +6,11 @@ hide_title: true
 ---
 # `Action`
 
-A representation of an FDC3 Action (specified via a Context or Context & Intent) that can be inserted inside another object, 
-for example a chat message.
+A representation of an FDC3 Action (specified via a Context or Context & Intent) that can be inserted inside another object, for example a chat message.
 
 The action may be completed by calling `fdc3.raiseIntent()` with the specified Intent and Context, or, if only a context is specified, by calling `fdc3.raiseIntentForContext()` (which the Desktop Agent will resolve by presenting the user with a list of available Intents for the Context).
 
-Accepts an optional `app` parameter in order to specify a certain app.
+Accepts an optional `app` parameter in order to specify a specific app.
 
 ## Type
 
@@ -33,8 +32,6 @@ Accepts an optional `app` parameter in order to specify a certain app.
 | `app.appId`       | string                                    | Yes      | `'app1'`                |
 | `app.instanceId`  | string                                    | No       | `'instance1'`           |
 
-
-
 ## Example
 
 ```js
@@ -69,7 +66,9 @@ const action = {
 ## See Also
 
 Other Types
-* [Message](Message)
+
+- [Message](Message)
 
 Intents
-* [StartChat](../../intents/ref/StartChat)
+
+- [StartChat](../../intents/ref/StartChat)

docs/context/ref/ChatInitSettings.md

@@ -61,7 +61,7 @@ const initSettings = {
         isPublic: false, // private chat room
         allowHistoryBrowsing: true,
         allowMessageCopy: true
-    }
+    },
     message: {
       type: 'fdc3.message',
       text: {

docs/context/ref/ChatRoom.md

@@ -6,7 +6,7 @@ hide_title: true
 ---
 # `ChatRoom`
 
-Reference to the chat room(s) (which could be used later to send a message to the room(s)).
+Reference to the chat room, which could be used later to send a message to the room.
 
 ## Type
 

docs/context/ref/Product.md

@@ -10,7 +10,7 @@ hide_title: true
 
 Notes:
 
-- The Product schema does not explicitly include identifiers in the id section, as there is not a common standard for such identifiers. Applications can, however, populate this part of the contract with custom identifiers if so desired.
+- The Product schema does not explicitly include identifiers in the `id` section, as there is not a common standard for such identifiers. Applications can, however, populate this part of the contract with custom identifiers if so desired.
 
 ## Type
 

docs/context/spec.md

@@ -4,7 +4,7 @@ sidebar_label: Overview
 title: Context Data (next)
 ---
 
-To interoperate, apps need to exchange commonly recognized context structures that can indicate topic with any number of identifiers or mappings to different systems. FDC3 Context Data defines a standard for passing common identifiers and data between apps to create a seamless workflow. FDC3 Context Data is not a symbology solution and is not specifically focused on modeling financial objects. The focus is on providing a standard payload structure that can be used to establish a lowest common denominator for interoperability.
+To interoperate, apps need to exchange commonly recognized context structures that can indicate topic with any number of identifiers or mappings to different systems. FDC3 Context Data defines a standard for passing common identifiers and data, encoded in JSON, between apps to create a seamless workflow. FDC3 Context Data is not a symbology solution and is not specifically focused on modeling financial objects. The focus is on providing a standard JSON payload structure that can be used to establish a lowest common denominator for interoperability.
 
 Context objects are used when raising [intents](../intents/spec) and when broadcasting context to other applications.
 
@@ -32,6 +32,12 @@ There are two main use cases for exchanging context data:
 
 FDC3 recognizes that there are other object definitions for providing context between applications. Most, if not all of these definitions though are platform-specific. FDC3, as a rule, sets out to be platform-agnostic and focused on creating bridges between the various walled gardens on the financial desktop.
 
+### Context Schemas
+
+FDC3 Context data is primarily encoded in JSON, but may also be encoded in language specific formats for use with FDC3 API implementations in those languages, although it is advisable to ensure that they can be converted to and from JSON.
+
+Each Standardized context type defined by the FDC3 Standard has an associated [JSON Schema](https://json-schema.org/) definition that should be considered the 'source of truth' for the context definition, although examples in documentation may also be given in TypeScript or JavaScript. The TypeScript definitions distributed in the FDC3 NPM module are generated from the JSON Schema files using [quicktype](https://quicktype.io/). Both documentation for fields defined (in the form of a `title` and `description` entry for each field defined) and examples SHOULD be included in JSON Schema definitions for Context types to ensure that the schema file can serve as a single source of truth, and that code generated from the schema files can also include that documentation.
+
 ## The Context Interface
 
 Context can be summarized as:
@@ -41,6 +47,8 @@ Context can be summarized as:
 - Optionally providing a map of equivalent identifiers.
 - Any other properties or metadata.
 
+Hence, the Context Interface can be represented in TypeScript as:
+
 ```typescript
 interface Context {
     type: string;
@@ -52,6 +60,36 @@ interface Context {
 }
 ```
 
+or in JSON Schema as:
+
+```JSON
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$id": "https://fdc3.finos.org/schemas/next/context/context.schema.json",
+    "type": "object",
+    "title": "Context",
+    "description": "The `fdc3.context` type defines the basic contract or \"shape\" for all data exchanged by FDC3 operations. As such, it is not really meant to be used on its own, but is imported by more specific type definitions (standardized or custom) to provide the structure and properties shared by all FDC3 context data types.\n\nThe key element of FDC3 context types is their mandatory `type` property, which is used to identify what type of data the object represents, and what shape it has.\n\nThe FDC3 context type, and all derived types, define the minimum set of fields a context data object of a particular type can be expected to have, but this can always be extended with custom fields as appropriate.",
+    "properties": {
+        "type": {
+            "type": "string"
+        },
+        "name": {
+            "type": "string"
+        },
+        "id": {
+            "type": "object",
+            "unevaluatedProperties": {
+                "type": "string"
+            }
+        }
+    },
+    "additionalProperties": true,
+    "required": [
+        "type"
+    ]
+}
+```
+
 ### Namespacing
 
 All well-known types at FDC3 level should be prefixed with `fdc3`. For private type definitions, or type definitions issued by other organizations, different namespaces can be used, e.g. `blackrock.fund`, etc.
@@ -62,11 +100,11 @@ The specification recognizes that evolving context data definitions over time, a
 
 It may be as simple as adding an optional `$version` property to types, but it could also be a set of guidelines for adding new properties, without removing or changing existing ones. For example, web technologies like REST or GraphQL do not take a particular opinion about versioning.
 
-## Field Type Conventions
+### Field Type Conventions
 
 This Standard defines a number of conventions for the fields of context types that all context objects SHOULD adhere to in order to reduce or prevent competing conventions from being established in both standardized types and proprietary types created by app developers.
 
-### Identifiers
+#### Identifiers
 
 An `id` field with type `object` is defined in the base [fdc3.context](ref/Context) type, from which all other context objects are derived, and SHOULD be used to encapsulate identifiers. Specific context types may define subfields for specific identifiers as needed.
 
@@ -90,7 +128,7 @@ The identifier "foo" is proprietary, an application that can use it is free to d
 }
 ```
 
-### Times
+#### Times
 
 Fields representing a point in time SHOULD be string encoded according to [ISO 8601-1:2019](https://www.iso.org/standard/70907.html) with a timezone indicator included, e.g.:
 
@@ -109,7 +147,7 @@ Parsing in JavaScript:
 let aDate = new Date("2022-03-30T11:44:44.123-04:00")
 ```
 
-### Dates
+#### Dates
 
 Fields representing a point in time SHOULD be string encoded using the `YYYY-MM-DD` date format from [ISO 8601-1:2019](https://www.iso.org/standard/70907.html).
 
@@ -121,13 +159,13 @@ Parsing in JavaScript:
 let aDate = new Date("2022-03-30")
 ```
 
-### Country codes
+#### Country codes
 
 Fields representing a country SHOULD be string encoded using the Alpha-2-codes from [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html) and field name `COUNTRY_ISOALPHA2`. The Alpha-3-codes from [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html) MAY be used in addition to the Alpha-2-code with the field name `COUNTRY_ISOALPHA3`.
 
 E.g. `"COUNTRY_ISOALPHA2": "GB"`
 
-### Currency codes
+#### Currency codes
 
 Fields representing a currency SHOULD be string encoded using the Alphabetic code from [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) with the field name `CURRENCY_ISOCODE`.
 

docs/references.md

@@ -13,6 +13,7 @@ The following normative documents contain provisions, which, through reference i
 - **ISO 8601-1:2019**, _Date and time — Representations for information interchange — Part 1: Basic rules_, <https://www.iso.org/standard/70907.html>
 - **JSON Schema**, <https://json-schema.org/>.
 - **OpenAPI Standard v3.0**, <https://www.openapis.org/>.
+- **quicktype**, <https://quicktype.io/>.
 - **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 4122**, _A Universally Unique IDentifier (UUID) URN Namespace, July 2005_, <https://datatracker.ietf.org/doc/html/rfc4122>.

schemas/context/action.schema.json

@@ -1,35 +1,67 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://fdc3.finos.org/schemas/next/context/action.schema.json",
-  "type": "object",
   "title": "Action",
-  "allOf": [{ "$ref": "context.schema.json#" }],
-  "properties": {
-    "type": { "const": "fdc3.action" },
-    "title": {
-      "type": "string"
-    },
-    "intent": {
-      "type": "string",
-      "description": "A reference an intent type name, such as those defined in the FDC3 Standard"
-    },
-    "context": {
-      "type": "object",
-      "$ref": "context.schema.json#"
-    },
-    "app": {
+  "description": "A representation of an FDC3 Action (specified via a Context or Context & Intent) that can be inserted inside another object, for example a chat message.\n\nThe action may be completed by calling `fdc3.raiseIntent()` with the specified Intent and Context, or, if only a context is specified, by calling `fdc3.raiseIntentForContext()` (which the Desktop Agent will resolve by presenting the user with a list of available Intents for the Context).\n\nAccepts an optional `app` parameter in order to specify a specific app.",
+  "allOf": [{
       "type": "object",
       "properties": {
-        "appId": { "type": "string" },
-        "instanceId": { "type": "string" }
+        "type": { "const": "fdc3.action" },
+        "title": {
+          "title": "Action Title",
+          "description": "A human readable display name for the action",
+          "type": "string"
+        },
+        "intent": {
+          "title": "Action Intent",
+          "description": "Optional Intent to raise to perform the actions. Should reference an intent type name, such as those defined in the FDC3 Standard. If intent is not set then `fdc3.raiseIntentForContext` should be used to perform the action as this will usually allow the user to choose the intent to raise.",
+          "type": "string"
+        },
+        "context": {
+          "title": "Action Context",
+          "description": "A context object with which the action will be performed",
+          "$ref": "context.schema.json#"
+        },
+        "app": {
+          "title": "Action Target App",
+          "description": "An optional target application identifier that should perform the action",
+          "allOf": [
+            { "$ref": "../api/api.schema.json#/definitions/AppIdentifier" }
+          ]
+        }
       },
-      "required": ["appId"]
+      "required": [
+        "title", "context"
+      ]
     },
-    "customConfig": {
-      "type": "object"
+    { "$ref": "context.schema.json#/definitions/BaseContext" }
+  ],
+  "examples": [
+    {
+      "type": "fdc3.action",
+      "title": "Click to view Chart",
+      "intent": "ViewChart",
+      "context": {
+          "type": "fdc3.chart",
+          "instruments": [
+              {
+                  "type": "fdc3.instrument",
+                  "id": {
+                      "ticker": "EURUSD"
+                  }
+              }
+          ],
+          "range": {
+              "type": "fdc3.dateRange",
+              "starttime": "2020-09-01T08:00:00.000Z",
+              "endtime": "2020-10-31T08:00:00.000Z"
+          },
+          "style": "candle"
+      },
+      "app" :{
+          "appId": "MyChartViewingApp",
+          "instanceId": "instance1"
+      }
     }
-  },
-  "required": [
-    "title", "context"
   ]
 }