From 370565fe7b2120cb9aa7674bdaf7dc9e17787d65 Mon Sep 17 00:00:00 2001 From: Kris West Date: Wed, 26 Jul 2023 11:28:41 +0100 Subject: [PATCH] Migrating docs to schemas for another 10 context types + adjusting instrument's format --- docs/context/ref/Action.md | 15 +- docs/context/ref/ChatInitSettings.md | 2 +- docs/context/ref/ChatMessage.md | 2 +- docs/context/ref/ChatRoom.md | 4 +- src/context/schemas/action.schema.json | 80 +++++--- src/context/schemas/chart.schema.json | 103 ++++++++--- .../schemas/chatInitSettings.schema.json | 124 ++++++++++--- src/context/schemas/chatMessage.schema.json | 43 ++++- src/context/schemas/chatRoom.schema.json | 53 ++++-- .../schemas/chatSearchCriteria.schema.json | 61 +++++-- src/context/schemas/instrument.schema.json | 171 +++++++++--------- 11 files changed, 456 insertions(+), 202 deletions(-) diff --git a/docs/context/ref/Action.md b/docs/context/ref/Action.md index 8808c0462..1d547f749 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 @@ -19,7 +18,7 @@ Accepts an optional `app` parameter in order to specify a certain app. ## Schema -https://fdc3.finos.org/schemas/next/action.schema.json + ## Details @@ -33,8 +32,6 @@ https://fdc3.finos.org/schemas/next/action.schema.json | `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 7637db1ee..41782167d 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/ChatMessage.md b/docs/context/ref/ChatMessage.md index 5d8483854..a2bac96fe 100644 --- a/docs/context/ref/ChatMessage.md +++ b/docs/context/ref/ChatMessage.md @@ -14,7 +14,7 @@ A context representing a chat message. Typically used to send the message or to ## Schema -- https://fdc3.finos.org/schemas/next/chatMessage.schema.json + ## Details diff --git a/docs/context/ref/ChatRoom.md b/docs/context/ref/ChatRoom.md index a11984cec..deb38d891 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 @@ -14,7 +14,7 @@ Reference to the chat room(s) (which could be used later to send a message to th ## Schema -https://fdc3.finos.org/schemas/next/chatRoom.schema.json + ## Details diff --git a/src/context/schemas/action.schema.json b/src/context/schemas/action.schema.json index 553631232..0433bc15d 100644 --- a/src/context/schemas/action.schema.json +++ b/src/context/schemas/action.schema.json @@ -1,35 +1,67 @@ { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://fdc3.finos.org/schemas/next/action.schema.json", - "type": "object", "title": "Action", - "allOf": [{ "$ref": "context.schema.json#" }], - "properties": { - "type": { "const": "fdc3.action" }, - "title": { - "type": "string" - }, - "intent": { - "type": "string", - "$comment": "Should 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": "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": "Target App", + "description": "An optional target application identifier that should perform the action", + "allOf": [ + { "$ref": "../api/AppIdentifier.schema.json" } + ] + } }, - "required": ["appId"] + "required": [ + "title", "context" + ] }, - "customConfig": { - "type": "object" + { "$ref": "context.schema.json#" } + ], + "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/src/context/schemas/chart.schema.json b/src/context/schemas/chart.schema.json index 9a913f1ce..d82de662c 100644 --- a/src/context/schemas/chart.schema.json +++ b/src/context/schemas/chart.schema.json @@ -1,30 +1,87 @@ { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://fdc3.finos.org/schemas/next/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#" } + ], + "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/src/context/schemas/chatInitSettings.schema.json b/src/context/schemas/chatInitSettings.schema.json index 7f1c5b8c2..0678016e4 100644 --- a/src/context/schemas/chatInitSettings.schema.json +++ b/src/context/schemas/chatInitSettings.schema.json @@ -1,36 +1,114 @@ { - "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://fdc3.finos.org/schemas/next/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/chatInitSettings.schema.json", + "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#" } + ], + "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/src/context/schemas/chatMessage.schema.json b/src/context/schemas/chatMessage.schema.json index 72171d832..cedc56e87 100644 --- a/src/context/schemas/chatMessage.schema.json +++ b/src/context/schemas/chatMessage.schema.json @@ -1,13 +1,38 @@ { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://fdc3.finos.org/schemas/next/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#" } + ], + "examples": [{ + "type": "fdc3.chat.message", + "chatRoom": { + "type": "fdc3.chat.room", + "providerName": "Symphony", + "id": { + "streamId": "j75xqXy25NBOdacUI3FNBH" + } + }, + "message": "A message to send" + }] } diff --git a/src/context/schemas/chatRoom.schema.json b/src/context/schemas/chatRoom.schema.json index a5a430a6b..7baa4fb8a 100644 --- a/src/context/schemas/chatRoom.schema.json +++ b/src/context/schemas/chatRoom.schema.json @@ -1,15 +1,46 @@ { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://fdc3.finos.org/schemas/next/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" + }, + "name": { + "title": "Chat name", + "description": "Display name for the chat room", + "type": "string" + } + }, + "required": ["providerName", "id"] + }, + { "$ref": "context.schema.json#" } + ], + "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/src/context/schemas/chatSearchCriteria.schema.json b/src/context/schemas/chatSearchCriteria.schema.json index 932418859..38e735ee4 100644 --- a/src/context/schemas/chatSearchCriteria.schema.json +++ b/src/context/schemas/chatSearchCriteria.schema.json @@ -1,22 +1,49 @@ { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://fdc3.finos.org/schemas/next/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", + "allOf": [{ + "type": "object", + "properties": { + "type": { "const": "fdc3.chat.searchCriteria" }, + "criteria": { + "title": "Criteria", + "description": "An array of criteria that should match chats returned from by a search", + "type": "array", + "items": { + "anyOf": [ + { "$ref": "instrument.schema.json#" }, + { "$ref": "organization.schema.json#" }, + { "$ref": "contact.schema.json#" }, + { "type": "string" } + ] + } + } + }, + "required": ["criteria"] + }, + { "$ref": "context.schema.json#" } + ], + "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"] + ] } diff --git a/src/context/schemas/instrument.schema.json b/src/context/schemas/instrument.schema.json index 230366773..bb1ce60f3 100644 --- a/src/context/schemas/instrument.schema.json +++ b/src/context/schemas/instrument.schema.json @@ -1,99 +1,104 @@ { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://fdc3.finos.org/schemas/next/instrument.schema.json", - "type": "object", "title": "Instrument", - "description": "A financial instrument from any asset class.\n\nAny combination of instrument identifiers can be used together to resolve ambiguity, or for a better match.\n\nNotes:\n\n- 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\n- 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.\n\n- 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.\n\n- Try 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 value represents. Doing so will make interpretation easier for the developers of target applications.", + "description": "A financial instrument from any asset class.", "allOf": [ { - "$ref": "context.schema.json#" - } - ], - "properties": { - "type": { - "const": "fdc3.instrument" - }, - "id": { - "type": "object", - "properties": { - "BBG": { - "type": "string", - "title": "Bloomberg security", - "description": "" - }, - "CUSIP": { - "type": "string", - "title": "CUSIP", - "description": "" - }, - "FDS_ID": { - "type": "string", - "title": "Factset 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": { "type": "object", "properties": { - "MIC": { - "type": "string", - "title": "Market Identifier Code", - "description": "" + "type": { + "const": "fdc3.instrument" }, - "name": { - "type": "string", - "title": "Market Name", - "description": "Human readable market name" + "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 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" + } + } }, - "COUNTRY_ISOALPHA2": { - "type": "string", - "title": "Country ISO Code", - "description": "" - }, - "BBG": { - "type": "string", - "title": "Bloomberg Market Identifier", - "description": "" + "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" + } } }, - "unevaluatedProperties": { - "type": "string" - } + "required": [ + "type","id" + ] + }, + { + "$ref": "context.schema.json#" } - }, - "required": [ - "type","id" ], "examples": [ {