From e3c5183755c32db3f0381e1568569fb3048b02f2 Mon Sep 17 00:00:00 2001 From: Hugh Troeger Date: Fri, 29 Apr 2022 14:49:48 -0400 Subject: [PATCH 1/2] refactor(intents): combine overview and spec pages, reduce duplicated content --- docs/intents/overview.md | 76 ------------------------------- docs/intents/spec.md | 98 ++++++++++++++++++++++++++-------------- 2 files changed, 65 insertions(+), 109 deletions(-) delete mode 100644 docs/intents/overview.md diff --git a/docs/intents/overview.md b/docs/intents/overview.md deleted file mode 100644 index 774fab5c8..000000000 --- a/docs/intents/overview.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -id: overview -sidebar_label: Intents Overview -title: Intents Overview -hide_title: true ---- - -# Intents Overview - -Extending APIs from one application to another is powerful. However, it requires bi-lateral agreements where implementors build to proprietary APIs. A standard language for interaction between applications allows us to create workflows on the fly, so that applications can discover and link to another without any prior knowledge. - - -FDC3 Intents define a standard set of verbs that can be used to put together common cross-application workflows on the financial desktop. -* Applications register the intents & [context data](context/overview) combinations they support in the [App Directory](app-directory/overview). -* The App Directory supports application discovery by intents and/or context data. -* Intents are not full RPC, apps don’t need to enumerate every function with an intent. -* FDC3 standard intents are a limited set, organizations can create their own intents. - -## Using Intents -Combined with [context data](context/overview) and [App Directory](app-directory/overview) standards, intents enable rich service discovery on the desktop. For example: - -### Ask for a chart to be displayed -```javascript -const result = await fdc3.raiseIntent("ViewChart", { - type: "fdc3.instrument", - name: "IBM", - id: { - ticker:"ibm" - } -}); -``` - -### Ask a specific application to display a chart -```javascript -const result = await fdc3.raiseIntent("ViewChart", { - type: "fdc3.instrument", - name: "IBM", - id: { - ticker:"ibm" - } -}, "market-data-app"); -``` - -### Find applications that can start a chat -```javascript -const intentApps = await fdc3.findIntent("StartChat"); -``` - -### Find available intents for a contact -```javascript -const intentsAndApps = await fdc3.findIntentsByContext({ - type: "fdc3.contact", - name: "Jane Doe", - id: { - email:"jane@doe.com" - } -}); -``` - -## Using Intents without a context -As the [Desktop Agent API](api/ref/DesktopAgent) and [App Directory](app-directory/overview) both -require a context to specified whereever intents are used, using an intent without a context is -achieved through the use of an explcit `null` context type `fdc3.nothing`. By using an explicit type -to represent a lack of context we allow applications to declare their support for a lack of -context. - -```javascript -const intentsAndApps = await fdc3.findIntentsByContext({ - type: "fdc3.nothing", -}); - -const result = await fdc3.raiseIntent("StartChat", { - type: "fdc3.nothing" -}); -``` - diff --git a/docs/intents/spec.md b/docs/intents/spec.md index b615346df..61341f871 100644 --- a/docs/intents/spec.md +++ b/docs/intents/spec.md @@ -1,12 +1,14 @@ --- id: spec -sidebar_label: Intents Specification -title: Intents Specification (next) +sidebar_label: Overview +title: Intents Overview (next) --- -## Introduction - -FDC3 [Intents](intents-intro) define a standard set of verbs that, in conjunction with context data acting as nouns, can be used to put together common cross-application workflows on the financial desktop. +FDC3 Intents define a standard set of verbs that, in conjunction with context data acting as nouns, can be used to put together common cross-application workflows on the financial desktop. +* Applications register the intents and [context data](../context/overview) combinations they support in the [App Directory](../app-directory/overview). +* The App Directory supports application discovery by intents and/or context data. +* Intents are not full RPC, apps don’t need to enumerate every function with an intent. +* FDC3 standard intents are a limited set, organizations can create their own intents. ### Naming Syntax * Intent names should be free of non-alphanumeric characters. @@ -14,7 +16,6 @@ FDC3 [Intents](intents-intro) define a standard set of verbs that, in conjunctio * Intent names should be in UpperCamelCase. ### Characteristics - Intents shoulde be: * Recognizable * Generally self-evident what the thing is @@ -27,33 +28,64 @@ Intents shoulde be: * Distinct * Granular enough that Intent handlers can communicate key functional differences -### Namespaces ### +### Namespaces All standard intent names are reserved. Applications may use their own intents ad hoc. However, there is a need for applications to ensure that their intents avoid collision. The recommended approach here is to use the app name as the noun. For example, the ‘myChart’ App may expose the ‘ViewChart’ intent and the ‘myChart.Foo’ proprietary intent. -## Initial Set of Standard Intents ## - -### StartCall - * Expected context: Contact - * Expected behavior: initiate call with contact(s) -### StartChat - * Expected context: Contact - * Expected behavior: initiate chat with contact(s) -### ViewChart - * Expected context: Instrument - * Expected behavior: display a chart for the context -### ViewContact - * Expected context: Contact - * Expected behavior: display details of a contact -### ViewQuote - * Expected context: Instrument - * Expected behavior: display pricing for an instrument -### ViewNews - * Expected context: Instrument, Contact, Organization, etc. - * Expected behavior: display news for a given context -### ViewInstrument - * Expected context: Instrument - * Expected behavior: display relevant information for a given instrument -### ViewAnalysis - * Expected context: Instrument, Organization, etc. - * Expected behavior: Send context to receiving application for displaying analysis +## Using Intents +Combined with [context data](../context/overview) and [App Directory](../app-directory/overview) standards, intents enable rich service discovery on the desktop. For example: + +### Ask for a chart to be displayed +```javascript +const result = await fdc3.raiseIntent("ViewChart", { + type: "fdc3.instrument", + name: "IBM", + id: { + ticker:"ibm" + } +}); +``` + +### Ask a specific application to display a chart +```javascript +const result = await fdc3.raiseIntent("ViewChart", { + type: "fdc3.instrument", + name: "IBM", + id: { + ticker:"ibm" + } +}, "market-data-app"); +``` + +### Find applications that can start a chat +```javascript +const intentApps = await fdc3.findIntent("StartChat"); +``` + +### Find available intents for a contact +```javascript +const intentsAndApps = await fdc3.findIntentsByContext({ + type: "fdc3.contact", + name: "Jane Doe", + id: { + email:"jane@doe.com" + } +}); +``` + +## Using Intents without a context +As the [Desktop Agent API](../api/ref/DesktopAgent) and [App Directory](../app-directory/overview) both +require a context to specified whereever intents are used, using an intent without a context is +achieved through the use of an explcit `null` context type `fdc3.nothing`. By using an explicit type +to represent a lack of context we allow applications to declare their support for a lack of +context. + +```javascript +const intentsAndApps = await fdc3.findIntentsByContext({ + type: "fdc3.nothing", +}); + +const result = await fdc3.raiseIntent("StartChat", { + type: "fdc3.nothing" +}); +``` From b9e8f2fa320354648969330422c1d84a1e6727a3 Mon Sep 17 00:00:00 2001 From: Hugh Troeger Date: Fri, 29 Apr 2022 17:25:07 -0400 Subject: [PATCH 2/2] refactor(context): combine overview and spec pages, reduce duplicated content --- docs/context/overview.md | 63 ------------- docs/context/spec.md | 185 +++++++-------------------------------- 2 files changed, 30 insertions(+), 218 deletions(-) delete mode 100644 docs/context/overview.md diff --git a/docs/context/overview.md b/docs/context/overview.md deleted file mode 100644 index 7f93da5d4..000000000 --- a/docs/context/overview.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -id: overview -sidebar_label: Context Data Overview -title: Context Data Overview -hide_title: true ---- - -# Context Data Overview -Extending APIs from one application to another is powerful. However, it requires bi-lateral agreements where implementors build to proprietary APIs. A standard language for interaction between applications allows us to create workflows on the fly, so that applications can discover and link to one another without any prior knowledge. - -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. - -Context objects are used when raising [intents](intents-intro) and when broadcasting context to other applications. - -## Context Object - -Context can be summarised as: -* Having a unique _type_ identifier, used for routing. -* Optionally providing a name. -* Optionally providing a map of equivalent identifiers. -* Any other properties or metadata. -```typescript -interface Context { - type: string; - name?: string; - id?: { - [x:string]: string; - }, - [x: string]: any; -} -``` -## Example Context Object - -An instrument could for example be derived as (note that the name is required and the type is fixed): - -```typescript -interface Instrument extends Context { - type: 'fdc3.instrument', - name: string; - id: { - ticker?: string; - ISIN?: string; - CUSIP?: string; - } -} -``` - -e.g. as a JSON payload: - -```json -{ - "type" : "fdc3.instrument", - "name" : "Apple", - "id" : - { - "ticker" : "aapl", - "ISIN" : "US0378331005", - "CUSIP" : "037833100" - }, - "country": "US" -} -``` - It is important to note that the context data specification allows extra identifiers and properties to be added as needed for each interop use case. In the example above, `country` could represent extra data in addition to the agreed instrument representation. diff --git a/docs/context/spec.md b/docs/context/spec.md index f17be7ea3..37fb3c282 100644 --- a/docs/context/spec.md +++ b/docs/context/spec.md @@ -1,14 +1,12 @@ --- id: spec -sidebar_label: Context Data Specification -title: Context Data Specification (next) +sidebar_label: Overview +title: Context Data (next) --- -## Introduction +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. - -Exchanging context is the most basic entry point to desktop interoperability. The barriers to adoption for this interaction must be kept as low as possible. +Context objects are used when raising [intents](../intents/spec) and when broadcasting context to other applications. There are two main use cases for exchanging context data: @@ -20,7 +18,7 @@ There are two main use cases for exchanging context data: * __Transferring information between applications.__ The source application may have data required to compose a workflow with another application, e.g. a list of contacts that have been selected, or a complex object representing an RFQ request. - In many such cases there isn't any sensible reference identifiers that can be shared, it is instead the data itself being transferred. + In many such cases there aren't any sensible reference identifiers that can be shared, it is instead the data itself being transferred. ## Assumptions @@ -34,9 +32,14 @@ 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. -## The Context Interface +## Context Object -```ts +Context can be summarised as: +* Having a unique _type_ identifier, used for routing. +* Optionally providing a name. +* Optionally providing a map of equivalent identifiers. +* Any other properties or metadata. +```typescript interface Context { type: string; name?: string; @@ -46,6 +49,7 @@ interface Context { [x: string]: any; } ``` + ### Namespacing All well-known types at FDC3 level should be prefixed with `fdc3`. For private type definitions, or type definitions issued by other organisations, different namespaces can be used, e.g. `blackrock.fund`, etc. @@ -75,7 +79,7 @@ The identifier "foo" is proprietary, an application that can use it is free to d } ``` -## Standard Context Types +### Standard Context Types The following are standard FDC3 context types. __Note:__ The specification for these types are shared with the [FINOS Financial Objects](https://fo.finos.org) definitions, JSON schemas are hosted with FDC3. @@ -116,164 +120,35 @@ The following are standard FDC3 context types. - Explicit representation of a lack of context - [schema](/schemas/next/nothing.schema.json) -__Note:__ The below examples show how the base context data interface can be used to define specific context data objects. It is not the purpose of the specification at this stage to define standard representations for objects. It establishes the framework in which such definitions could be created. +### Example Context Object -### Examples +An instrument could for example be derived as (note that the name is required and the type is fixed): -#### Contact -```json -{ - "type": "fdc3.contact", - "name": "John Smith", - "id":{ - "email": "john.smith@company.com", +```typescript +interface Instrument extends Context { + type: 'fdc3.instrument', + name: string; + id: { + ticker?: string; + ISIN?: string; + CUSIP?: string; } } ``` -#### ContactList -```json -{ - "type": "fdc3.contactList", - "name": "client list", - "contacts":[ - { - "type":"fdc3.contact", - "name":"joe", - "id":{ - "email": "joe@company1.com", - } - }, - { - "type":"fdc3.contact", - "name":"jane", - "id":{ - "email": "jane@company2.com", - } - } - ] -} -``` - -#### Country -```json -{ - "type":"fdc3.country", - "name":"the USA", - "id":{ - "ISOALPHA2":"US", - "ISOALPHA3":"USA" - } -} -``` +e.g. as a JSON payload: -#### Instrument ```json { "type" : "fdc3.instrument", "name" : "Apple", - "id" : - { + "id" : + { "ticker" : "aapl", "ISIN" : "US0378331005", - "CUSIP" : "037833100", - "FIGI" : "BBG000B9XRY4", - } -} -``` - -#### InstrumentList -```json -{ - "type" : "fdc3.instrumentList", - "name" : "my portfolio", - "instruments" : [ - { - "type" : "fdc3.instrument", - "name" : "Apple", - "id": { - "ticker" : "aapl" - } - }, - { - "type" : "fdc3.instrument", - "name" : "International Business Machines", - "id": { - "ticker" : "ibm" - } - } - ] -} -``` - -#### Organization -```json -{ - "type": "fdc3.organization", - "name": "IBM", - "id": { - "PERMID" : "4295904307", - "LEI" : "VGRQXHF3J8VDLUA7XE92" - } -} -``` - -#### Portfolio -```json -{ - "type":"fdc3.portfolio", - "name":"my portfolio", - "positions":[ - { - "type": "fdc3.position", - "instrument": { - "type" : "fdc3.instrument", - "name" : "Apple", - "id" : - { - "ISIN" : "US0378331005" - } - }, - "holding": 500 - }, - { - "type": "fdc3.position", - "instrument": { - "type" : "fdc3.instrument", - "name" : "IBM", - "id" : - { - "ISIN" : "US4592001014" - } - }, - "holding": 1000 - } - ] -} -``` - - -#### Position -```json -{ - "type": "fdc3.position", - "instrument": { - "type" : "fdc3.instrument", - "name" : "Apple", - "id" : - { - "ISIN" : "US0378331005" - } + "CUSIP" : "037833100" }, - "holding": 500 + "country": "US" } ``` - -#### Nothing -```json -{ - "type": "fdc3.nothing", -} -``` - - + It is important to note that the context data specification allows extra identifiers and properties to be added as needed for each interop use case. In the example above, `country` could represent extra data in addition to the agreed instrument representation.