diff --git a/CHANGELOG.md b/CHANGELOG.md index d8e19bd16..9ddb36545 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). * Added an indication that applications, that can be launched to receive intents or context via a raised intent or open with context, SHOULD add their context or intent listeners via the API within 15 seconds, and that Desktop Agents MUST allow at least a 15 second timeout for them to do so, and MAY set a longer timeout ([#987](https://github.com/finos/FDC3/pull/987)) * Added [@experimental](https://fdc3.finos.org/docs/fdc3-compliance#experimental-features) `Order`, `OrderList`, `Product`, `Trade` & `TradeList` context types. ([#1021](https://github.com/finos/FDC3/pull/1021)) * Added Agent Bridging as an [@experimental](https://fdc3.finos.org/docs/fdc3-compliance#experimental-features) 5th part of the FDC3 Standard. ([#968](https://github.com/finos/FDC3/pull/968)) +* Added a description of the standards use of JSON Schema to define context types and Bridging messages. ([#1020](https://github.com/finos/FDC3/pull/1020)) +* Documentation for standardized Context types was added to their JSON Schema files and TypeScript interfaces generated from them, so that they may act as a 'single source of truth' for Context definitions. ([#1020](https://github.com/finos/FDC3/pull/1020)) ### Changed diff --git a/docs/agent-bridging/spec.md b/docs/agent-bridging/spec.md index f8b1f749e..cf1347fbb 100644 --- a/docs/agent-bridging/spec.md +++ b/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 diff --git a/docs/context/ref/Action.md b/docs/context/ref/Action.md index 6d41393ad..714ccdb69 100644 --- a/docs/context/ref/Action.md +++ b/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) diff --git a/docs/context/ref/ChatInitSettings.md b/docs/context/ref/ChatInitSettings.md index f0bcd1066..b5ce5b261 100644 --- a/docs/context/ref/ChatInitSettings.md +++ b/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: { diff --git a/docs/context/ref/ChatRoom.md b/docs/context/ref/ChatRoom.md index 2fa72b2e1..ce52eb91c 100644 --- a/docs/context/ref/ChatRoom.md +++ b/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 diff --git a/docs/context/ref/SearchCriteria.md b/docs/context/ref/ChatSearchCriteria.md similarity index 100% rename from docs/context/ref/SearchCriteria.md rename to docs/context/ref/ChatSearchCriteria.md diff --git a/docs/context/ref/Product.md b/docs/context/ref/Product.md index e36185eb2..be56a866b 100644 --- a/docs/context/ref/Product.md +++ b/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 diff --git a/docs/context/spec.md b/docs/context/spec.md index 3dbc21c83..a16603da1 100644 --- a/docs/context/spec.md +++ b/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`. diff --git a/docs/references.md b/docs/references.md index 4e30a63f0..379c5342d 100644 --- a/docs/references.md +++ b/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_, - **JSON Schema**, . - **OpenAPI Standard v3.0**, . +- **quicktype**, . - **RFC 2119**, _Keywords for use in RFCs to Indicate Requirement Levels, March 1997_, . - **RFC 2782**, _A DNS RR for specifying the location of services (DNS SRV), February 2000_, . - **RFC 4122**, _A Universally Unique IDentifier (UUID) URN Namespace, July 2005_, . diff --git a/schemas/context/action.schema.json b/schemas/context/action.schema.json index a985015a7..693dd622d 100644 --- a/schemas/context/action.schema.json +++ b/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" ] } diff --git a/schemas/context/chart.schema.json b/schemas/context/chart.schema.json index 215326f61..171f9e594 100644 --- a/schemas/context/chart.schema.json +++ b/schemas/context/chart.schema.json @@ -3,28 +3,86 @@ "$id": "https://fdc3.finos.org/schemas/next/context/chart.schema.json", "type": "object", "title": "Chart", - "allOf": [{ "$ref": "context.schema.json#" }], - "properties": { - "type": { "const": "fdc3.chart" }, - "instruments": { - "type": "array", - "items": { - "$ref": "instrument.schema.json#" - } + "description": "A context type representing details of a Chart, which may be used to request plotting of a particular chart or to otherwise share details of its composition, such as:\n\n- A list of instruments for comparison\n- The time period to plot the chart over\n- The style of chart (line, bar, mountain, candle etc.)\n- Other settings such as indicators to calculate, or data representing drawings and annotations.\n\nIn addition to handling requests to plot charts, a charting application may use this type to output a representation of what it is currently displaying so that it can be recorded by another application.", + "allOf": [{ + "type": "object", + "properties": { + "type": { "const": "fdc3.chart" }, + "instruments": { + "title": "Instruments to plot", + "description": "An array of instrument contexts whose data should be plotted.", + "type": "array", + "items": { + "$ref": "instrument.schema.json#" + } + }, + "range": { + "title": "Time Range", + "description": "The time range that should be plotted", + "allOf": [{ + "$ref": "timerange.schema.json#" + }] + }, + "style": { + "title": "Chart style", + "description": "The type of chart that should be plotted", + "type": "string", + "enum": [ "line", "bar", "stacked-bar", "mountain", "candle", "pie", "scatter", "histogram", "heatmap", "custom"] + }, + "otherConfig": { + "title": "Other configuration", + "description": "It is common for charts to support other configuration, such as indicators, annotations etc., which do not have standardized formats, but may be included in the `otherConfig` array as context objects.", + "type": "array", + "items": { + "$ref": "context.schema.json#" + } + } + }, + "required": ["instruments"] }, - "range": { - "$ref": "timerange.schema.json#" - }, - "style": { - "type": "string", - "enum": [ "line", "bar", "stacked-bar", "mountain", "candle", "pie", "scatter", "histogram", "heatmap", "custom"] - }, - "otherConfig": { - "type": "array", - "items": { - "$ref": "context.schema.json#" - } + { "$ref": "context.schema.json#/definitions/BaseContext" } + ], + "examples": [ + { + "type": "fdc3.chart", + "instruments": [ + { + "type": "fdc3.instrument", + "id": { + "ticker": "AAPL" + } + }, + { + "type": "fdc3.instrument", + "id": { + "ticker": "GOOG" + } + } + ], + "range": { + "type": "fdc3.timeRange", + "startTime": "2020-09-01T08:00:00.000Z", + "endTime": "2020-10-31T08:00:00.000Z" + }, + "style": "line", + "otherConfig": [ + { + "type": "somevendor.someproduct.indicator", + "name": "stddev", + "parameters": { + "period": 10, + "matype": "exponential" + } + }, + { + "type": "someothervendor.someotherproduct.formula", + "formula": "standard-deviation", + "fields": { + "lookback": 10, + "type": "ema" + } + } + ] } - }, - "required": ["instruments"] + ] } diff --git a/schemas/context/chatInitSettings.schema.json b/schemas/context/chatInitSettings.schema.json index e2e967c1c..45711cd8b 100644 --- a/schemas/context/chatInitSettings.schema.json +++ b/schemas/context/chatInitSettings.schema.json @@ -1,36 +1,115 @@ { - "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://fdc3.finos.org/schemas/next/context/chatInitSettings.schema.json", - "type": "object", - "title": "ChatInitSettings", - "allOf": [{ "$ref": "context.schema.json#" }], - "properties": { + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://fdc3.finos.org/schemas/next/context/chatInitSettings.schema.json", + "type": "object", + "title": "ChatInitSettings", + "description": "A collection of settings to start a new chat conversation", + "allOf": [{ + "type": "object", + "properties": { "type": { "const": "fdc3.chat.initSettings" }, "chatName": { - "type": "string" + "title": "Chat name", + "description": "Name to apply to the chat created", + "type": "string" }, "members": { - "$ref": "contactList.schema.json#" + "title": "Chat members", + "description": "Contacts to add to the chat", + "$ref": "contactList.schema.json#" }, "message": { - "anyOf": [ - { - "type": "string" - }, - { - "$ref": "message.schema.json#" - } - ] + "title": "Initial chat message", + "description": "An initial message to post in the chat when created.", + "anyOf": [ + { + "type": "string" + }, + { + "$ref": "message.schema.json#" + } + ] }, "options": { - "type": "object", - "properties": { - "groupRecipients": {"type": "boolean"}, - "isPublic": {"type": "boolean"}, - "allowHistoryBrowsing": {"type": "boolean"}, - "allowMessageCopy": {"type": "boolean"}, - "allowAddUser": {"type": "boolean"} + "title": "Chat options", + "description": "Option settings that affect the creation of the chat", + "type": "object", + "properties": { + "groupRecipients": { + "title": "Group recipients option", + "description": "if false a separate chat will be created for each member", + "type": "boolean" + }, + "isPublic": { + "title": "Public chat option", + "description": "if true the room will be visible to everyone in the chat application", + "type": "boolean" + }, + "allowHistoryBrowsing": { + "title": "Allow history browsing option", + "description": "if true members will be allowed to browse past messages", + "type": "boolean" + }, + "allowMessageCopy": { + "title": "Allow message copy option", + "description": "if true members will be allowed to copy/paste messages", + "type": "boolean" + }, + "allowAddUser": { + "title": "All adding users option", + "description": "if true members will be allowed to add other members to the chat", + "type": "boolean" + } + } + } + } + }, + { "$ref": "context.schema.json#/definitions/BaseContext" } + ], + "examples": [ + { + "type": "fdc3.chat.initSettings", + "chatName": "Chat ABCD", + "members": { + "type": "fdc3.contactList", + "contacts": [ + { + "type": "fdc3.contact", + "name": "Jane Doe", + "id": { + "email": "jane@mail.com" + } + }, + { + "type": "fdc3.contact", + "name": "John Doe", + "id": { + "email": "john@mail.com" + } + } + ] + }, + "options": { + "groupRecipients": true, + "isPublic": false, + "allowHistoryBrowsing": true, + "allowMessageCopy": true + }, + "message": { + "type": "fdc3.message", + "text": { + "text/plain": "Hey all, can we discuss the issue together? I attached a screenshot" + }, + "entities": { + "0": { + "type": "fdc3.fileAttachment", + "data": { + "name": "myImage.png", + "dataUri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII" } + } } + } } + ] } diff --git a/schemas/context/chatMessage.schema.json b/schemas/context/chatMessage.schema.json index be443e915..d469d3805 100644 --- a/schemas/context/chatMessage.schema.json +++ b/schemas/context/chatMessage.schema.json @@ -2,12 +2,39 @@ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://fdc3.finos.org/schemas/next/context/chatMessage.schema.json", "type": "object", - "title": "ChatMessage", - "allOf": [{ "$ref": "context.schema.json#" }], - "properties": { - "type": { "const": "fdc3.chat.message" }, - "chatRoom": { "$ref": "chatRoom.schema.json#" }, - "message": { "$ref": "message.schema.json#" } - }, - "required": ["type", "chatRoom", "message"] + "title": "Chat Message", + "description": "A context representing a chat message. Typically used to send the message or to pre-populate a message for sending.", + "allOf": [{ + "type": "object", + "properties": { + "type": { "const": "fdc3.chat.message" }, + "chatRoom": { "$ref": "chatRoom.schema.json#" }, + "message": { + "title": "Chat message", + "description": "The content of the message to post in the chat when created.", + "anyOf": [ + { + "type": "string" + }, + { + "$ref": "message.schema.json#" + } + ] + } + }, + "required": ["type", "chatRoom", "message"] + }, + { "$ref": "context.schema.json#/definitions/BaseContext" } + ], + "examples": [{ + "type": "fdc3.chat.message", + "chatRoom": { + "type": "fdc3.chat.room", + "providerName": "Symphony", + "id": { + "streamId": "j75xqXy25NBOdacUI3FNBH" + } + }, + "message": "A message to send" + }] } diff --git a/schemas/context/chatRoom.schema.json b/schemas/context/chatRoom.schema.json index d0cd00664..d04fdf2f9 100644 --- a/schemas/context/chatRoom.schema.json +++ b/schemas/context/chatRoom.schema.json @@ -2,14 +2,47 @@ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://fdc3.finos.org/schemas/next/context/chatRoom.schema.json", "type": "object", - "title": "ChatRoom", - "allOf": [{ "$ref": "context.schema.json#" }], - "properties": { - "type": { "const": "fdc3.chat.room" }, - "providerName": { "type": "string" }, - "id": { "type": "object" }, - "url": { "type": "string" }, - "name": { "type": "string" } - }, - "required": ["providerName", "id"] + "title": "Chat Room", + "description": "Reference to the chat room which could be used to send a message to the room", + "allOf": [{ + "type": "object", + "properties": { + "type": { "const": "fdc3.chat.room" }, + "providerName": { + "title": "Chat provider name", + "description": "The name of the service that hosts the chat", + "type": "string" + }, + "id": { + "title": "Chat room id", + "description": "Identifier(s) for the chat - currently unstandardized", + "type": "object" + }, + "url": { + "title": "Chat URL", + "description": "Universal url to access to the room. It could be opened from a browser, a mobile app, etc...", + "type": "string", + "format": "uri" + }, + "name": { + "title": "Chat name", + "description": "Display name for the chat room", + "type": "string" + } + }, + "required": ["providerName", "id"] + }, + { "$ref": "context.schema.json#/definitions/BaseContext" } + ], + "examples": [ + { + "type": "fdc3.chat.room", + "providerName": "Symphony", + "id": { + "streamId": "j75xqXy25NBOdacUI3FNBH" + }, + "url": "http://symphony.com/ref/room/j75xqXy25NBOdacUI3FNBH___pqSsuJRdA", + "name": "My new room" + } + ] } diff --git a/schemas/context/chatSearchCriteria.schema.json b/schemas/context/chatSearchCriteria.schema.json index 95cdf90d7..e6210ae82 100644 --- a/schemas/context/chatSearchCriteria.schema.json +++ b/schemas/context/chatSearchCriteria.schema.json @@ -2,21 +2,65 @@ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://fdc3.finos.org/schemas/next/context/chatSearchCriteria.schema.json", "type": "object", - "title": "ChatSearchCriteria", - "allOf": [{ "$ref": "context.schema.json#" }], - "properties": { - "type": { "const": "fdc3.chat.searchCriteria" }, - "criteria": { - "type": "array", - "items": { - "anyOf": [ - { "$ref":"instrument.schema.json#" }, - { "$ref": "organization.schema.json#" }, - { "$ref": "contact.schema.json#" }, - { "type": "string" } - ] - } + "title": "Chat Search Criteria", + "description": "A context type that represents a simple search criterion, based on a list of other context objects, that can be used to search or filter messages in a chat application.", + "allOf": [ + { + "type": "object", + "properties": { + "type": { + "const": "fdc3.chat.searchCriteria" + }, + "criteria": { + "title": "Criteria array", + "description": "An array of criteria that should match chats returned from by a search.\n\n⚠️ Operators (and/or/not) are not defined in `fdc3.chat.searchCriteria`. It is up to the application that processes the FDC3 Intent to choose and apply the operators between the criteria.\n\nEmpty search criteria can be supported to allow resetting of filters.", + "type": "array", + "items": { + "anyOf": [ + { + "$ref": "instrument.schema.json#" + }, + { + "$ref": "organization.schema.json#" + }, + { + "$ref": "contact.schema.json#" + }, + { + "type": "string", + "title": "Free text", + "description": "Free text to be used for a keyword search" + } + ] + } + } + }, + "required": [ + "criteria" + ] + }, + { "$ref": "context.schema.json#/definitions/BaseContext" } + ], + "examples": [ + { + "type": "fdc3.chat.searchCriteria", + "criteria": [ + { + "type": "fdc3.contact", + "name": "Jane Doe", + "id": { + "email": "jane.doe@mail.com" + } + }, + { + "type": "fdc3.instrument", + "id": { + "ticker": "TSLA" + }, + "name": "Tesla, inc." + }, + "annual return" + ] } - }, - "required": ["criteria"] -} + ] +} \ No newline at end of file diff --git a/schemas/context/contact.schema.json b/schemas/context/contact.schema.json index 6aef5f52e..e2066b58c 100644 --- a/schemas/context/contact.schema.json +++ b/schemas/context/contact.schema.json @@ -3,16 +3,46 @@ "$id": "https://fdc3.finos.org/schemas/next/context/contact.schema.json", "type": "object", "title": "Contact", - "allOf": [{ "$ref": "context.schema.json#" }], - "properties": { - "type": { "const": "fdc3.contact" }, - "id": { + "description": "A person contact that can be engaged with through email, calling, messaging, CMS, etc.", + "allOf": [ + { "type": "object", "properties": { - "email": { "type": "string" }, - "FDS_ID": { "type": "string" } + "type": { + "const": "fdc3.contact" + }, + "id": { + "type": "object", + "title": "Contact Identifiers", + "description": "Identifiers that relate to the Contact represented by this context", + "properties": { + "email": { + "type": "string", + "format": "email", + "title": "Email address", + "description": "The email address for the contact" + }, + "FDS_ID": { + "type": "string", + "title": "FDS ID", + "description": "FactSet Permanent Identifier representing the contact" + } + } + } + }, + "required": [ + "id" + ] + }, + { "$ref": "context.schema.json#/definitions/BaseContext" } + ], + "examples": [ + { + "type": "fdc3.contact", + "name": "Jane Doe", + "id": { + "email": "jane.doe@mail.com" } } - }, - "required": ["id"] + ] } diff --git a/schemas/context/contactList.schema.json b/schemas/context/contactList.schema.json index 57bf2a532..ed571f38c 100644 --- a/schemas/context/contactList.schema.json +++ b/schemas/context/contactList.schema.json @@ -3,13 +3,48 @@ "$id": "https://fdc3.finos.org/schemas/next/context/contactList.schema.json", "type": "object", "title": "ContactList", - "allOf": [{ "$ref": "context.schema.json#" }], - "properties": { - "type": { "const": "fdc3.contactList" }, - "contacts": { - "type": "array", - "items": { "$ref": "contact.schema.json#" } + "description": "A collection of contacts, e.g. for chatting to or calling multiple contacts.\n\nThe contact list 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.", + "allOf": [ + { + "type": "object", + "properties": { + "type": { + "const": "fdc3.contactList" + }, + "contacts": { + "type": "array", + "title": "List of Contacts", + "description": "An array of contact contexts that forms the list.", + "items": { + "$ref": "contact.schema.json#" + } + } + }, + "required": [ + "contacts" + ] + }, + { "$ref": "context.schema.json#/definitions/BaseContext" } + ], + "examples": [ + { + "type": "fdc3.contactList", + "contacts": [ + { + "type": "fdc3.contact", + "name": "Jane Doe", + "id": { + "email": "jane.doe@mail.com" + } + }, + { + "type": "fdc3.contact", + "name": "John Doe", + "id": { + "email": "john.doe@mail.com" + } + } + ] } - }, - "required": ["contacts"] -} + ] +} \ No newline at end of file diff --git a/schemas/context/context.schema.json b/schemas/context/context.schema.json index b14861b52..8c84dd866 100644 --- a/schemas/context/context.schema.json +++ b/schemas/context/context.schema.json @@ -3,14 +3,65 @@ "$id": "https://fdc3.finos.org/schemas/next/context/context.schema.json", "type": "object", "title": "Context", - "properties": { - "type": { "type": "string" }, - "name": { "type": "string" }, - "id": { + "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.", + "allOf": [ + { + "$ref": "#/definitions/DocumentedContext" + }, + { + "$ref": "#/definitions/BaseContext" + } + ], + "definitions": { + "BaseContext": { + "$comment": "Base definition for the Context object without documentation (which will be imported into all derived types unless separated).", + "type": "object", + "properties": { + "type": { + "type": "string" + }, + "name": { + "type": "string" + }, + "id": { + "type": "object", + "unevaluatedProperties": { + "type": "string" + } + } + }, + "additionalProperties": true, + "required": [ + "type" + ] + }, + "DocumentedContext": { + "$comment": "Base definition for the Context object without documentation (which will be imported into all derived types unless separated).", "type": "object", - "unevaluatedProperties": { "type": "string" } + "properties": { + "type": { + "type": "string", + "title": "Type", + "description": "The type property is the only _required_ part of the FDC3 context data schema. The FDC3 [API](https://fdc3.finos.org/docs/api/spec) relies on the `type` property being present to route shared context data appropriately.\n\nFDC3 [Intents](https://fdc3.finos.org/docs/intents/spec) also register the context data types they support in an FDC3 [App Directory](https://fdc3.finos.org/docs/app-directory/overview), used for intent discovery and routing.\n\nStandardized FDC3 context types have well-known `type` properties prefixed with the `fdc3` namespace, e.g. `fdc3.instrument`. For non-standard types, e.g. those defined and used by a particular organization, the convention is to prefix them with an organization-specific namespace, e.g. `blackrock.fund`.\n\nSee the [Context Data Specification](https://fdc3.finos.org/docs/context/spec) for more information about context data types." + }, + "name": { + "type": "string", + "title": "Name", + "description": "Context data objects may include a name property that can be used for more information, or display purposes. Some derived types may require the name object as mandatory, depending on use case." + }, + "id": { + "type": "object", + "title": "Id", + "description": "Context data objects may include a set of equivalent key-value pairs that can be used to help applications identify and look up the context type they receive in their own domain. The idea behind this design is that applications can provide as many equivalent identifiers to a target application as possible, e.g. an instrument may be represented by an ISIN, CUSIP or Bloomberg identifier.\n\nIdentifiers do not make sense for all types of data, so the `id` property is therefore optional, but some derived types may choose to require at least one identifier.", + "unevaluatedProperties": { + "type": "string" + } + } + }, + "additionalProperties": true, + "required": [ + "type" + ] } - }, - "additionalItems": true, - "required": ["type"] -} + } +} \ No newline at end of file diff --git a/schemas/context/country.schema.json b/schemas/context/country.schema.json index 2a0a6a763..66bb354e6 100644 --- a/schemas/context/country.schema.json +++ b/schemas/context/country.schema.json @@ -3,18 +3,55 @@ "$id": "https://fdc3.finos.org/schemas/next/context/country.schema.json", "type": "object", "title": "Country", - "allOf": [{ "$ref": "context.schema.json#" }], - "properties": { - "type": { "const": "fdc3.country" }, - "id": { + "description": "A country entity.\n\nNotes:\n\n- It is valid to include extra properties and metadata as part of the country payload, but the minimum requirement is for at least one standardized identifier to be provided\n\n - `COUNTRY_ISOALPHA2` SHOULD be preferred.\n\n- Try to only use country identifiers as intended and specified in the [ISO standard](https://en.wikipedia.org/wiki/ISO_3166-1). E.g. the `COUNTRY_ISOALPHA2` property must be a recognized value and not a proprietary two-letter code. If the identifier you want to share is not a standardized and recognized one, rather define a property that makes it clear what value it is. This makes it easier for target applications.", + "allOf": [ + { "type": "object", "properties": { - "COUNTRY_ISOALPHA2": { "type": "string" }, - "COUNTRY_ISOALPHA3": { "type": "string" }, - "ISOALPHA2": { "type": "string" }, - "ISOALPHA3": { "type": "string" } + "type": { + "const": "fdc3.country" + }, + "id": { + "type": "object", + "properties": { + "COUNTRY_ISOALPHA2": { + "type": "string", + "title": "COUNTRY_ISOALPHA2", + "description": "Two-letter ISO country code" + }, + "COUNTRY_ISOALPHA3": { + "type": "string", + "title": "COUNTRY_ISOALPHA3", + "description": "Three-letter ISO country code" + }, + "ISOALPHA2": { + "type": "string", + "title": "ISOALPHA2", + "description": "Two-letter ISO country code. Deprecated in FDC3 2.0 in favour of the version prefixed with `COUNTRY_`.", + "deprecated": true + }, + "ISOALPHA3": { + "type": "string", + "title": "ISOALPHA3", + "description": "Three-letter ISO country code. Deprecated in FDC3 2.0 in favour of the version prefixed with `COUNTRY_`.", + "deprecated": true + } + } + } + }, + "required": [ + "id" + ] + }, + { "$ref": "context.schema.json#/definitions/BaseContext" } + ], + "examples": [ + { + "type": "fdc3.country", + "name": "Sweden", + "id": { + "COUNTRY_ISOALPHA2": "SE" } } - }, - "required": ["id"] -} + ] +} \ No newline at end of file diff --git a/schemas/context/currency.schema.json b/schemas/context/currency.schema.json index aa0c08455..a58b5b75c 100644 --- a/schemas/context/currency.schema.json +++ b/schemas/context/currency.schema.json @@ -3,17 +3,44 @@ "$id": "https://fdc3.finos.org/schemas/next/context/currency.schema.json", "type": "object", "title": "Currency", - "allOf": [{ "$ref": "context.schema.json#" }], - "properties": { - "type": { "const": "fdc3.currency" }, - "name": { "type": "string" }, - "id": { + "description": "A context representing an individual Currency.", + "allOf": [ + { "type": "object", "properties": { - "CURRENCY_ISOCODE": { "type": "string", "pattern": "^[A-Z]{3}$"} + "type": { + "const": "fdc3.currency" + }, + "name": { + "type": "string", + "title": "Currency name", + "description": "The name of the currency for display purposes" + }, + "id": { + "type": "object", + "properties": { + "CURRENCY_ISOCODE": { + "type": "string", + "pattern": "^[A-Z]{3}$", + "title": "CURRENCY_ISOCODE", + "description": "The `CURRENCY_ISOCODE` should conform to 3 character alphabetic codes defined in [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html)" + } + } + } + }, + "required": [ + "id" + ] + }, + { "$ref": "context.schema.json#/definitions/BaseContext" } + ], + "examples": [ + { + "type": "fdc3.currency", + "name": "US Dollar", + "id": { + "CURRENCY_ISOCODE": "USD" } } - - }, - "required": ["id"] -} + ] +} \ No newline at end of file diff --git a/schemas/context/email.schema.json b/schemas/context/email.schema.json index 4ec814dcf..eb863bfa6 100644 --- a/schemas/context/email.schema.json +++ b/schemas/context/email.schema.json @@ -3,17 +3,55 @@ "$id": "https://fdc3.finos.org/schemas/next/context/email.schema.json", "type": "object", "title": "Email", - "allOf": [{ "$ref": "context.schema.json#" }], - "properties": { - "type": { "const": "fdc3.email" }, - "recipients": { - "oneOf": [ - { "$ref": "contact.schema.json#" }, - { "$ref": "contactList.schema.json#" } + "description": "A collection of information to be used to initiate an email with a Contact or ContactList.", + "allOf": [ + { + "type": "object", + "properties": { + "type": { + "const": "fdc3.email" + }, + "recipients": { + "title": "Email Recipients", + "description": "One or more receipients for the email.", + "oneOf": [ + { + "$ref": "contact.schema.json#" + }, + { + "$ref": "contactList.schema.json#" + } + ] + }, + "subject": { + "title": "Email Subject", + "description": "Subject line for the email.", + "type": "string" + }, + "textBody": { + "title": "Email Body", + "description": "Body content for the email.", + "type": "string" + } + }, + "required": [ + "recipients" ] }, - "subject": { "type": "string" }, - "textBody": { "type": "string" } - }, - "required": ["recipients"] -} + { "$ref": "context.schema.json#/definitions/BaseContext" } + ], + "examples": [ + { + "type": "fdc3.email", + "recipients": { + "type": "fdc3.contact", + "name": "Jane Doe", + "id": { + "email": "jane.doe@example.com" + } + }, + "subject": "The information you requested", + "textBody": "Blah, blah, blah ..." + } + ] +} \ No newline at end of file diff --git a/schemas/context/instrument.schema.json b/schemas/context/instrument.schema.json index eee0f800f..7ea8435d8 100644 --- a/schemas/context/instrument.schema.json +++ b/schemas/context/instrument.schema.json @@ -3,34 +3,114 @@ "$id": "https://fdc3.finos.org/schemas/next/context/instrument.schema.json", "type": "object", "title": "Instrument", - "allOf": [{ "$ref": "context.schema.json#" }], - "properties": { - "type": { "const": "fdc3.instrument" }, - "id": { + "description": "A financial instrument from any asset class.", + "allOf": [ + { "type": "object", "properties": { - "BBG": { "type": "string" }, - "CUSIP": { "type": "string" }, - "FDS_ID": { "type": "string" }, - "FIGI": { "type": "string" }, - "ISIN": { "type": "string" }, - "PERMID": { "type": "string" }, - "RIC": { "type": "string" }, - "SEDOL": { "type": "string" }, - "ticker": { "type": "string" } - } + "type": { + "const": "fdc3.instrument" + }, + "id": { + "title": "Instrument identifiers", + "description": "Any combination of instrument identifiers can be used together to resolve ambiguity, or for a better match. Not all applications will use the same instrument identifiers, which is why FDC3 allows for multiple to be specified. In general, the more identifiers an application can provide, the easier it will be to achieve interoperability.\n\nIt is valid to include extra properties and metadata as part of the instrument payload, but the minimum requirement is for at least one instrument identifier to be provided.\n\nTry to only use instrument identifiers as intended. E.g. the `ticker` property is meant for tickers as used by an exchange.\nIf the identifier you want to share is not a ticker or one of the other standardized fields, define a property that makes it clear what the value represents. Doing so will make interpretation easier for the developers of target applications.", + "type": "object", + "properties": { + "BBG": { + "type": "string", + "title": "Bloomberg security", + "description": "" + }, + "CUSIP": { + "type": "string", + "title": "CUSIP", + "description": "" + }, + "FDS_ID": { + "type": "string", + "title": "FactSet Permanent Security Identifier", + "description": "" + }, + "FIGI": { + "type": "string", + "title": "Open FIGI", + "description": "" + }, + "ISIN": { + "type": "string", + "title": "ISIN", + "description": "" + }, + "PERMID": { + "type": "string", + "title": "Refinitiv PERMID", + "description": "" + }, + "RIC": { + "type": "string", + "title": "Refinitiv Identification Code", + "description": " " + }, + "SEDOL": { + "type": "string", + "title": "SEDOL", + "description": "" + }, + "ticker": { + "type": "string", + "title": "Stock ticker", + "description": "Unstandardized stock tickers" + } + } + }, + "market": { + "description": "The `market` map can be used to further specify the instrument and help achieve interoperability between disparate data sources. This is especially useful when using an `id` field that is not globally unique.", + "type": "object", + "properties": { + "MIC": { + "type": "string", + "title": "Market Identifier Code", + "description": "" + }, + "name": { + "type": "string", + "title": "Market Name", + "description": "Human readable market name" + }, + "COUNTRY_ISOALPHA2": { + "type": "string", + "title": "Country ISO Code", + "description": "" + }, + "BBG": { + "type": "string", + "title": "Bloomberg Market Identifier", + "description": "" + } + }, + "unevaluatedProperties": { + "type": "string" + } + } + }, + "required": [ + "type","id" + ] }, - "market": { - "type": "object", - "properties": { - "MIC": { "type": "string" }, - "name": { "type": "string" }, - "COUNTRY_ISOALPHA2": { "type": "string" }, - "BBG": { "type": "string" } + { "$ref": "context.schema.json#/definitions/BaseContext" } + ], + "examples": [ + { + "type": "fdc3.instrument", + "name": "Microsoft", + "id": { + "ticker": "MSFT", + "RIC": "MSFT.OQ", + "ISIN": "US5949181045" }, - "unevaluatedProperties": { "type": "string" } + "market": { + "MIC": "XNAS" + } } - - }, - "required": ["id"] -} \ No newline at end of file + ] +} diff --git a/schemas/context/instrumentList.schema.json b/schemas/context/instrumentList.schema.json index ceca78935..4fb2627ea 100644 --- a/schemas/context/instrumentList.schema.json +++ b/schemas/context/instrumentList.schema.json @@ -3,13 +3,49 @@ "$id": "https://fdc3.finos.org/schemas/next/context/instrumentList.schema.json", "type": "object", "title": "InstrumentList", - "allOf": [{ "$ref": "context.schema.json#" }], - "properties": { - "type": { "const": "fdc3.instrumentList" }, - "instruments": { - "type": "array", - "items": { "$ref": "instrument.schema.json#" } + "description": "A collection of instruments. Use this type for use cases that require not just a single instrument, but multiple (e.g. to populate a watchlist). However, when holding information for each instrument is required, it is recommended to use the [Portfolio](Portfolio) type.\n\nThe instrument list 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.", + "allOf": [ + { + "type": "object", + "properties": { + "type": { + "const": "fdc3.instrumentList" + }, + "instruments": { + "type": "array", + "title": "List of instruments", + "description": "An array of instrument contexts that forms the list.", + "items": { + "$ref": "instrument.schema.json#" + } + } + }, + "required": [ + "instruments" + ] + }, + { "$ref": "context.schema.json#/definitions/BaseContext" } + ], + "examples": [ + { + "type": "fdc3.instrumentList", + "instruments": [ + { + "type": "fdc3.instrument", + "id": { + "ticker": "AAPL" + }, + "market": { + "MIC": "XNAS" + } + }, + { + "type": "fdc3.instrument", + "id": { + "ISIN": "US5949181045" + } + } + ] } - }, - "required": ["instruments"] -} + ] +} \ No newline at end of file diff --git a/schemas/context/interaction.schema.json b/schemas/context/interaction.schema.json index b5ed532d3..bf001f03f 100644 --- a/schemas/context/interaction.schema.json +++ b/schemas/context/interaction.schema.json @@ -3,35 +3,125 @@ "$id": "https://fdc3.finos.org/schemas/next/context/interaction.schema.json", "type": "object", "title": "Interaction", - "allOf": [{ "$ref": "context.schema.json#" }], - "properties": { - "type": { "const": "fdc3.interaction" }, - "participants": { - "$ref": "contactList.schema.json#" - }, - "timeRange": { - "$ref": "timerange.schema.json#" - }, - "interactionType": { - "anyOf": [ - { - "type": "string", - "enum": ["Instant Message", "Email", "Call", "Meeting"] + "description": "An `Interaction` is a significant direct exchange of ideas or information between a number of participants, e.g. a Sell Side party and one or more Buy Side parties. An `Interaction` might be a call, a meeting (physical or virtual), an IM or the preparation of some specialist data, such as financial data for a given company or sector.", + "allOf": [ + { + "type": "object", + "properties": { + "type": { + "const": "fdc3.interaction" + }, + "id": { + "type": "object", + "title": "Interaction Id", + "description": "Can be used by a target application to pass an identifier back to the originating application after an interaction record has been created, updated or deleted. An interaction ID does not need to be populated by the originating application, however the target application could store it for future reference and SHOULD return it in a `TransactionResult`.", + "properties": { + "URI": { + "type": "string", + "title": "Interaction URI", + "description": "Can be used by a target application to pass a record's link back to the originating application. This offers the originating application a way to open the record for a user to view." + }, + "SALESFORCE": { + "type": "string", + "title": "Salesforce ID", + "description": "Interactions ID in Salesforce" + }, + "SINGLETRACK": { + "type": "string", + "title": "SingleTrack ID", + "description": "Interaction ID in SingleTrack" + } + } + }, + "participants": { + "title": "Interaction Participants", + "description": "A list of contacts involved in the interaction", + "$ref": "contactList.schema.json#" + }, + "timeRange": { + "title": "Interaction Time range", + "description": "The time range over which the interaction occurred", + "$ref": "timerange.schema.json#" + }, + "interactionType": { + "title": "Interaction Type", + "description": "`interactionType` SHOULD be one of `'Instant Message'`, `'Email'`, `'Call'`, or `'Meeting'` although other string values are permitted.", + "anyOf": [ + { + "type": "string", + "enum": [ + "Instant Message", + "Email", + "Call", + "Meeting" + ] + }, + { + "type": "string" + } + ] }, - { + "description": { + "title": "Interaction Description", + "description": "A human-readable description of the interaction", + "type": "string" + }, + "initiator": { + "title": "Interaction Initiator", + "description": "The contact that initiated the interaction", + "$ref": "contact.schema.json#" + }, + "origin": { + "title": "Interaction Origin", + "description": "Used to represent the application or service that the interaction was created from to aid in tracing the source of an interaction.", "type": "string" } + }, + "required": [ + "participants", + "timeRange", + "interactionType", + "description" ] }, - "description": { - "type": "string" - }, - "initiator": { - "$ref": "contact.schema.json#" - }, - "origin": { - "type": "string" + { "$ref": "context.schema.json#/definitions/BaseContext" } + ], + "examples": [ + { + "type": "fdc3.interaction", + "participants": { + "type": "fdc3.contactList", + "contacts": [ + { + "type": "fdc3.contact", + "name": "Jane Doe", + "id": { + "email": "jane.doe@mail.com" + } + }, + { + "type": "fdc3.contact", + "name": "John Doe", + "id": { + "email": "john.doe@mail.com" + } + } + ] + }, + "interactionType": "Instant Message", + "timeRange": { + "type": "fdc3.timeRange", + "startTime": "2022-02-10T15:12:00Z" + }, + "description": "Laboris libero dapibus fames elit adipisicing eu, fermentum, dignissimos laboriosam, erat, risus qui deserunt. Praesentium! Reiciendis. Hic harum nostrud, harum potenti amet? Mauris. Pretium aliquid animi, eget eiusmod integer proident. Architecto ipsum blandit ducimus, possimus illum sunt illum necessitatibus ab litora sed, nonummy integer minus corrupti ducimus iste senectus accumsan, fugiat nostrud? Pede vero dictumst excepturi, iure earum consequuntur voluptatum", + "initiator": { + "type": "fdc3.contact", + "name": "Jane Doe", + "id": { + "email": "jane.doe@mail.com" + } + }, + "origin": "Outlook" } - }, - "required": ["participants", "timeRange", "interactionType", "description"] + ] } \ No newline at end of file diff --git a/schemas/context/message.schema.json b/schemas/context/message.schema.json index 9d2050b7b..b776eb11e 100644 --- a/schemas/context/message.schema.json +++ b/schemas/context/message.schema.json @@ -3,53 +3,118 @@ "$id": "https://fdc3.finos.org/schemas/next/context/message.schema.json", "type": "object", "title": "Message", - "allOf": [{ "$ref": "context.schema.json#" }], - "properties": { - "type": { "const": "fdc3.message" }, - "text": { + "description": "A chat message to be sent through an instant messaging application. Can contain one or several text bodies (organized by mime-type, plaintext or markdown), as well as attached entities (either arbitrary file attachments or FDC3 actions to be embedded in the message). To be put inside a ChatInitSettings object.", + "allOf": [ + { "type": "object", "properties": { - "text/plain": { - "type": "string" + "type": { + "const": "fdc3.message" }, - "text/markdown": { - "type": "string" - } - } - }, - "entities": { - "type": "object", - "additionalProperties": { - "anyOf": [ - { - "$ref": "action.schema.json#" - }, - { - "type": "object", - "properties": { - "type": { - "const": "fdc3.entity.fileAttachment" + "text": { + "type": "object", + "title": "Message text", + "description": "A map of string mime-type to string content", + "properties": { + "text/plain": { + "type": "string", + "title": "Plain text", + "description": "Plain text encoded content." + }, + "text/markdown": { + "title": "Markdown text", + "description": "Markdown encoded content", + "type": "string" + } + } + }, + "entities": { + "type": "object", + "title": "Message entities", + "description": "A map of string IDs to entities that should be attached to the message, such as an action to perform, a file attachment, or other FDC3 context object.", + "additionalProperties": { + "anyOf": [ + { + "$ref": "action.schema.json#" }, - "data": { + { "type": "object", + "title": "File attachment", + "description": "A File attachment encoded in the form of a data URI", "properties": { - "name": { - "type": "string" + "type": { + "const": "fdc3.entity.fileAttachment" }, - "dataUri": { - "type": "string" + "data": { + "type": "object", + "properties": { + "name": { + "type": "string", + "title": "File name", + "description": "The name of the attached file" + }, + "dataUri": { + "type": "string", + "format": "uri", + "title": "", + "description": "A data URI encoding the content of the file to be attached" + } + }, + "required": [ + "name", + "dataUri" + ] } }, "required": [ - "name", - "dataUri" + "type", + "data" ] } + ] + } + } + } + }, + { "$ref": "context.schema.json#/definitions/BaseContext" } + ], + "examples": [ + { + "type": "fdc3.message", + "text": { + "text/plain": "Hey all, can we discuss the issue together? I attached a screenshot and a link to the current exchange rate" + }, + "entities": { + "picture1": { + "type": "fdc3.fileAttachment", + "data": { + "name": "myImage.png", + "dataUri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII" + } + }, + "eurusd_action": { + "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" }, - "required": ["type", "data"] + "style": "candle" } - ] + } } } - } -} + ] +} \ No newline at end of file diff --git a/schemas/context/nothing.schema.json b/schemas/context/nothing.schema.json index a7d67095e..2b970c895 100644 --- a/schemas/context/nothing.schema.json +++ b/schemas/context/nothing.schema.json @@ -3,8 +3,21 @@ "$id": "https://fdc3.finos.org/schemas/next/context/nothing.schema.json", "type": "object", "title": "Nothing", - "allOf": [{ "$ref": "context.schema.json#" }], - "properties": { - "type": { "const": "fdc3.nothing" } - } -} + "description": "A type that explicitly represents a lack of context.\n\nNotes:\n\n- Intended to be used in situations where no context is desired.\n- For example:\n - Raising an intent without context (e.g. opening a blank order form, or chat interface without a contact selected).\n - Resetting context on a channel (e.g. when context is used to set a filter in other applications a null context might release the filter).\n- An explicit representation of a Null or empty context allows apps to declare support for a lack of context, for example in their intent metadata in an app directory.", + "allOf": [ + { + "type": "object", + "properties": { + "type": { + "const": "fdc3.nothing" + } + } + }, + { "$ref": "context.schema.json#/definitions/BaseContext" } + ], + "examples": [ + { + "type": "fdc3.nothing" + } + ] +} \ No newline at end of file diff --git a/schemas/context/order.schema.json b/schemas/context/order.schema.json index baa8381b9..fcf975011 100644 --- a/schemas/context/order.schema.json +++ b/schemas/context/order.schema.json @@ -1,74 +1,76 @@ { - "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://fdc3.finos.org/schemas/next/context/order.schema.json", - "type": "object", - "title": "Order", - "description": "@experimental context type representing an order. To be used with OMS and EMS systems.\n\nThis type currently only defines a required `id` field, which should provide a reference to the order in one or more systems, an optional human readable `name` field to be used to summarize the order and an optional `details` field that may be used to provide additional detail about the order, including a context representing a `product`, which may be extended with arbitrary properties. The `details.product` field is currently typed as a unspecified Context type, but both `details` and `details.product` are expected to be standardized in future.", - "allOf": [ - { - "$ref": "context.schema.json#" - } - ], - "properties": { - "type": { - "const": "fdc3.order" - }, - "id": { - "type": "object", - "additionalProperties": { - "type": "string" - }, - "title": "Order Identifiers", - "description": "One or more identifiers that refer to the order in an OMS, EMS or related system. Specific key names for systems are expected to be standardized in future." - }, - "name": { - "type": "string", - "title": "Name", - "description": "An optional human-readable summary of the order." - }, - "details": { - "type": "object", - "title": "Order Details", - "description": "Optional additional details about the order, which may include a product element that is an, as yet undefined but extensible, Context", - "properties": { - "product": { - "$ref": "product.schema.json" - } - }, - "additionalProperties": true - } - }, - "required": [ - "type", "id" - ], - "additionalProperties": true, - "examples": [ - { - "type": "fdc3.order", - "name": "...", - "id": { - "myOMS": "12345" - }, - "details": { - "product": { - "type": "fdc3.product", - "id": { - "productId": "ABC123" - }, - "instrument": { - "type": "fdc3.instrument", - "id": { - "ticker": "MSFT" - } - } - } - } - }, - { - "type": "fdc3.order", - "id": { - "myOMS": "ABC123" - } - } - ] -} + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://fdc3.finos.org/schemas/next/context/order.schema.json", + "type": "object", + "title": "Order", + "description": "@experimental context type representing an order. To be used with OMS and EMS systems.\n\nThis type currently only defines a required `id` field, which should provide a reference to the order in one or more systems, an optional human readable `name` field to be used to summarize the order and an optional `details` field that may be used to provide additional detail about the order, including a context representing a `product`, which may be extended with arbitrary properties. The `details.product` field is currently typed as a unspecified Context type, but both `details` and `details.product` are expected to be standardized in future.", + "allOf": [ + { + "type": "object", + "properties": { + "type": { + "const": "fdc3.order" + }, + "id": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "title": "Order Identifiers", + "description": "One or more identifiers that refer to the order in an OMS, EMS or related system. Specific key names for systems are expected to be standardized in future." + }, + "name": { + "type": "string", + "title": "Name", + "description": "An optional human-readable summary of the order." + }, + "details": { + "type": "object", + "title": "Order Details", + "description": "Optional additional details about the order, which may include a product element that is an, as yet undefined but extensible, Context", + "properties": { + "product": { + "$ref": "product.schema.json" + } + }, + "additionalProperties": true + } + }, + "required": [ + "type", + "id" + ], + "additionalProperties": true + }, + { "$ref": "context.schema.json#/definitions/BaseContext" } + ], + "examples": [ + { + "type": "fdc3.order", + "name": "...", + "id": { + "myOMS": "12345" + }, + "details": { + "product": { + "type": "fdc3.product", + "id": { + "productId": "ABC123" + }, + "instrument": { + "type": "fdc3.instrument", + "id": { + "ticker": "MSFT" + } + } + } + } + }, + { + "type": "fdc3.order", + "id": { + "myOMS": "ABC123" + } + } + ] +} \ No newline at end of file diff --git a/schemas/context/orderList.schema.json b/schemas/context/orderList.schema.json index bfc532e32..b282ce3e0 100644 --- a/schemas/context/orderList.schema.json +++ b/schemas/context/orderList.schema.json @@ -3,14 +3,47 @@ "$id": "https://fdc3.finos.org/schemas/next/context/orderList.schema.json", "type": "object", "title": "OrderList", - "description": "@experimental A list of orders", - "allOf": [{ "$ref": "context.schema.json#" }], - "properties": { - "type": { "const": "fdc3.orderList" }, - "orders": { - "type": "array", - "items": { "$ref": "order.schema.json#" } + "description": "@experimental A list of orders. Use this type for use cases that require not just a single order, but multiple.\n\nThe OrderList 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.", + "allOf": [ + { + "type": "object", + "properties": { + "type": { + "const": "fdc3.orderList" + }, + "orders": { + "type": "array", + "items": { + "$ref": "order.schema.json#" + }, + "title": "List of Orders", + "description": "An array of order contexts that forms the list." + } + }, + "required": [ + "type", + "orders" + ] + }, + { "$ref": "context.schema.json#/definitions/BaseContext" } + ], + "examples": [ + { + "type": "fdc3.orderList", + "orders": [ + { + "type": "fdc3.order", + "id": { + "myOMS": "ABC123" + } + }, + { + "type": "fdc3.order", + "id": { + "myOMS": "DEF456" + } + } + ] } - }, - "required": ["type", "orders"] -} + ] +} \ No newline at end of file diff --git a/schemas/context/organization.schema.json b/schemas/context/organization.schema.json index 7a791496e..84716863c 100644 --- a/schemas/context/organization.schema.json +++ b/schemas/context/organization.schema.json @@ -3,17 +3,52 @@ "$id": "https://fdc3.finos.org/schemas/next/context/organization.schema.json", "type": "object", "title": "Organization", - "allOf": [{ "$ref": "context.schema.json#" }], - "properties": { - "type": { "const": "fdc3.organization" }, - "id": { + "description": "An entity that can be used when referencing private companies and other organizations where a specific instrument is not available or desired e.g. CRM and News workflows.\n\nIt is valid to include extra properties and metadata as part of the organization payload, but the minimum requirement is for at least one specified identifier to be provided.", + "allOf": [ + { "type": "object", "properties": { - "LEI": { "type": "string" }, - "PERMID": { "type": "string" }, - "FDS_ID": { "type": "string" } + "type": { + "const": "fdc3.organization" + }, + "id": { + "type": "object", + "title": "Organization Identifiers", + "description": "Identifiers for the organization, at least one must be provided.", + "minProperties": 1, + "properties": { + "LEI": { + "type": "string", + "title": "Legal Entity Identifier", + "description": "The Legal Entity Identifier (LEI) is a 20-character, alpha-numeric code based on the ISO 17442 standard developed by the International Organization for Standardization (ISO). It connects to key reference information that enables clear and unique identification of legal entities participating in financial transactions." + }, + "PERMID": { + "type": "string", + "title": "Organization", + "description": "Refinitiv Permanent Identifiers, or PermID for the organization" + }, + "FDS_ID": { + "type": "string", + "title": "Organization", + "description": "FactSet Permanent Identifier representing the organization" + } + } + } + }, + "required": [ + "id" + ] + }, + { "$ref": "context.schema.json#/definitions/BaseContext" } + ], + "examples": [ + { + "type": "fdc3.organization", + "name": "Cargill, Incorporated", + "id": { + "LEI": "QXZYQNMR4JZ5RIRN4T31", + "FDS_ID": "00161G-E" } } - }, - "required": ["id"] + ] } diff --git a/schemas/context/portfolio.schema.json b/schemas/context/portfolio.schema.json index 64202e02f..c2a69a194 100644 --- a/schemas/context/portfolio.schema.json +++ b/schemas/context/portfolio.schema.json @@ -3,13 +3,64 @@ "$id": "https://fdc3.finos.org/schemas/next/context/portfolio.schema.json", "type": "object", "title": "Portfolio", - "allOf": [{ "$ref": "context.schema.json#" }], - "properties": { - "type": { "const": "fdc3.portfolio" }, - "positions": { - "type": "array", - "items": { "$ref": "position.schema.json#" } + "description": "A financial portfolio made up of multiple positions (holdings) in several instruments. Contrast this with e.g. the [InstrumentList](InstrumentList) type, which is just a list of instruments.\n\nThis is a good example of how types can be composed and extended with extra properties to define more complex types.\n\nThe Portfolio type consists of an array of [Position](Position) types, each of which refers to a single [Instrument](Instrument) and a holding amount for that instrument.\n\nThe portfolio schema does not explicitly include identifiers in the `id` section, as there bis not a common standard for such identifiers. Applications can, however, populate this part of the contract with custom identifiers if so desired.", + "allOf": [ + { + "type": "object", + "properties": { + "type": { + "const": "fdc3.portfolio" + }, + "positions": { + "type": "array", + "items": { + "$ref": "position.schema.json#" + }, + "title": "Portfolio positions", + "description": "The List of Positions which make up the Portfolio" + } + }, + "required": [ + "positions" + ] + }, + { "$ref": "context.schema.json#/definitions/BaseContext" } + ], + "examples": [ + { + "type": "fdc3.portfolio", + "positions": [ + { + "type": "fdc3.position", + "instrument": { + "type": "fdc3.instrument", + "id": { + "ticker": "AAPL" + } + }, + "holding": 2000000 + }, + { + "type": "fdc3.position", + "instrument": { + "type": "fdc3.instrument", + "id": { + "ticker": "MSFT" + } + }, + "holding": 1500000 + }, + { + "type": "fdc3.position", + "instrument": { + "type": "fdc3.instrument", + "id": { + "ticker": "IBM" + } + }, + "holding": 3000000 + } + ] } - }, - "required": ["positions"] -} + ] +} \ No newline at end of file diff --git a/schemas/context/position.schema.json b/schemas/context/position.schema.json index e2a948aee..4e90bcec5 100644 --- a/schemas/context/position.schema.json +++ b/schemas/context/position.schema.json @@ -3,12 +3,42 @@ "$id": "https://fdc3.finos.org/schemas/next/context/position.schema.json", "type": "object", "title": "Position", - "allOf": [{ "$ref": "context.schema.json#" }], - "properties": { - "type": { "const": "fdc3.position" }, - "instrument": { "$ref": "instrument.schema.json#" }, - "holding": { "type": "number" } - }, - "required": ["instrument", "holding"] -} - + "description": "A financial position made up of an instrument and a holding in that instrument. This type is a good example of how new context types can be composed from existing types.\n\nIn this case, the instrument and the holding amount for that instrument are required values.\n\nThe [Position](Position) type goes hand-in-hand with the [Portfolio](Portfolio) type, which represents multiple holdings in a combination of instruments.\n\nThe position 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.", + "allOf": [ + { + "type": "object", + "properties": { + "type": { + "const": "fdc3.position" + }, + "instrument": { + "$ref": "instrument.schema.json#", + "title": "The financial instrument that this position relates to", + "description": "" + }, + "holding": { + "type": "number", + "title": "The size of the holding represented by this position", + "description": "The amount of the holding, e.g. a number of shares" + } + }, + "required": [ + "instrument", + "holding" + ] + }, + { "$ref": "context.schema.json#/definitions/BaseContext" } + ], + "examples": [ + { + "type": "fdc3.position", + "instrument": { + "type": "fdc3.instrument", + "id": { + "ticker": "AAPL" + } + }, + "holding": 2000000 + } + ] +} \ No newline at end of file diff --git a/schemas/context/product.schema.json b/schemas/context/product.schema.json index a1571d4f9..df20ae614 100644 --- a/schemas/context/product.schema.json +++ b/schemas/context/product.schema.json @@ -3,11 +3,9 @@ "$id": "https://fdc3.finos.org/schemas/next/context/product.schema.json", "type": "object", "title": "Product", - "description": "@experimental context type representing a tradable product. To be used with OMS and EMS systems.\n\nThis type is currently only loosely defined as an extensible context object, with an optional instrument field.", + "description": "@experimental context type representing a tradable product. To be used with OMS and EMS systems.\n\nThis type is currently only loosely defined as an extensible context object, with an optional instrument field.\n\nThe 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.", "allOf": [ { - "$ref": "context.schema.json#" - },{ "type": "object", "properties": { "type": { @@ -23,16 +21,22 @@ }, "name": { "type": "string", - "title": "Name", + "title": "Product Name", "description": "A human-readable summary of the product." - }, + }, "instrument": { - "$ref": "instrument.schema.json" + "$ref": "instrument.schema.json", + "title": "Product Instrument", + "description": " financial instrument that relates to the definition of this product" } }, - "required": ["type","id"], + "required": [ + "type", + "id" + ], "additionalProperties": true - } + }, + { "$ref": "context.schema.json#/definitions/BaseContext" } ], "examples": [ { @@ -48,4 +52,4 @@ } } ] -} +} \ No newline at end of file diff --git a/schemas/context/timerange.schema.json b/schemas/context/timerange.schema.json index 5b6b326f5..442dd3b11 100644 --- a/schemas/context/timerange.schema.json +++ b/schemas/context/timerange.schema.json @@ -3,22 +3,60 @@ "$id": "https://fdc3.finos.org/schemas/next/context/timerange.schema.json", "type": "object", "title": "TimeRange", - "allOf": [{ "$ref": "context.schema.json#" }], + "description": "A context representing a period of time. Any user interfaces that represent or visualize events or activity over time can be filtered or focused on a particular time period, e.g.:\n\n- A pricing chart\n- A trade blotter\n- A record of client contact/activity in a CRM\n\nExample use cases:\n\n- User may want to view pricing/trades/customer activity for a security over a particular time period, the time range might be specified as the context for the `ViewChart` intent OR it might be embedded in another context (e.g. a context representing a chart to plot).\n- User filters a visualization (e.g. a pricing chart) to show a particular period, the `TimeRange` is broadcast and other visualizations (e.g. a heatmap of activity by instrument, or industry sector etc.) receive it and filter themselves to show data over the same range.\n\nNotes:\n\n- A `TimeRange` may be closed (i.e. `startTime` and `endTime` are both known) or open (i.e. only one of `startTime` or `endTime` is known).\n- Ranges corresponding to dates (e.g. `2022-05-12` to `2022-05-19`) should be specified using times as this prevents issues with timezone conversions and inclusive/exclusive date ranges.\n- String fields representing times are encoded according to [ISO 8601-1:2019](https://www.iso.org/standard/70907.html).\n - A timezone indicator should be specified, e.g. `\"2022-05-12T15:18:03Z\"` or `\"2022-05-12T16:18:03+01:00\"`\n - Times MAY be specified with millisecond precision, e.g. `\"2022-05-12T15:18:03.349Z\"`", + "allOf": [ + { + "properties": { + "type": { + "const": "fdc3.timerange" + }, + "startTime": { + "type": "string", + "format": "date-time", + "title": "Start Time", + "description": "The start time of the range, encoded according to [ISO 8601-1:2019](https://www.iso.org/standard/70907.html) with a timezone indicator." + }, + "endTime": { + "type": "string", + "format": "date-time", + "title": "End Time", + "description": "The end time of the range, encoded according to [ISO 8601-1:2019](https://www.iso.org/standard/70907.html) with a timezone indicator." + } + } + }, + { "$ref": "context.schema.json#/definitions/BaseContext" } + ], "anyOf": [ { - "required": ["startTime", "endTime"] + "required": [ + "startTime", + "endTime" + ] }, { - "required": ["startTime"] + "required": [ + "startTime" + ] }, { - "required": ["endTime"] + "required": [ + "endTime" + ] } ], - "properties": { - "type": { "const": "fdc3.timerange" }, - "startTime": { "type": "string", "format": "date-time" }, - "endTime": {"type": "string", "format": "date-time" } - }, - "required": [] -} + "examples": [ + { + "type": "fdc3.timeRange", + "startTime": "2022-03-30T15:44:44Z", + "endTime": "2022-04-30T23:59:59ZS" + }, + { + "type": "fdc3.timeRange", + "startTime": "2022-03-30T15:44:44+00:00" + }, + { + "type": "fdc3.timeRange", + "endTime": "2022-03-30T16:44:44.123Z" + } + ] +} \ No newline at end of file diff --git a/schemas/context/trade.schema.json b/schemas/context/trade.schema.json index 10a108c31..e8286ae52 100644 --- a/schemas/context/trade.schema.json +++ b/schemas/context/trade.schema.json @@ -3,37 +3,40 @@ "$id": "https://fdc3.finos.org/schemas/next/context/trade.schema.json", "type": "object", "title": "Trade", - "description": "@experimental context type representing a trade. To be used with execution systems.\n\nThis type currently only defines a required `id` field, which should provide a reference to the trade in one or more systems, an optional human readable `name` field to be used to summarize the trade and a required `product` field that may be used to provide additional detail about the trade, which is currently typed as a unspecified Context type, but `product` is expected to be standardized in future.", + "description": "@experimental context type representing a trade. To be used with execution systems.\n\nThis type currently only defines a required `id` field, which should provide a reference to the trade in one or more systems, an optional human readable `name` field to be used to summarize the trade and a required `product` field that may be used to provide additional detail about the trade, which is currently typed as a unspecified Context type, but `product` is expected to be standardized in future.\n\n The Trade 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.", "allOf": [ { - "$ref": "context.schema.json#" - } - ], - "properties": { - "type": { - "const": "fdc3.trade" - }, - "id": { "type": "object", - "additionalProperties": { - "type": "string" + "properties": { + "type": { + "const": "fdc3.trade" + }, + "id": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "title": "Trade Identifiers", + "description": "One or more identifiers that refer to the trade in an OMS, EMS or related system. Specific key names for systems are expected to be standardized in future." + }, + "name": { + "type": "string", + "title": "Trade Name", + "description": "A human-readable summary of the trade." + }, + "product": { + "$ref": "product.schema.json", + "title": "Traded product", + "description": "A product that is the subject of th trade." + } }, - "title": "Trade Identifiers", - "description": "One or more identifiers that refer to the trade in an OMS, EMS or related system. Specific key names for systems are expected to be standardized in future." + "required": [ + "type", "id", "product" + ], + "additionalProperties": true }, - "name": { - "type": "string", - "title": "Name", - "description": "A human-readable summary of the trade." - }, - "product": { - "$ref": "product.schema.json" - } - }, - "required": [ - "type", "id", "product" + { "$ref": "context.schema.json#/definitions/BaseContext" } ], - "additionalProperties": true, "examples": [ { "type": "fdc3.trade", diff --git a/schemas/context/tradeList.schema.json b/schemas/context/tradeList.schema.json index 49d8b0d27..dee810127 100644 --- a/schemas/context/tradeList.schema.json +++ b/schemas/context/tradeList.schema.json @@ -3,14 +3,72 @@ "$id": "https://fdc3.finos.org/schemas/next/context/tradeList.schema.json", "type": "object", "title": "TradeList", - "description": "@experimental A list of trades.", - "allOf": [{ "$ref": "context.schema.json#" }], - "properties": { - "type": { "const": "fdc3.tradeList" }, - "trades": { - "type": "array", - "items": { "$ref": "trade.schema.json#" } + "description": "@experimental A list of trades. Use this type for use cases that require not just a single trade, but multiple.\n\nThe TradeList 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.", + "allOf": [ + { + "type": "object", + "properties": { + "type": { + "const": "fdc3.tradeList" + }, + "trades": { + "type": "array", + "items": { + "$ref": "trade.schema.json#" + }, + "title": "List of Trades", + "description": "An array of trade contexts that forms the list." + } + }, + "required": [ + "type", + "trades" + ] + }, + { "$ref": "context.schema.json#/definitions/BaseContext" } + ], + "examples": [ + { + "type": "fdc3.tradeList", + "trades": [ + { + "type": "fdc3.trade", + "name": "...", + "id": { + "myEMS": "12345" + }, + "product": { + "type": "fdc3.product", + "id": { + "productId": "ABC123" + }, + "instrument": { + "type": "fdc3.instrument", + "id": { + "ticker": "MSFT" + } + } + } + }, + { + "type": "fdc3.trade", + "id": { + "myEMS": "67890" + }, + "product": { + "type": "fdc3.product", + "id": { + "productId": "DEF456" + }, + "instrument": { + "type": "fdc3.instrument", + "id": { + "ticker": "TSLA" + } + } + } + } + ] } - }, - "required": ["type", "trades"] -} + ] +} \ No newline at end of file diff --git a/schemas/context/transactionresult.schema.json b/schemas/context/transactionresult.schema.json index 11370018e..2a8cca61c 100644 --- a/schemas/context/transactionresult.schema.json +++ b/schemas/context/transactionresult.schema.json @@ -3,17 +3,55 @@ "$id": "https://fdc3.finos.org/schemas/next/context/transactionresult.schema.json", "type": "object", "title": "TransactionResult", - "allOf": [{ "$ref": "context.schema.json#" }], - "properties": { - "type": { "const": "fdc3.transactionResult" }, - "status": { + "description": "A context type representing the result of a transaction initiated via FDC3, which SHOULD be returned as an `IntentResult` by intents that create, retrieve, update or delete content or records in another application. Its purpose is to provide a status and message (where needed) for the transaction and MAY wrap a returned context object.", + "allOf": [ + { + "type": "object", + "properties": { + "type": { + "const": "fdc3.transactionResult" + }, + "status": { "type": "string", - "enum": ["Created", "Deleted", "Updated", "Failed"] + "enum": [ + "Created", + "Deleted", + "Updated", + "Failed" + ], + "title": "Transaction Status", + "description": "The status of the transaction being reported." }, - "context": { "$ref": "context.schema.json#" } - }, - "message": { - "type": "string" + "context": { + "$ref": "context.schema.json#", + "title": "Transaction Result Context", + "description": "A context object returned by the transaction, possibly with updated data." + } + }, + "message": { + "type": "string", + "title": "Transaction Message", + "description": "A human readable message describing the outcome of the transaction." + }, + "required": [ + "type", + "status" + ] }, - "required": ["type", "status"] + { "$ref": "context.schema.json#/definitions/BaseContext" } + ], + "examples": [ + { + "type": "fdc3.transactionResult", + "status": "Updated", + "context": { + "type": "fdc3.contact", + "name": "Jane Doe", + "id": { + "email": "jane.doe@mail.com" + } + }, + "message": "record with id 'jane.doe@mail.com' was updated" + } + ] } \ No newline at end of file diff --git a/schemas/context/valuation.schema.json b/schemas/context/valuation.schema.json index 7ad55be71..712764483 100644 --- a/schemas/context/valuation.schema.json +++ b/schemas/context/valuation.schema.json @@ -3,14 +3,57 @@ "$id": "https://fdc3.finos.org/schemas/next/context/valuation.schema.json", "type": "object", "title": "Valuation", - "allOf": [{ "$ref": "context.schema.json#" }], - "properties": { - "type": { "const": "fdc3.valuation" }, - "value": { "type": "number" }, - "price": { "type": "number"}, - "CURRENCY_ISOCODE": { "type": "string", "pattern": "^[A-Z]{3}$" }, - "valuationTime": {"type": "string", "format": "date-time" }, - "expiryTime": {"type": "string", "format": "date-time" } - }, - "required": ["value", "CURRENCY_ISOCODE"] -} + "description": "A context type representing the price and value of a holding.", + "allOf": [ + { + "type": "object", + "properties": { + "type": { + "const": "fdc3.valuation" + }, + "value": { + "type": "number", + "title": "Value", + "description": "The value of the holding, expresses in the nominated currency." + }, + "price": { + "type": "number", + "title": "Price per unit", + "description": "The price per unit the the valuation is based on." + }, + "CURRENCY_ISOCODE": { + "type": "string", + "pattern": "^[A-Z]{3}$", + "title": "Valuation Currency", + "description": "The valuation currency, which should conform to 3 character alphabetic codes defined in [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html)" + }, + "valuationTime": { + "type": "string", + "format": "date-time", + "title": "Valuation time", + "description": "The time at which the valuation was performed, encoded according to [ISO 8601-1:2019](https://www.iso.org/standard/70907.html) with a timezone indicator included." + }, + "expiryTime": { + "type": "string", + "format": "date-time", + "title": "Expiry Time", + "description": "The time at which this valuation expires, encoded according to [ISO 8601-1:2019](https://www.iso.org/standard/70907.html) with a timezone indicator included." + } + }, + "required": [ + "value", + "CURRENCY_ISOCODE" + ] + }, + { "$ref": "context.schema.json#/definitions/BaseContext" } + ], + "examples": [ + { + "type": "fdc3.valuation", + "value": 500.0, + "price": 5.0, + "CURRENCY_ISOCODE": "USD", + "expiryTime": "2022-05-13T16:16:24+01:00" + } + ] +} \ No newline at end of file diff --git a/src/bridging/BridgingTypes.ts b/src/bridging/BridgingTypes.ts index 05e7884a7..eb6363f9f 100644 --- a/src/bridging/BridgingTypes.ts +++ b/src/bridging/BridgingTypes.ts @@ -648,10 +648,55 @@ export interface BroadcastAgentRequestPayload { /** * The context object that was the payload of a broadcast message. + * + * 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. + * + * The 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. + * + * The 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. */ export interface ContextElement { + /** + * Context data objects may include a set of equivalent key-value pairs that can be used to + * help applications identify and look up the context type they receive in their own domain. + * The idea behind this design is that applications can provide as many equivalent + * identifiers to a target application as possible, e.g. an instrument may be represented by + * an ISIN, CUSIP or Bloomberg identifier. + * + * Identifiers do not make sense for all types of data, so the `id` property is therefore + * optional, but some derived types may choose to require at least one identifier. + */ id?: { [key: string]: any }; + /** + * Context data objects may include a name property that can be used for more information, + * or display purposes. Some derived types may require the name object as mandatory, + * depending on use case. + */ name?: string; + /** + * The type property is the only _required_ part of the FDC3 context data schema. The FDC3 + * [API](https://fdc3.finos.org/docs/api/spec) relies on the `type` property being present + * to route shared context data appropriately. + * + * FDC3 [Intents](https://fdc3.finos.org/docs/intents/spec) also register the context data + * types they support in an FDC3 [App + * Directory](https://fdc3.finos.org/docs/app-directory/overview), used for intent discovery + * and routing. + * + * Standardized FDC3 context types have well-known `type` properties prefixed with the + * `fdc3` namespace, e.g. `fdc3.instrument`. For non-standard types, e.g. those defined and + * used by a particular organization, the convention is to prefix them with an + * organization-specific namespace, e.g. `blackrock.fund`. + * + * See the [Context Data Specification](https://fdc3.finos.org/docs/context/spec) for more + * information about context data types. + */ type: string; [property: string]: any; } @@ -3878,9 +3923,55 @@ export interface RaiseIntentResultBridgeResponsePayload { intentResult: IntentResult; } +/** + * 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. + * + * The 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. + * + * The 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. + */ export interface Context { + /** + * Context data objects may include a set of equivalent key-value pairs that can be used to + * help applications identify and look up the context type they receive in their own domain. + * The idea behind this design is that applications can provide as many equivalent + * identifiers to a target application as possible, e.g. an instrument may be represented by + * an ISIN, CUSIP or Bloomberg identifier. + * + * Identifiers do not make sense for all types of data, so the `id` property is therefore + * optional, but some derived types may choose to require at least one identifier. + */ id?: { [key: string]: any }; + /** + * Context data objects may include a name property that can be used for more information, + * or display purposes. Some derived types may require the name object as mandatory, + * depending on use case. + */ name?: string; + /** + * The type property is the only _required_ part of the FDC3 context data schema. The FDC3 + * [API](https://fdc3.finos.org/docs/api/spec) relies on the `type` property being present + * to route shared context data appropriately. + * + * FDC3 [Intents](https://fdc3.finos.org/docs/intents/spec) also register the context data + * types they support in an FDC3 [App + * Directory](https://fdc3.finos.org/docs/app-directory/overview), used for intent discovery + * and routing. + * + * Standardized FDC3 context types have well-known `type` properties prefixed with the + * `fdc3` namespace, e.g. `fdc3.instrument`. For non-standard types, e.g. those defined and + * used by a particular organization, the convention is to prefix them with an + * organization-specific namespace, e.g. `blackrock.fund`. + * + * See the [Context Data Specification](https://fdc3.finos.org/docs/context/spec) for more + * information about context data types. + */ type: string; [property: string]: any; } diff --git a/src/context/ContextTypes.ts b/src/context/ContextTypes.ts index a4b1ab99e..4811bb906 100644 --- a/src/context/ContextTypes.ts +++ b/src/context/ContextTypes.ts @@ -38,14 +38,36 @@ // These functions will throw an error if the JSON doesn't // match the expected interface, even if the JSON is valid. +/** + * 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 specific app. + */ export interface Action { - app?: ActionApp; - context: ActionContext; - customConfig?: { [key: string]: any }; /** - * A reference an intent type name, such as those defined in the FDC3 Standard + * An optional target application identifier that should perform the action + */ + app?: ActionTargetApp; + /** + * A context object with which the action will be performed + */ + context: ContextElement; + /** + * 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. */ intent?: string; + /** + * A human readable display name for the action + */ title: string; type: string; id?: { [key: string]: any }; @@ -53,68 +75,294 @@ export interface Action { [property: string]: any; } -export interface ActionApp { +/** + * An optional target application identifier that should perform the action + * + * Identifies an application, or instance of an application, and is used to target FDC3 API + * calls, such as `fdc3.open` or `fdc3.raiseIntent` at specific applications or application + * instances. + * + * Will always include at least an `appId` field, which uniquely identifies a specific app. + * + * If the `instanceId` field is set then the `AppMetadata` object represents a specific + * instance of the application that may be addressed using that Id. + */ +export interface ActionTargetApp { + /** + * The unique application identifier located within a specific application directory + * instance. An example of an appId might be 'app@sub.root' + */ appId: string; + /** + * The Desktop Agent that the app is available on. Used in Desktop Agent Bridging to + * identify the Desktop Agent to target. + */ + desktopAgent?: string; + /** + * An optional instance identifier, indicating that this object represents a specific + * instance of the application described. + */ instanceId?: string; [property: string]: any; } -export interface ActionContext { +/** + * A context object with which the action will be performed + * + * A context object returned by the transaction, possibly with updated data. + * + * 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. + * + * The 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. + * + * The 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. + */ +export interface ContextElement { + /** + * Context data objects may include a set of equivalent key-value pairs that can be used to + * help applications identify and look up the context type they receive in their own domain. + * The idea behind this design is that applications can provide as many equivalent + * identifiers to a target application as possible, e.g. an instrument may be represented by + * an ISIN, CUSIP or Bloomberg identifier. + * + * Identifiers do not make sense for all types of data, so the `id` property is therefore + * optional, but some derived types may choose to require at least one identifier. + */ id?: { [key: string]: any }; + /** + * Context data objects may include a name property that can be used for more information, + * or display purposes. Some derived types may require the name object as mandatory, + * depending on use case. + */ name?: string; + /** + * The type property is the only _required_ part of the FDC3 context data schema. The FDC3 + * [API](https://fdc3.finos.org/docs/api/spec) relies on the `type` property being present + * to route shared context data appropriately. + * + * FDC3 [Intents](https://fdc3.finos.org/docs/intents/spec) also register the context data + * types they support in an FDC3 [App + * Directory](https://fdc3.finos.org/docs/app-directory/overview), used for intent discovery + * and routing. + * + * Standardized FDC3 context types have well-known `type` properties prefixed with the + * `fdc3` namespace, e.g. `fdc3.instrument`. For non-standard types, e.g. those defined and + * used by a particular organization, the convention is to prefix them with an + * organization-specific namespace, e.g. `blackrock.fund`. + * + * See the [Context Data Specification](https://fdc3.finos.org/docs/context/spec) for more + * information about context data types. + */ type: string; [property: string]: any; } +/** + * A context type representing details of a Chart, which may be used to request plotting of + * a particular chart or to otherwise share details of its composition, such as: + * + * - A list of instruments for comparison + * - The time period to plot the chart over + * - The style of chart (line, bar, mountain, candle etc.) + * - Other settings such as indicators to calculate, or data representing drawings and + * annotations. + * + * In addition to handling requests to plot charts, a charting application may use this type + * to output a representation of what it is currently displaying so that it can be recorded + * by another application. + */ export interface Chart { + /** + * An array of instrument contexts whose data should be plotted. + */ instruments: InstrumentElement[]; + /** + * It is common for charts to support other configuration, such as indicators, annotations + * etc., which do not have standardized formats, but may be included in the `otherConfig` + * array as context objects. + */ otherConfig?: ContextElement[]; + /** + * The time range that should be plotted + */ range?: TimeRangeObject; - style?: Style; + /** + * The type of chart that should be plotted + */ + style?: ChartStyle; type: string; id?: { [key: string]: any }; name?: string; [property: string]: any; } +/** + * financial instrument that relates to the definition of this product + * + * + * + * A financial instrument from any asset class. + */ export interface InstrumentElement { - id: PurpleID; + /** + * Any combination of instrument identifiers can be used together to resolve ambiguity, or + * for a better match. Not all applications will use the same instrument identifiers, which + * is why FDC3 allows for multiple to be specified. In general, the more identifiers an + * application can provide, the easier it will be to achieve interoperability. + * + * It is valid to include extra properties and metadata as part of the instrument payload, + * but the minimum requirement is for at least one instrument identifier to be provided. + * + * Try to only use instrument identifiers as intended. E.g. the `ticker` property is meant + * for tickers as used by an exchange. + * If the identifier you want to share is not a ticker or one of the other standardized + * fields, define a property that makes it clear what the value represents. Doing so will + * make interpretation easier for the developers of target applications. + */ + id: PurpleInstrumentIdentifiers; + /** + * The `market` map can be used to further specify the instrument and help achieve + * interoperability between disparate data sources. This is especially useful when using an + * `id` field that is not globally unique. + */ market?: OrganizationMarket; type: string; name?: string; [property: string]: any; } -export interface PurpleID { +/** + * Any combination of instrument identifiers can be used together to resolve ambiguity, or + * for a better match. Not all applications will use the same instrument identifiers, which + * is why FDC3 allows for multiple to be specified. In general, the more identifiers an + * application can provide, the easier it will be to achieve interoperability. + * + * It is valid to include extra properties and metadata as part of the instrument payload, + * but the minimum requirement is for at least one instrument identifier to be provided. + * + * Try to only use instrument identifiers as intended. E.g. the `ticker` property is meant + * for tickers as used by an exchange. + * If the identifier you want to share is not a ticker or one of the other standardized + * fields, define a property that makes it clear what the value represents. Doing so will + * make interpretation easier for the developers of target applications. + */ +export interface PurpleInstrumentIdentifiers { + /** + * + */ BBG?: string; + /** + * + */ CUSIP?: string; + /** + * + */ FDS_ID?: string; + /** + * + */ FIGI?: string; + /** + * + */ ISIN?: string; + /** + * + */ PERMID?: string; + /** + * + */ RIC?: string; + /** + * + */ SEDOL?: string; + /** + * Unstandardized stock tickers + */ ticker?: string; [property: string]: any; } +/** + * The `market` map can be used to further specify the instrument and help achieve + * interoperability between disparate data sources. This is especially useful when using an + * `id` field that is not globally unique. + */ export interface OrganizationMarket { + /** + * + */ BBG?: string; + /** + * + */ COUNTRY_ISOALPHA2?: string; + /** + * + */ MIC?: string; + /** + * Human readable market name + */ name?: string; [property: string]: any; } -export interface ContextElement { - id?: { [key: string]: any }; - name?: string; - type: string; - [property: string]: any; -} - +/** + * The time range that should be plotted + * + * The time range over which the interaction occurred + * + * A context representing a period of time. Any user interfaces that represent or visualize + * events or activity over time can be filtered or focused on a particular time period, + * e.g.: + * + * - A pricing chart + * - A trade blotter + * - A record of client contact/activity in a CRM + * + * Example use cases: + * + * - User may want to view pricing/trades/customer activity for a security over a particular + * time period, the time range might be specified as the context for the `ViewChart` intent + * OR it might be embedded in another context (e.g. a context representing a chart to plot). + * - User filters a visualization (e.g. a pricing chart) to show a particular period, the + * `TimeRange` is broadcast and other visualizations (e.g. a heatmap of activity by + * instrument, or industry sector etc.) receive it and filter themselves to show data over + * the same range. + * + * Notes: + * + * - A `TimeRange` may be closed (i.e. `startTime` and `endTime` are both known) or open + * (i.e. only one of `startTime` or `endTime` is known). + * - Ranges corresponding to dates (e.g. `2022-05-12` to `2022-05-19`) should be specified + * using times as this prevents issues with timezone conversions and inclusive/exclusive + * date ranges. + * - String fields representing times are encoded according to [ISO + * 8601-1:2019](https://www.iso.org/standard/70907.html). + * - A timezone indicator should be specified, e.g. `"2022-05-12T15:18:03Z"` or + * `"2022-05-12T16:18:03+01:00"` + * - Times MAY be specified with millisecond precision, e.g. `"2022-05-12T15:18:03.349Z"` + */ export interface TimeRangeObject { + /** + * The end time of the range, encoded according to [ISO + * 8601-1:2019](https://www.iso.org/standard/70907.html) with a timezone indicator. + */ endTime?: Date; + /** + * The start time of the range, encoded according to [ISO + * 8601-1:2019](https://www.iso.org/standard/70907.html) with a timezone indicator. + */ startTime?: Date; type: string; id?: { [key: string]: any }; @@ -122,7 +370,10 @@ export interface TimeRangeObject { [property: string]: any; } -export enum Style { +/** + * The type of chart that should be plotted + */ +export enum ChartStyle { Bar = 'bar', Candle = 'candle', Custom = 'custom', @@ -135,18 +386,47 @@ export enum Style { StackedBar = 'stacked-bar', } +/** + * A collection of settings to start a new chat conversation + */ export interface ChatInitSettings { + /** + * Name to apply to the chat created + */ chatName?: string; + /** + * Contacts to add to the chat + */ members?: ContactListObject; + /** + * An initial message to post in the chat when created. + */ message?: MessageObject | string; - options?: Options; + /** + * Option settings that affect the creation of the chat + */ + options?: ChatOptions; type: string; id?: { [key: string]: any }; name?: string; [property: string]: any; } +/** + * Contacts to add to the chat + * + * A list of contacts involved in the interaction + * + * A collection of contacts, e.g. for chatting to or calling multiple contacts. + * + * The contact list 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. + */ export interface ContactListObject { + /** + * An array of contact contexts that forms the list. + */ contacts: ContactElement[]; type: string; id?: { [key: string]: any }; @@ -154,36 +434,90 @@ export interface ContactListObject { [property: string]: any; } +/** + * The contact that initiated the interaction + * + * A person contact that can be engaged with through email, calling, messaging, CMS, etc. + */ export interface ContactElement { - id: FluffyID; + /** + * Identifiers that relate to the Contact represented by this context + */ + id: PurpleContactIdentifiers; type: string; name?: string; [property: string]: any; } -export interface FluffyID { +/** + * Identifiers that relate to the Contact represented by this context + */ +export interface PurpleContactIdentifiers { + /** + * The email address for the contact + */ email?: string; + /** + * FactSet Permanent Identifier representing the contact + */ FDS_ID?: string; [property: string]: any; } +/** + * A chat message to be sent through an instant messaging application. Can contain one or + * several text bodies (organized by mime-type, plaintext or markdown), as well as attached + * entities (either arbitrary file attachments or FDC3 actions to be embedded in the + * message). To be put inside a ChatInitSettings object. + */ export interface MessageObject { + /** + * A map of string IDs to entities that should be attached to the message, such as an action + * to perform, a file attachment, or other FDC3 context object. + */ entities?: { [key: string]: PurpleAction }; - text?: PurpleText; + /** + * A map of string mime-type to string content + */ + text?: PurpleMessageText; type: string; id?: { [key: string]: any }; name?: string; [property: string]: any; } +/** + * 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 specific app. + * + * A File attachment encoded in the form of a data URI + */ export interface PurpleAction { - app?: EntityApp; - context?: EntityContext; - customConfig?: { [key: string]: any }; /** - * A reference an intent type name, such as those defined in the FDC3 Standard + * An optional target application identifier that should perform the action + */ + app?: ActionTargetApp; + /** + * A context object with which the action will be performed + */ + context?: ContextElement; + /** + * 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. */ intent?: string; + /** + * A human readable display name for the action + */ title?: string; type: any; id?: { [key: string]: any }; @@ -192,68 +526,140 @@ export interface PurpleAction { [property: string]: any; } -export interface EntityApp { - appId: string; - instanceId?: string; - [property: string]: any; -} - -export interface EntityContext { - id?: { [key: string]: any }; - name?: string; - type: string; - [property: string]: any; -} - export interface PurpleData { + /** + * A data URI encoding the content of the file to be attached + */ dataUri: string; + /** + * The name of the attached file + */ name: string; [property: string]: any; } -export interface PurpleText { +/** + * A map of string mime-type to string content + */ +export interface PurpleMessageText { + /** + * Markdown encoded content + */ 'text/markdown'?: string; + /** + * Plain text encoded content. + */ 'text/plain'?: string; [property: string]: any; } -export interface Options { +/** + * Option settings that affect the creation of the chat + */ +export interface ChatOptions { + /** + * if true members will be allowed to add other members to the chat + */ allowAddUser?: boolean; + /** + * if true members will be allowed to browse past messages + */ allowHistoryBrowsing?: boolean; + /** + * if true members will be allowed to copy/paste messages + */ allowMessageCopy?: boolean; + /** + * if false a separate chat will be created for each member + */ groupRecipients?: boolean; + /** + * if true the room will be visible to everyone in the chat application + */ isPublic?: boolean; [property: string]: any; } +/** + * A context representing a chat message. Typically used to send the message or to + * pre-populate a message for sending. + */ export interface ChatMessage { chatRoom: ChatRoomObject; - message: MessageObject; + /** + * The content of the message to post in the chat when created. + */ + message: MessageObject | string; type: string; id?: { [key: string]: any }; name?: string; [property: string]: any; } +/** + * Reference to the chat room which could be used to send a message to the room + */ export interface ChatRoomObject { + /** + * Identifier(s) for the chat - currently unstandardized + */ id: { [key: string]: any }; + /** + * Display name for the chat room + */ name?: string; + /** + * The name of the service that hosts the chat + */ providerName: string; type: string; + /** + * Universal url to access to the room. It could be opened from a browser, a mobile app, + * etc... + */ url?: string; [property: string]: any; } +/** + * Reference to the chat room which could be used to send a message to the room + */ export interface ChatRoom { + /** + * Identifier(s) for the chat - currently unstandardized + */ id: { [key: string]: any }; + /** + * Display name for the chat room + */ name?: string; + /** + * The name of the service that hosts the chat + */ providerName: string; type: string; + /** + * Universal url to access to the room. It could be opened from a browser, a mobile app, + * etc... + */ url?: string; [property: string]: any; } +/** + * A context type that represents a simple search criterion, based on a list of other + * context objects, that can be used to search or filter messages in a chat application. + */ export interface ChatSearchCriteria { + /** + * An array of criteria that should match chats returned from by a search. + * + * ⚠️ Operators (and/or/not) are not defined in `fdc3.chat.searchCriteria`. It is up to the + * application that processes the FDC3 Intent to choose and apply the operators between the + * criteria. + * + * Empty search criteria can be supported to allow resetting of filters. + */ criteria: Array; type: string; id?: { [key: string]: any }; @@ -261,43 +667,170 @@ export interface ChatSearchCriteria { [property: string]: any; } +/** + * financial instrument that relates to the definition of this product + * + * + * + * A financial instrument from any asset class. + * + * An entity that can be used when referencing private companies and other organizations + * where a specific instrument is not available or desired e.g. CRM and News workflows. + * + * It is valid to include extra properties and metadata as part of the organization payload, + * but the minimum requirement is for at least one specified identifier to be provided. + * + * The contact that initiated the interaction + * + * A person contact that can be engaged with through email, calling, messaging, CMS, etc. + */ export interface OrganizationObject { - id: TentacledID; + /** + * Any combination of instrument identifiers can be used together to resolve ambiguity, or + * for a better match. Not all applications will use the same instrument identifiers, which + * is why FDC3 allows for multiple to be specified. In general, the more identifiers an + * application can provide, the easier it will be to achieve interoperability. + * + * It is valid to include extra properties and metadata as part of the instrument payload, + * but the minimum requirement is for at least one instrument identifier to be provided. + * + * Try to only use instrument identifiers as intended. E.g. the `ticker` property is meant + * for tickers as used by an exchange. + * If the identifier you want to share is not a ticker or one of the other standardized + * fields, define a property that makes it clear what the value represents. Doing so will + * make interpretation easier for the developers of target applications. + * + * Identifiers for the organization, at least one must be provided. + * + * Identifiers that relate to the Contact represented by this context + */ + id: Identifiers; + /** + * The `market` map can be used to further specify the instrument and help achieve + * interoperability between disparate data sources. This is especially useful when using an + * `id` field that is not globally unique. + */ market?: OrganizationMarket; type: string; name?: string; [property: string]: any; } -export interface TentacledID { +/** + * Any combination of instrument identifiers can be used together to resolve ambiguity, or + * for a better match. Not all applications will use the same instrument identifiers, which + * is why FDC3 allows for multiple to be specified. In general, the more identifiers an + * application can provide, the easier it will be to achieve interoperability. + * + * It is valid to include extra properties and metadata as part of the instrument payload, + * but the minimum requirement is for at least one instrument identifier to be provided. + * + * Try to only use instrument identifiers as intended. E.g. the `ticker` property is meant + * for tickers as used by an exchange. + * If the identifier you want to share is not a ticker or one of the other standardized + * fields, define a property that makes it clear what the value represents. Doing so will + * make interpretation easier for the developers of target applications. + * + * Identifiers for the organization, at least one must be provided. + * + * Identifiers that relate to the Contact represented by this context + */ +export interface Identifiers { + /** + * + */ BBG?: string; + /** + * + */ CUSIP?: string; + /** + * + * + * FactSet Permanent Identifier representing the organization + * + * FactSet Permanent Identifier representing the contact + */ FDS_ID?: string; + /** + * + */ FIGI?: string; + /** + * + */ ISIN?: string; + /** + * + * + * Refinitiv Permanent Identifiers, or PermID for the organization + */ PERMID?: string; + /** + * + */ RIC?: string; + /** + * + */ SEDOL?: string; + /** + * Unstandardized stock tickers + */ ticker?: string; + /** + * The Legal Entity Identifier (LEI) is a 20-character, alpha-numeric code based on the ISO + * 17442 standard developed by the International Organization for Standardization (ISO). It + * connects to key reference information that enables clear and unique identification of + * legal entities participating in financial transactions. + */ LEI?: string; + /** + * The email address for the contact + */ email?: string; [property: string]: any; } +/** + * A person contact that can be engaged with through email, calling, messaging, CMS, etc. + */ export interface Contact { - id: StickyID; + /** + * Identifiers that relate to the Contact represented by this context + */ + id: FluffyContactIdentifiers; type: string; name?: string; [property: string]: any; } -export interface StickyID { +/** + * Identifiers that relate to the Contact represented by this context + */ +export interface FluffyContactIdentifiers { + /** + * The email address for the contact + */ email?: string; + /** + * FactSet Permanent Identifier representing the contact + */ FDS_ID?: string; [property: string]: any; } +/** + * A collection of contacts, e.g. for chatting to or calling multiple contacts. + * + * The contact list 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. + */ export interface ContactList { + /** + * An array of contact contexts that forms the list. + */ contacts: ContactElement[]; type: string; id?: { [key: string]: any }; @@ -305,13 +838,76 @@ export interface ContactList { [property: string]: any; } +/** + * 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. + * + * The 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. + * + * The 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. + */ export interface Context { + /** + * Context data objects may include a set of equivalent key-value pairs that can be used to + * help applications identify and look up the context type they receive in their own domain. + * The idea behind this design is that applications can provide as many equivalent + * identifiers to a target application as possible, e.g. an instrument may be represented by + * an ISIN, CUSIP or Bloomberg identifier. + * + * Identifiers do not make sense for all types of data, so the `id` property is therefore + * optional, but some derived types may choose to require at least one identifier. + */ id?: { [key: string]: any }; + /** + * Context data objects may include a name property that can be used for more information, + * or display purposes. Some derived types may require the name object as mandatory, + * depending on use case. + */ name?: string; + /** + * The type property is the only _required_ part of the FDC3 context data schema. The FDC3 + * [API](https://fdc3.finos.org/docs/api/spec) relies on the `type` property being present + * to route shared context data appropriately. + * + * FDC3 [Intents](https://fdc3.finos.org/docs/intents/spec) also register the context data + * types they support in an FDC3 [App + * Directory](https://fdc3.finos.org/docs/app-directory/overview), used for intent discovery + * and routing. + * + * Standardized FDC3 context types have well-known `type` properties prefixed with the + * `fdc3` namespace, e.g. `fdc3.instrument`. For non-standard types, e.g. those defined and + * used by a particular organization, the convention is to prefix them with an + * organization-specific namespace, e.g. `blackrock.fund`. + * + * See the [Context Data Specification](https://fdc3.finos.org/docs/context/spec) for more + * information about context data types. + */ type: string; [property: string]: any; } +/** + * A country entity. + * + * Notes: + * + * - It is valid to include extra properties and metadata as part of the country payload, + * but the minimum requirement is for at least one standardized identifier to be provided + * + * - `COUNTRY_ISOALPHA2` SHOULD be preferred. + * + * - Try to only use country identifiers as intended and specified in the [ISO + * standard](https://en.wikipedia.org/wiki/ISO_3166-1). E.g. the `COUNTRY_ISOALPHA2` + * property must be a recognized value and not a proprietary two-letter code. If the + * identifier you want to share is not a standardized and recognized one, rather define a + * property that makes it clear what value it is. This makes it easier for target + * applications. + */ export interface Country { id: CountryID; type: string; @@ -320,28 +916,64 @@ export interface Country { } export interface CountryID { + /** + * Two-letter ISO country code + */ COUNTRY_ISOALPHA2?: string; + /** + * Three-letter ISO country code + */ COUNTRY_ISOALPHA3?: string; + /** + * Two-letter ISO country code. Deprecated in FDC3 2.0 in favour of the version prefixed + * with `COUNTRY_`. + */ ISOALPHA2?: string; + /** + * Three-letter ISO country code. Deprecated in FDC3 2.0 in favour of the version prefixed + * with `COUNTRY_`. + */ ISOALPHA3?: string; [property: string]: any; } +/** + * A context representing an individual Currency. + */ export interface Currency { id: CurrencyID; + /** + * The name of the currency for display purposes + */ name?: string; type: string; [property: string]: any; } export interface CurrencyID { + /** + * The `CURRENCY_ISOCODE` should conform to 3 character alphabetic codes defined in [ISO + * 4217](https://www.iso.org/iso-4217-currency-codes.html) + */ CURRENCY_ISOCODE?: string; [property: string]: any; } +/** + * A collection of information to be used to initiate an email with a Contact or ContactList. + */ export interface Email { - recipients: RecipientsObject; + /** + * One or more receipients for the email. + */ + recipients: EmailRecipients; + /** + * Subject line for the email. + */ subject?: string; + /** + * Body content for the email. + */ textBody?: string; type: string; id?: { [key: string]: any }; @@ -349,50 +981,177 @@ export interface Email { [property: string]: any; } -export interface RecipientsObject { - id?: RecipientsID; +/** + * One or more receipients for the email. + * + * The contact that initiated the interaction + * + * A person contact that can be engaged with through email, calling, messaging, CMS, etc. + * + * Contacts to add to the chat + * + * A list of contacts involved in the interaction + * + * A collection of contacts, e.g. for chatting to or calling multiple contacts. + * + * The contact list 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. + */ +export interface EmailRecipients { + /** + * Identifiers that relate to the Contact represented by this context + */ + id?: EmailRecipientsID; type: string; name?: string; + /** + * An array of contact contexts that forms the list. + */ contacts?: ContactElement[]; [property: string]: any; } -export interface RecipientsID { +/** + * Identifiers that relate to the Contact represented by this context + */ +export interface EmailRecipientsID { + /** + * The email address for the contact + */ email?: string; + /** + * FactSet Permanent Identifier representing the contact + */ FDS_ID?: string; [property: string]: any; } +/** + * A financial instrument from any asset class. + */ export interface Instrument { - id: IndigoID; + /** + * Any combination of instrument identifiers can be used together to resolve ambiguity, or + * for a better match. Not all applications will use the same instrument identifiers, which + * is why FDC3 allows for multiple to be specified. In general, the more identifiers an + * application can provide, the easier it will be to achieve interoperability. + * + * It is valid to include extra properties and metadata as part of the instrument payload, + * but the minimum requirement is for at least one instrument identifier to be provided. + * + * Try to only use instrument identifiers as intended. E.g. the `ticker` property is meant + * for tickers as used by an exchange. + * If the identifier you want to share is not a ticker or one of the other standardized + * fields, define a property that makes it clear what the value represents. Doing so will + * make interpretation easier for the developers of target applications. + */ + id: FluffyInstrumentIdentifiers; + /** + * The `market` map can be used to further specify the instrument and help achieve + * interoperability between disparate data sources. This is especially useful when using an + * `id` field that is not globally unique. + */ market?: PurpleMarket; type: string; name?: string; [property: string]: any; } -export interface IndigoID { +/** + * Any combination of instrument identifiers can be used together to resolve ambiguity, or + * for a better match. Not all applications will use the same instrument identifiers, which + * is why FDC3 allows for multiple to be specified. In general, the more identifiers an + * application can provide, the easier it will be to achieve interoperability. + * + * It is valid to include extra properties and metadata as part of the instrument payload, + * but the minimum requirement is for at least one instrument identifier to be provided. + * + * Try to only use instrument identifiers as intended. E.g. the `ticker` property is meant + * for tickers as used by an exchange. + * If the identifier you want to share is not a ticker or one of the other standardized + * fields, define a property that makes it clear what the value represents. Doing so will + * make interpretation easier for the developers of target applications. + */ +export interface FluffyInstrumentIdentifiers { + /** + * + */ BBG?: string; + /** + * + */ CUSIP?: string; + /** + * + */ FDS_ID?: string; + /** + * + */ FIGI?: string; + /** + * + */ ISIN?: string; + /** + * + */ PERMID?: string; + /** + * + */ RIC?: string; + /** + * + */ SEDOL?: string; + /** + * Unstandardized stock tickers + */ ticker?: string; [property: string]: any; } +/** + * The `market` map can be used to further specify the instrument and help achieve + * interoperability between disparate data sources. This is especially useful when using an + * `id` field that is not globally unique. + */ export interface PurpleMarket { + /** + * + */ BBG?: string; + /** + * + */ COUNTRY_ISOALPHA2?: string; + /** + * + */ MIC?: string; + /** + * Human readable market name + */ name?: string; [property: string]: any; } +/** + * A collection of instruments. Use this type for use cases that require not just a single + * instrument, but multiple (e.g. to populate a watchlist). However, when holding + * information for each instrument is required, it is recommended to use the + * [Portfolio](Portfolio) type. + * + * The instrument list 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. + */ export interface InstrumentList { + /** + * An array of instrument contexts that forms the list. + */ instruments: InstrumentElement[]; type: string; id?: { [key: string]: any }; @@ -400,36 +1159,131 @@ export interface InstrumentList { [property: string]: any; } +/** + * An `Interaction` is a significant direct exchange of ideas or information between a + * number of participants, e.g. a Sell Side party and one or more Buy Side parties. An + * `Interaction` might be a call, a meeting (physical or virtual), an IM or the preparation + * of some specialist data, such as financial data for a given company or sector. + */ export interface Interaction { + /** + * A human-readable description of the interaction + */ description: string; + /** + * Can be used by a target application to pass an identifier back to the originating + * application after an interaction record has been created, updated or deleted. An + * interaction ID does not need to be populated by the originating application, however the + * target application could store it for future reference and SHOULD return it in a + * `TransactionResult`. + */ + id?: InteractionID; + /** + * The contact that initiated the interaction + */ initiator?: ContactElement; + /** + * `interactionType` SHOULD be one of `'Instant Message'`, `'Email'`, `'Call'`, or + * `'Meeting'` although other string values are permitted. + */ interactionType: string; + /** + * Used to represent the application or service that the interaction was created from to aid + * in tracing the source of an interaction. + */ origin?: string; + /** + * A list of contacts involved in the interaction + */ participants: ContactListObject; + /** + * The time range over which the interaction occurred + */ timeRange: TimeRangeObject; type: string; - id?: { [key: string]: any }; name?: string; [property: string]: any; } +/** + * Can be used by a target application to pass an identifier back to the originating + * application after an interaction record has been created, updated or deleted. An + * interaction ID does not need to be populated by the originating application, however the + * target application could store it for future reference and SHOULD return it in a + * `TransactionResult`. + */ +export interface InteractionID { + /** + * Interactions ID in Salesforce + */ + SALESFORCE?: string; + /** + * Interaction ID in SingleTrack + */ + SINGLETRACK?: string; + /** + * Can be used by a target application to pass a record's link back to the originating + * application. This offers the originating application a way to open the record for a user + * to view. + */ + URI?: string; + [property: string]: any; +} + +/** + * A chat message to be sent through an instant messaging application. Can contain one or + * several text bodies (organized by mime-type, plaintext or markdown), as well as attached + * entities (either arbitrary file attachments or FDC3 actions to be embedded in the + * message). To be put inside a ChatInitSettings object. + */ export interface Message { + /** + * A map of string IDs to entities that should be attached to the message, such as an action + * to perform, a file attachment, or other FDC3 context object. + */ entities?: { [key: string]: FluffyAction }; - text?: FluffyText; + /** + * A map of string mime-type to string content + */ + text?: FluffyMessageText; type: string; id?: { [key: string]: any }; name?: string; [property: string]: any; } +/** + * 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 specific app. + * + * A File attachment encoded in the form of a data URI + */ export interface FluffyAction { - app?: EntityApp; - context?: EntityContext; - customConfig?: { [key: string]: any }; /** - * A reference an intent type name, such as those defined in the FDC3 Standard + * An optional target application identifier that should perform the action + */ + app?: ActionTargetApp; + /** + * A context object with which the action will be performed + */ + context?: ContextElement; + /** + * 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. */ intent?: string; + /** + * A human readable display name for the action + */ title?: string; type: any; id?: { [key: string]: any }; @@ -439,17 +1293,46 @@ export interface FluffyAction { } export interface FluffyData { + /** + * A data URI encoding the content of the file to be attached + */ dataUri: string; + /** + * The name of the attached file + */ name: string; [property: string]: any; } -export interface FluffyText { +/** + * A map of string mime-type to string content + */ +export interface FluffyMessageText { + /** + * Markdown encoded content + */ 'text/markdown'?: string; + /** + * Plain text encoded content. + */ 'text/plain'?: string; [property: string]: any; } +/** + * A type that explicitly represents a lack of context. + * + * Notes: + * + * - Intended to be used in situations where no context is desired. + * - For example: + * - Raising an intent without context (e.g. opening a blank order form, or chat interface + * without a contact selected). + * - Resetting context on a channel (e.g. when context is used to set a filter in other + * applications a null context might release the filter). + * - An explicit representation of a Null or empty context allows apps to declare support + * for a lack of context, for example in their intent metadata in an app directory. + */ export interface Nothing { type: string; id?: { [key: string]: any }; @@ -497,11 +1380,17 @@ export interface PurpleOrderDetails { } /** + * A product that is the subject of th trade. + * * @experimental context type representing a tradable product. To be used with OMS and EMS * systems. * * This type is currently only loosely defined as an extensible context object, with an * optional instrument field. + * + * 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. */ export interface ProductObject { /** @@ -509,19 +1398,30 @@ export interface ProductObject { * expected to be standardized in future. */ id: { [key: string]: string }; + /** + * financial instrument that relates to the definition of this product + */ + instrument?: InstrumentElement; /** * A human-readable summary of the product. */ name?: string; type: string; - instrument?: InstrumentElement; [property: string]: any; } /** - * @experimental A list of orders + * @experimental A list of orders. Use this type for use cases that require not just a + * single order, but multiple. + * + * The OrderList 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. */ export interface OrderList { + /** + * An array of order contexts that forms the list. + */ orders: OrderElement[]; type: string; id?: { [key: string]: any }; @@ -568,21 +1468,64 @@ export interface FluffyOrderDetails { [property: string]: any; } +/** + * An entity that can be used when referencing private companies and other organizations + * where a specific instrument is not available or desired e.g. CRM and News workflows. + * + * It is valid to include extra properties and metadata as part of the organization payload, + * but the minimum requirement is for at least one specified identifier to be provided. + */ export interface Organization { - id: IndecentID; + /** + * Identifiers for the organization, at least one must be provided. + */ + id: OrganizationIdentifiers; type: string; name?: string; [property: string]: any; } -export interface IndecentID { +/** + * Identifiers for the organization, at least one must be provided. + */ +export interface OrganizationIdentifiers { + /** + * FactSet Permanent Identifier representing the organization + */ FDS_ID?: string; + /** + * The Legal Entity Identifier (LEI) is a 20-character, alpha-numeric code based on the ISO + * 17442 standard developed by the International Organization for Standardization (ISO). It + * connects to key reference information that enables clear and unique identification of + * legal entities participating in financial transactions. + */ LEI?: string; + /** + * Refinitiv Permanent Identifiers, or PermID for the organization + */ PERMID?: string; [property: string]: any; } +/** + * A financial portfolio made up of multiple positions (holdings) in several instruments. + * Contrast this with e.g. the [InstrumentList](InstrumentList) type, which is just a list + * of instruments. + * + * This is a good example of how types can be composed and extended with extra properties to + * define more complex types. + * + * The Portfolio type consists of an array of [Position](Position) types, each of which + * refers to a single [Instrument](Instrument) and a holding amount for that instrument. + * + * The portfolio schema does not explicitly include identifiers in the `id` section, as + * there bis not a common standard for such identifiers. Applications can, however, populate + * this part of the contract with custom identifiers if so desired. + */ export interface Portfolio { + /** + * The List of Positions which make up the Portfolio + */ positions: PositionElement[]; type: string; id?: { [key: string]: any }; @@ -590,7 +1533,24 @@ export interface Portfolio { [property: string]: any; } +/** + * A financial position made up of an instrument and a holding in that instrument. This type + * is a good example of how new context types can be composed from existing types. + * + * In this case, the instrument and the holding amount for that instrument are required + * values. + * + * The [Position](Position) type goes hand-in-hand with the [Portfolio](Portfolio) type, + * which represents multiple holdings in a combination of instruments. + * + * The position 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. + */ export interface PositionElement { + /** + * The amount of the holding, e.g. a number of shares + */ holding: number; instrument: InstrumentElement; type: string; @@ -599,7 +1559,24 @@ export interface PositionElement { [property: string]: any; } +/** + * A financial position made up of an instrument and a holding in that instrument. This type + * is a good example of how new context types can be composed from existing types. + * + * In this case, the instrument and the holding amount for that instrument are required + * values. + * + * The [Position](Position) type goes hand-in-hand with the [Portfolio](Portfolio) type, + * which represents multiple holdings in a combination of instruments. + * + * The position 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. + */ export interface Position { + /** + * The amount of the holding, e.g. a number of shares + */ holding: number; instrument: InstrumentElement; type: string; @@ -614,6 +1591,10 @@ export interface Position { * * This type is currently only loosely defined as an extensible context object, with an * optional instrument field. + * + * 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. */ export interface Product { /** @@ -621,17 +1602,60 @@ export interface Product { * expected to be standardized in future. */ id: { [key: string]: string }; + /** + * financial instrument that relates to the definition of this product + */ + instrument?: InstrumentElement; /** * A human-readable summary of the product. */ name?: string; type: string; - instrument?: InstrumentElement; [property: string]: any; } +/** + * A context representing a period of time. Any user interfaces that represent or visualize + * events or activity over time can be filtered or focused on a particular time period, + * e.g.: + * + * - A pricing chart + * - A trade blotter + * - A record of client contact/activity in a CRM + * + * Example use cases: + * + * - User may want to view pricing/trades/customer activity for a security over a particular + * time period, the time range might be specified as the context for the `ViewChart` intent + * OR it might be embedded in another context (e.g. a context representing a chart to plot). + * - User filters a visualization (e.g. a pricing chart) to show a particular period, the + * `TimeRange` is broadcast and other visualizations (e.g. a heatmap of activity by + * instrument, or industry sector etc.) receive it and filter themselves to show data over + * the same range. + * + * Notes: + * + * - A `TimeRange` may be closed (i.e. `startTime` and `endTime` are both known) or open + * (i.e. only one of `startTime` or `endTime` is known). + * - Ranges corresponding to dates (e.g. `2022-05-12` to `2022-05-19`) should be specified + * using times as this prevents issues with timezone conversions and inclusive/exclusive + * date ranges. + * - String fields representing times are encoded according to [ISO + * 8601-1:2019](https://www.iso.org/standard/70907.html). + * - A timezone indicator should be specified, e.g. `"2022-05-12T15:18:03Z"` or + * `"2022-05-12T16:18:03+01:00"` + * - Times MAY be specified with millisecond precision, e.g. `"2022-05-12T15:18:03.349Z"` + */ export interface TimeRange { + /** + * The end time of the range, encoded according to [ISO + * 8601-1:2019](https://www.iso.org/standard/70907.html) with a timezone indicator. + */ endTime?: Date; + /** + * The start time of the range, encoded according to [ISO + * 8601-1:2019](https://www.iso.org/standard/70907.html) with a timezone indicator. + */ startTime?: Date; type: string; id?: { [key: string]: any }; @@ -647,6 +1671,10 @@ export interface TimeRange { * to summarize the trade and a required `product` field that may be used to provide * additional detail about the trade, which is currently typed as a unspecified Context * type, but `product` is expected to be standardized in future. + * + * The Trade 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. */ export interface Trade { /** @@ -658,15 +1686,26 @@ export interface Trade { * A human-readable summary of the trade. */ name?: string; + /** + * A product that is the subject of th trade. + */ product: ProductObject; type: string; [property: string]: any; } /** - * @experimental A list of trades. + * @experimental A list of trades. Use this type for use cases that require not just a + * single trade, but multiple. + * + * The TradeList 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. */ export interface TradeList { + /** + * An array of trade contexts that forms the list. + */ trades: TradeElement[]; type: string; id?: { [key: string]: any }; @@ -682,6 +1721,10 @@ export interface TradeList { * to summarize the trade and a required `product` field that may be used to provide * additional detail about the trade, which is currently typed as a unspecified Context * type, but `product` is expected to be standardized in future. + * + * The Trade 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. */ export interface TradeElement { /** @@ -693,33 +1736,72 @@ export interface TradeElement { * A human-readable summary of the trade. */ name?: string; + /** + * A product that is the subject of th trade. + */ product: ProductObject; type: string; [property: string]: any; } +/** + * A context type representing the result of a transaction initiated via FDC3, which SHOULD + * be returned as an `IntentResult` by intents that create, retrieve, update or delete + * content or records in another application. Its purpose is to provide a status and message + * (where needed) for the transaction and MAY wrap a returned context object. + */ export interface TransactionResult { + /** + * A context object returned by the transaction, possibly with updated data. + */ context?: ContextElement; - status: Status; + /** + * The status of the transaction being reported. + */ + status: TransactionStatus; type: string; id?: { [key: string]: any }; name?: string; [property: string]: any; } -export enum Status { +/** + * The status of the transaction being reported. + */ +export enum TransactionStatus { Created = 'Created', Deleted = 'Deleted', Failed = 'Failed', Updated = 'Updated', } +/** + * A context type representing the price and value of a holding. + */ export interface Valuation { + /** + * The valuation currency, which should conform to 3 character alphabetic codes defined in + * [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) + */ CURRENCY_ISOCODE: string; + /** + * The time at which this valuation expires, encoded according to [ISO + * 8601-1:2019](https://www.iso.org/standard/70907.html) with a timezone indicator included. + */ expiryTime?: Date; + /** + * The price per unit the the valuation is based on. + */ price?: number; type: string; + /** + * The time at which the valuation was performed, encoded according to [ISO + * 8601-1:2019](https://www.iso.org/standard/70907.html) with a timezone indicator included. + */ valuationTime?: Date; + /** + * The value of the holding, expresses in the nominated currency. + */ value: number; id?: { [key: string]: any }; name?: string; @@ -1123,9 +2205,8 @@ function r(name: string) { const typeMap: any = { Action: o( [ - { json: 'app', js: 'app', typ: u(undefined, r('ActionApp')) }, - { json: 'context', js: 'context', typ: r('ActionContext') }, - { json: 'customConfig', js: 'customConfig', typ: u(undefined, m('any')) }, + { json: 'app', js: 'app', typ: u(undefined, r('ActionTargetApp')) }, + { json: 'context', js: 'context', typ: r('ContextElement') }, { json: 'intent', js: 'intent', typ: u(undefined, '') }, { json: 'title', js: 'title', typ: '' }, { json: 'type', js: 'type', typ: '' }, @@ -1134,14 +2215,15 @@ const typeMap: any = { ], 'any' ), - ActionApp: o( + ActionTargetApp: o( [ { json: 'appId', js: 'appId', typ: '' }, + { json: 'desktopAgent', js: 'desktopAgent', typ: u(undefined, '') }, { json: 'instanceId', js: 'instanceId', typ: u(undefined, '') }, ], 'any' ), - ActionContext: o( + ContextElement: o( [ { json: 'id', js: 'id', typ: u(undefined, m('any')) }, { json: 'name', js: 'name', typ: u(undefined, '') }, @@ -1154,7 +2236,7 @@ const typeMap: any = { { json: 'instruments', js: 'instruments', typ: a(r('InstrumentElement')) }, { json: 'otherConfig', js: 'otherConfig', typ: u(undefined, a(r('ContextElement'))) }, { json: 'range', js: 'range', typ: u(undefined, r('TimeRangeObject')) }, - { json: 'style', js: 'style', typ: u(undefined, r('Style')) }, + { json: 'style', js: 'style', typ: u(undefined, r('ChartStyle')) }, { json: 'type', js: 'type', typ: '' }, { json: 'id', js: 'id', typ: u(undefined, m('any')) }, { json: 'name', js: 'name', typ: u(undefined, '') }, @@ -1163,14 +2245,14 @@ const typeMap: any = { ), InstrumentElement: o( [ - { json: 'id', js: 'id', typ: r('PurpleID') }, + { json: 'id', js: 'id', typ: r('PurpleInstrumentIdentifiers') }, { json: 'market', js: 'market', typ: u(undefined, r('OrganizationMarket')) }, { json: 'type', js: 'type', typ: '' }, { json: 'name', js: 'name', typ: u(undefined, '') }, ], 'any' ), - PurpleID: o( + PurpleInstrumentIdentifiers: o( [ { json: 'BBG', js: 'BBG', typ: u(undefined, '') }, { json: 'CUSIP', js: 'CUSIP', typ: u(undefined, '') }, @@ -1193,14 +2275,6 @@ const typeMap: any = { ], 'any' ), - ContextElement: o( - [ - { json: 'id', js: 'id', typ: u(undefined, m('any')) }, - { json: 'name', js: 'name', typ: u(undefined, '') }, - { json: 'type', js: 'type', typ: '' }, - ], - 'any' - ), TimeRangeObject: o( [ { json: 'endTime', js: 'endTime', typ: u(undefined, Date) }, @@ -1216,7 +2290,7 @@ const typeMap: any = { { json: 'chatName', js: 'chatName', typ: u(undefined, '') }, { json: 'members', js: 'members', typ: u(undefined, r('ContactListObject')) }, { json: 'message', js: 'message', typ: u(undefined, u(r('MessageObject'), '')) }, - { json: 'options', js: 'options', typ: u(undefined, r('Options')) }, + { json: 'options', js: 'options', typ: u(undefined, r('ChatOptions')) }, { json: 'type', js: 'type', typ: '' }, { json: 'id', js: 'id', typ: u(undefined, m('any')) }, { json: 'name', js: 'name', typ: u(undefined, '') }, @@ -1234,13 +2308,13 @@ const typeMap: any = { ), ContactElement: o( [ - { json: 'id', js: 'id', typ: r('FluffyID') }, + { json: 'id', js: 'id', typ: r('PurpleContactIdentifiers') }, { json: 'type', js: 'type', typ: '' }, { json: 'name', js: 'name', typ: u(undefined, '') }, ], 'any' ), - FluffyID: o( + PurpleContactIdentifiers: o( [ { json: 'email', js: 'email', typ: u(undefined, '') }, { json: 'FDS_ID', js: 'FDS_ID', typ: u(undefined, '') }, @@ -1250,7 +2324,7 @@ const typeMap: any = { MessageObject: o( [ { json: 'entities', js: 'entities', typ: u(undefined, m(r('PurpleAction'))) }, - { json: 'text', js: 'text', typ: u(undefined, r('PurpleText')) }, + { json: 'text', js: 'text', typ: u(undefined, r('PurpleMessageText')) }, { json: 'type', js: 'type', typ: '' }, { json: 'id', js: 'id', typ: u(undefined, m('any')) }, { json: 'name', js: 'name', typ: u(undefined, '') }, @@ -1259,9 +2333,8 @@ const typeMap: any = { ), PurpleAction: o( [ - { json: 'app', js: 'app', typ: u(undefined, r('EntityApp')) }, - { json: 'context', js: 'context', typ: u(undefined, r('EntityContext')) }, - { json: 'customConfig', js: 'customConfig', typ: u(undefined, m('any')) }, + { json: 'app', js: 'app', typ: u(undefined, r('ActionTargetApp')) }, + { json: 'context', js: 'context', typ: u(undefined, r('ContextElement')) }, { json: 'intent', js: 'intent', typ: u(undefined, '') }, { json: 'title', js: 'title', typ: u(undefined, '') }, { json: 'type', js: 'type', typ: 'any' }, @@ -1271,21 +2344,6 @@ const typeMap: any = { ], 'any' ), - EntityApp: o( - [ - { json: 'appId', js: 'appId', typ: '' }, - { json: 'instanceId', js: 'instanceId', typ: u(undefined, '') }, - ], - 'any' - ), - EntityContext: o( - [ - { json: 'id', js: 'id', typ: u(undefined, m('any')) }, - { json: 'name', js: 'name', typ: u(undefined, '') }, - { json: 'type', js: 'type', typ: '' }, - ], - 'any' - ), PurpleData: o( [ { json: 'dataUri', js: 'dataUri', typ: '' }, @@ -1293,14 +2351,14 @@ const typeMap: any = { ], 'any' ), - PurpleText: o( + PurpleMessageText: o( [ { json: 'text/markdown', js: 'text/markdown', typ: u(undefined, '') }, { json: 'text/plain', js: 'text/plain', typ: u(undefined, '') }, ], 'any' ), - Options: o( + ChatOptions: o( [ { json: 'allowAddUser', js: 'allowAddUser', typ: u(undefined, true) }, { json: 'allowHistoryBrowsing', js: 'allowHistoryBrowsing', typ: u(undefined, true) }, @@ -1313,7 +2371,7 @@ const typeMap: any = { ChatMessage: o( [ { json: 'chatRoom', js: 'chatRoom', typ: r('ChatRoomObject') }, - { json: 'message', js: 'message', typ: r('MessageObject') }, + { json: 'message', js: 'message', typ: u(r('MessageObject'), '') }, { json: 'type', js: 'type', typ: '' }, { json: 'id', js: 'id', typ: u(undefined, m('any')) }, { json: 'name', js: 'name', typ: u(undefined, '') }, @@ -1351,14 +2409,14 @@ const typeMap: any = { ), OrganizationObject: o( [ - { json: 'id', js: 'id', typ: r('TentacledID') }, + { json: 'id', js: 'id', typ: r('Identifiers') }, { json: 'market', js: 'market', typ: u(undefined, r('OrganizationMarket')) }, { json: 'type', js: 'type', typ: '' }, { json: 'name', js: 'name', typ: u(undefined, '') }, ], 'any' ), - TentacledID: o( + Identifiers: o( [ { json: 'BBG', js: 'BBG', typ: u(undefined, '') }, { json: 'CUSIP', js: 'CUSIP', typ: u(undefined, '') }, @@ -1376,13 +2434,13 @@ const typeMap: any = { ), Contact: o( [ - { json: 'id', js: 'id', typ: r('StickyID') }, + { json: 'id', js: 'id', typ: r('FluffyContactIdentifiers') }, { json: 'type', js: 'type', typ: '' }, { json: 'name', js: 'name', typ: u(undefined, '') }, ], 'any' ), - StickyID: o( + FluffyContactIdentifiers: o( [ { json: 'email', js: 'email', typ: u(undefined, '') }, { json: 'FDS_ID', js: 'FDS_ID', typ: u(undefined, '') }, @@ -1434,7 +2492,7 @@ const typeMap: any = { CurrencyID: o([{ json: 'CURRENCY_ISOCODE', js: 'CURRENCY_ISOCODE', typ: u(undefined, '') }], 'any'), Email: o( [ - { json: 'recipients', js: 'recipients', typ: r('RecipientsObject') }, + { json: 'recipients', js: 'recipients', typ: r('EmailRecipients') }, { json: 'subject', js: 'subject', typ: u(undefined, '') }, { json: 'textBody', js: 'textBody', typ: u(undefined, '') }, { json: 'type', js: 'type', typ: '' }, @@ -1443,16 +2501,16 @@ const typeMap: any = { ], 'any' ), - RecipientsObject: o( + EmailRecipients: o( [ - { json: 'id', js: 'id', typ: u(undefined, r('RecipientsID')) }, + { json: 'id', js: 'id', typ: u(undefined, r('EmailRecipientsID')) }, { json: 'type', js: 'type', typ: '' }, { json: 'name', js: 'name', typ: u(undefined, '') }, { json: 'contacts', js: 'contacts', typ: u(undefined, a(r('ContactElement'))) }, ], 'any' ), - RecipientsID: o( + EmailRecipientsID: o( [ { json: 'email', js: 'email', typ: u(undefined, '') }, { json: 'FDS_ID', js: 'FDS_ID', typ: u(undefined, '') }, @@ -1461,14 +2519,14 @@ const typeMap: any = { ), Instrument: o( [ - { json: 'id', js: 'id', typ: r('IndigoID') }, + { json: 'id', js: 'id', typ: r('FluffyInstrumentIdentifiers') }, { json: 'market', js: 'market', typ: u(undefined, r('PurpleMarket')) }, { json: 'type', js: 'type', typ: '' }, { json: 'name', js: 'name', typ: u(undefined, '') }, ], 'any' ), - IndigoID: o( + FluffyInstrumentIdentifiers: o( [ { json: 'BBG', js: 'BBG', typ: u(undefined, '') }, { json: 'CUSIP', js: 'CUSIP', typ: u(undefined, '') }, @@ -1503,21 +2561,29 @@ const typeMap: any = { Interaction: o( [ { json: 'description', js: 'description', typ: '' }, + { json: 'id', js: 'id', typ: u(undefined, r('InteractionID')) }, { json: 'initiator', js: 'initiator', typ: u(undefined, r('ContactElement')) }, { json: 'interactionType', js: 'interactionType', typ: '' }, { json: 'origin', js: 'origin', typ: u(undefined, '') }, { json: 'participants', js: 'participants', typ: r('ContactListObject') }, { json: 'timeRange', js: 'timeRange', typ: r('TimeRangeObject') }, { json: 'type', js: 'type', typ: '' }, - { json: 'id', js: 'id', typ: u(undefined, m('any')) }, { json: 'name', js: 'name', typ: u(undefined, '') }, ], 'any' ), + InteractionID: o( + [ + { json: 'SALESFORCE', js: 'SALESFORCE', typ: u(undefined, '') }, + { json: 'SINGLETRACK', js: 'SINGLETRACK', typ: u(undefined, '') }, + { json: 'URI', js: 'URI', typ: u(undefined, '') }, + ], + 'any' + ), Message: o( [ { json: 'entities', js: 'entities', typ: u(undefined, m(r('FluffyAction'))) }, - { json: 'text', js: 'text', typ: u(undefined, r('FluffyText')) }, + { json: 'text', js: 'text', typ: u(undefined, r('FluffyMessageText')) }, { json: 'type', js: 'type', typ: '' }, { json: 'id', js: 'id', typ: u(undefined, m('any')) }, { json: 'name', js: 'name', typ: u(undefined, '') }, @@ -1526,9 +2592,8 @@ const typeMap: any = { ), FluffyAction: o( [ - { json: 'app', js: 'app', typ: u(undefined, r('EntityApp')) }, - { json: 'context', js: 'context', typ: u(undefined, r('EntityContext')) }, - { json: 'customConfig', js: 'customConfig', typ: u(undefined, m('any')) }, + { json: 'app', js: 'app', typ: u(undefined, r('ActionTargetApp')) }, + { json: 'context', js: 'context', typ: u(undefined, r('ContextElement')) }, { json: 'intent', js: 'intent', typ: u(undefined, '') }, { json: 'title', js: 'title', typ: u(undefined, '') }, { json: 'type', js: 'type', typ: 'any' }, @@ -1545,7 +2610,7 @@ const typeMap: any = { ], 'any' ), - FluffyText: o( + FluffyMessageText: o( [ { json: 'text/markdown', js: 'text/markdown', typ: u(undefined, '') }, { json: 'text/plain', js: 'text/plain', typ: u(undefined, '') }, @@ -1573,9 +2638,9 @@ const typeMap: any = { ProductObject: o( [ { json: 'id', js: 'id', typ: m('') }, + { json: 'instrument', js: 'instrument', typ: u(undefined, r('InstrumentElement')) }, { json: 'name', js: 'name', typ: u(undefined, '') }, { json: 'type', js: 'type', typ: '' }, - { json: 'instrument', js: 'instrument', typ: u(undefined, r('InstrumentElement')) }, ], 'any' ), @@ -1600,13 +2665,13 @@ const typeMap: any = { FluffyOrderDetails: o([{ json: 'product', js: 'product', typ: u(undefined, r('ProductObject')) }], 'any'), Organization: o( [ - { json: 'id', js: 'id', typ: r('IndecentID') }, + { json: 'id', js: 'id', typ: r('OrganizationIdentifiers') }, { json: 'type', js: 'type', typ: '' }, { json: 'name', js: 'name', typ: u(undefined, '') }, ], 'any' ), - IndecentID: o( + OrganizationIdentifiers: o( [ { json: 'FDS_ID', js: 'FDS_ID', typ: u(undefined, '') }, { json: 'LEI', js: 'LEI', typ: u(undefined, '') }, @@ -1646,9 +2711,9 @@ const typeMap: any = { Product: o( [ { json: 'id', js: 'id', typ: m('') }, + { json: 'instrument', js: 'instrument', typ: u(undefined, r('InstrumentElement')) }, { json: 'name', js: 'name', typ: u(undefined, '') }, { json: 'type', js: 'type', typ: '' }, - { json: 'instrument', js: 'instrument', typ: u(undefined, r('InstrumentElement')) }, ], 'any' ), @@ -1692,7 +2757,7 @@ const typeMap: any = { TransactionResult: o( [ { json: 'context', js: 'context', typ: u(undefined, r('ContextElement')) }, - { json: 'status', js: 'status', typ: r('Status') }, + { json: 'status', js: 'status', typ: r('TransactionStatus') }, { json: 'type', js: 'type', typ: '' }, { json: 'id', js: 'id', typ: u(undefined, m('any')) }, { json: 'name', js: 'name', typ: u(undefined, '') }, @@ -1712,6 +2777,6 @@ const typeMap: any = { ], 'any' ), - Style: ['bar', 'candle', 'custom', 'heatmap', 'histogram', 'line', 'mountain', 'pie', 'scatter', 'stacked-bar'], - Status: ['Created', 'Deleted', 'Failed', 'Updated'], + ChartStyle: ['bar', 'candle', 'custom', 'heatmap', 'histogram', 'line', 'mountain', 'pie', 'scatter', 'stacked-bar'], + TransactionStatus: ['Created', 'Deleted', 'Failed', 'Updated'], }; diff --git a/website/sidebars.json b/website/sidebars.json index a04e459bf..60904acb9 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -64,10 +64,12 @@ "items": [ "context/spec", "context/ref/Context", + "context/ref/Action", "context/ref/Chart", "context/ref/ChatInitSettings", "context/ref/ChatMessage", "context/ref/ChatRoom", + "context/ref/ChatSearchCriteria", "context/ref/Contact", "context/ref/ContactList", "context/ref/Country", @@ -84,7 +86,6 @@ "context/ref/Portfolio", "context/ref/Position", "context/ref/Product", - "context/ref/ChatSearchCriteria", "context/ref/TimeRange", "context/ref/Trade", "context/ref/TradeList", @@ -98,18 +99,18 @@ "items": [ "agent-bridging/spec", "agent-bridging/ref/broadcast", + "agent-bridging/ref/findInstances", "agent-bridging/ref/findIntent", "agent-bridging/ref/findIntentsByContext", - "agent-bridging/ref/raiseIntent", - "agent-bridging/ref/open", - "agent-bridging/ref/findInstances", "agent-bridging/ref/getAppMetadata", + "agent-bridging/ref/open", "agent-bridging/ref/PrivateChannel.broadcast", "agent-bridging/ref/PrivateChannel.eventListenerAdded", "agent-bridging/ref/PrivateChannel.eventListenerRemoved", "agent-bridging/ref/PrivateChannel.onAddContextListener", "agent-bridging/ref/PrivateChannel.onDisconnect", - "agent-bridging/ref/PrivateChannel.onUnsubscribe" + "agent-bridging/ref/PrivateChannel.onUnsubscribe", + "agent-bridging/ref/raiseIntent" ] } ]