From 7ff9414ba88af3f9811f4e4d85795f9cf8062290 Mon Sep 17 00:00:00 2001 From: DILPREET1910 Date: Mon, 28 Oct 2024 22:13:36 +0530 Subject: [PATCH 1/2] refactored docs (markdown files) to be MDX v3 compatible --- docs/api/ref/DesktopAgent.md | 48 +++++++-------- docs/app-directory/overview.md | 6 +- docs/context/ref/Action.md | 60 +++++++++++++++++-- docs/context/ref/BaseContext.md | 3 +- docs/context/ref/Chart.md | 2 +- docs/context/ref/ChatInitSettings.md | 2 +- docs/context/ref/ChatMessage.md | 2 +- docs/context/ref/ChatRoom.md | 2 +- docs/context/ref/ChatSearchCriteria.md | 2 +- docs/context/ref/Contact.md | 2 +- docs/context/ref/ContactList.md | 2 +- docs/context/ref/Context.md | 4 +- docs/context/ref/Country.md | 2 +- docs/context/ref/Currency.md | 2 +- docs/context/ref/DocumentedContext.md | 2 +- docs/context/ref/Email.md | 2 +- docs/context/ref/Instrument.md | 2 +- docs/context/ref/InstrumentList.md | 2 +- docs/context/ref/Interaction.md | 2 +- docs/context/ref/Message.md | 2 +- docs/context/ref/Nothing.md | 2 +- docs/context/ref/Order.md | 2 +- docs/context/ref/OrderList.md | 2 +- docs/context/ref/Organization.md | 2 +- docs/context/ref/Portfolio.md | 2 +- docs/context/ref/Position.md | 2 +- docs/context/ref/Product.md | 2 +- docs/context/ref/TimeRange.md | 2 +- docs/context/ref/Trade.md | 2 +- docs/context/ref/TradeList.md | 2 +- docs/context/ref/TransactionResult.md | 2 +- docs/context/ref/Valuation.md | 2 +- docs/context/spec.md | 6 +- docs/guides/submit-new-intent.md | 2 +- docs/references.md | 46 +++++++------- toolbox/fdc3-conformance/Intents-Tests.md | 38 ++++++------ toolbox/fdc3-conformance/Metadata-Tests.md | 14 ++--- .../fdc3-conformance/User-Channel-Tests.md | 8 +-- toolbox/fdc3-explained/README.md | 2 +- .../version-1.0/api/ref/DesktopAgent.md | 38 ++++++------ .../version-1.0/appd-discovery.md | 42 ++++++------- .../version-1.0/context/ref/Chart.md | 6 +- .../version-1.0/context/ref/Email.md | 2 +- .../version-1.1/app-directory/discovery.md | 30 +++++----- .../version-1.1/appd-discovery.md | 42 ++++++------- .../version-1.2/app-directory/discovery.md | 24 ++++---- .../version-1.2/appd-discovery.md | 42 ++++++------- .../version-2.0/api/ref/DesktopAgent.md | 40 ++++++------- .../version-2.0/context/ref/Chart.md | 6 +- .../version-2.0/context/ref/Email.md | 2 +- .../version-2.1/api/ref/DesktopAgent.md | 38 ++++++------ .../version-2.1/app-directory/overview.md | 6 +- .../version-2.1/context/ref/Action.md | 2 +- .../version-2.1/context/ref/Chart.md | 8 +-- .../context/ref/ChatInitSettings.md | 2 +- .../version-2.1/context/ref/ChatMessage.md | 2 +- .../version-2.1/context/ref/ChatRoom.md | 2 +- .../context/ref/ChatSearchCriteria.md | 4 +- .../version-2.1/context/ref/Contact.md | 2 +- .../version-2.1/context/ref/ContactList.md | 2 +- .../version-2.1/context/ref/Context.md | 4 +- .../version-2.1/context/ref/Country.md | 2 +- .../version-2.1/context/ref/Currency.md | 2 +- .../version-2.1/context/ref/Email.md | 2 +- .../version-2.1/context/ref/Instrument.md | 22 +++---- .../version-2.1/context/ref/InstrumentList.md | 2 +- .../version-2.1/context/ref/Interaction.md | 8 +-- .../version-2.1/context/ref/Message.md | 6 +- .../version-2.1/context/ref/Nothing.md | 2 +- .../version-2.1/context/ref/Order.md | 4 +- .../version-2.1/context/ref/OrderList.md | 2 +- .../version-2.1/context/ref/Organization.md | 2 +- .../version-2.1/context/ref/Portfolio.md | 2 +- .../version-2.1/context/ref/Position.md | 2 +- .../version-2.1/context/ref/Product.md | 2 +- .../version-2.1/context/ref/TimeRange.md | 4 +- .../version-2.1/context/ref/Trade.md | 2 +- .../version-2.1/context/ref/TradeList.md | 2 +- .../context/ref/TransactionResult.md | 2 +- .../version-2.1/context/ref/Valuation.md | 2 +- .../version-2.1/guides/submit-new-intent.md | 2 +- .../versioned_docs/version-2.1/references.md | 46 +++++++------- 82 files changed, 404 insertions(+), 353 deletions(-) diff --git a/docs/api/ref/DesktopAgent.md b/docs/api/ref/DesktopAgent.md index 9525418b7..a5090ca52 100644 --- a/docs/api/ref/DesktopAgent.md +++ b/docs/api/ref/DesktopAgent.md @@ -47,7 +47,7 @@ interface DesktopAgent { getCurrentChannel() : Promise; leaveCurrentChannel() : Promise; - // non-context events + // non-context events addEventListener(type: FDC3EventTypes | null, handler: EventHandler): Promise; //implementation info @@ -145,7 +145,7 @@ const listener = await fdc3.addContextListener(null, context => { ... }); const contactListener = await fdc3.addContextListener('fdc3.contact', contact => { ... }); // listener that logs metadata for the message a specific type -const contactListener = await fdc3.addContextListener('fdc3.contact', (contact, metadata) => { +const contactListener = await fdc3.addContextListener('fdc3.contact', (contact, metadata) => { console.log(`Received context message\nContext: ${contact}\nOriginating app: ${metadata?.source}`); //do something else with the context }); @@ -210,7 +210,7 @@ Whenever the handler function is called it will be passed an event object with d const listener = await fdc3.addEventListener(null, event => { ... }); // listener for a specific event type that logs its details -const userChannelChangedListener = await fdc3.addEventListener("userChannelChanged ", event => { +const userChannelChangedListener = await fdc3.addEventListener("userChannelChanged ", event => { console.log(`Received event ${event.type}\n\tDetails: ${event.details}`); //do something else with the event }); @@ -277,7 +277,7 @@ const listener = fdc3.addIntentListener('StartChat', context => { }); //Handle a raised intent and log the originating app metadata -const listener = fdc3.addIntentListener('StartChat', (contact, metadata) => { +const listener = fdc3.addIntentListener('StartChat', (contact, metadata) => { console.log(`Received intent StartChat\nContext: ${contact}\nOriginating app: ${metadata?.source}`); return; }); @@ -492,7 +492,7 @@ _desktopAgent.AddIntentListener("QuoteStream", async (context, metad var disconnectListener = channel.OnDisconnect(() => { _feed.stop(symbol); }); - + return channel; }); ``` @@ -599,8 +599,8 @@ const appIntent = await fdc3.findIntent("StartChat"); // { // intent: { name: "StartChat" }, // apps: [ -// { appId: "Skype" }, -// { appId: "Symphony" }, +// { appId: "Skype" }, +// { appId: "Symphony" }, // { appId: "Slack" } // ] // } @@ -610,14 +610,14 @@ await fdc3.raiseIntent(appIntent.intent.name, context, appIntent.apps[0]); //later, we want to raise 'StartChat' intent again const appIntent = await fdc3.findIntent("StartChat"); -// returns an AppIntent, but with multiple options for resolution, +// returns an AppIntent, but with multiple options for resolution, // which includes an existing instance of an application: // { // intent: { name: "StartChat" }, // apps: [ -// { appId: "Skype" }, -// { appId: "Symphony" }, -// { appId: "Symphony", instanceId: "93d2fe3e-a66c-41e1-b80b-246b87120859" }, +// { appId: "Skype" }, +// { appId: "Symphony" }, +// { appId: "Symphony", instanceId: "93d2fe3e-a66c-41e1-b80b-246b87120859" }, // { appId: "Slack" } // ] ``` @@ -742,11 +742,11 @@ const appIntents = await fdc3.findIntentsByContext(context); // apps: [{ appId: "Skype" }] // }, // { -// intent: { name: "StartChat" }, +// intent: { name: "StartChat" }, // apps: [ -// { appId: "Skype" }, -// { appId: "Symphony" }, -// { appId: "Symphony", instanceId: "93d2fe3e-a66c-41e1-b80b-246b87120859" }, +// { appId: "Skype" }, +// { appId: "Symphony" }, +// { appId: "Symphony", instanceId: "93d2fe3e-a66c-41e1-b80b-246b87120859" }, // { appId: "Slack" } // ] // }, @@ -779,7 +779,7 @@ const appIntentsForType = await fdc3.findIntentsByContext(context, "fdc3.Contact // intent: { name: "ViewContact" }, // apps: [{ appId: "Symphony" }, { appId: "MyCRM", resultType: "fdc3.ContactList"}] // }]; - + // select a particular intent to raise const startChat = appIntents[1]; @@ -1259,7 +1259,7 @@ If an error occurs while opening the app, the promise MUST be rejected with an ` let appIdentifier = { appId: 'myApp-v1.0.1' }; let instanceIdentifier = await fdc3.open(appIdentifier); -// Open an app with context +// Open an app with context let instanceIdentifier = await fdc3.open(appIdentifier, context); ``` @@ -1271,7 +1271,7 @@ let instanceIdentifier = await fdc3.open(appIdentifier, context); var appIdentifier = new AppIdentifier("myApp-v1.0.1"); var instanceIdentifier = await _desktopAgent.Open(appIdentifier); -// Open an app with context +// Open an app with context var instanceIdentifier = await _desktopAgent.Open(appIdentifier, context); ``` @@ -1307,7 +1307,7 @@ Task RaiseIntent(string intent, IContext context, IAppIdentif Raises a specific intent for resolution against apps registered with the desktop agent. The desktop agent MUST resolve the correct app to target based on the provided intent name and context data. If multiple matching apps are found, a method for resolving the intent to a target app, such as presenting the user with a resolver UI allowing them to pick an app, SHOULD be provided. -Alternatively, the specific app or app instance to target can also be provided. A list of valid target applications and instances can be retrieved via [`findIntent`](DesktopAgent#findintent). +Alternatively, the specific app or app instance to target can also be provided. A list of valid target applications and instances can be retrieved via [`findIntent`](DesktopAgent#findintent). If a target app for the intent cannot be found with the criteria provided or the user either closes the resolver UI or otherwise cancels resolution, the promise MUST be rejected with an `Error` object with a `message` chosen from the [`ResolveError`](Errors#resolveerror) enumeration, or (if connected to a Desktop Agent Bridge) the [`BridgingError`](Errors#bridgingerror) enumeration. If a specific target `app` parameter was set, but either the app or app instance is not available, the promise MUST be rejected with an `Error` object with either the `ResolveError.TargetAppUnavailable` or `ResolveError.TargetInstanceUnavailable` string as its `message`. If an invalid context object is passed as an argument the promise MUST be rejected with an `Error` object with the [`ResolveError.MalformedContext`](Errors#resolveerror) string as its `message`. @@ -1348,7 +1348,7 @@ try { } else { console.error(`${resolution.source} didn't return anything` } -} +} catch (error: ResultError) { console.error(`${resolution.source} returned a result error: ${error}`); } @@ -1476,7 +1476,7 @@ Not implemented -Adds a listener for incoming context broadcasts from the Desktop Agent. Provided for backwards compatibility with versions FDC3 standard <2.0. +Adds a listener for incoming context broadcasts from the Desktop Agent. Provided for backwards compatibility with versions FDC3 standard <2.0. **See also:** @@ -1550,7 +1550,7 @@ Not implemented -Version of `open` that launches an app by name rather than `AppIdentifier`. Provided for backwards compatibility with versions of the FDC3 Standard <2.0. +Version of `open` that launches an app by name rather than `AppIdentifier`. Provided for backwards compatibility with versions of the FDC3 Standard <2.0. **See also:** @@ -1575,7 +1575,7 @@ Not implemented -Version of `raiseIntent` that targets an app by name rather than `AppIdentifier`. Provided for backwards compatibility with versions of the FDC3 Standard <2.0. +Version of `raiseIntent` that targets an app by name rather than `AppIdentifier`. Provided for backwards compatibility with versions of the FDC3 Standard <2.0. **See also:** @@ -1600,7 +1600,7 @@ Not implemented -Version of `raiseIntentForContext` that targets an app by name rather than `AppIdentifier`. Provided for backwards compatibility with versions of the FDC3 Standard <2.0. +Version of `raiseIntentForContext` that targets an app by name rather than `AppIdentifier`. Provided for backwards compatibility with versions of the FDC3 Standard <2.0. **See also:** diff --git a/docs/app-directory/overview.md b/docs/app-directory/overview.md index ac8062bc7..d3515f50c 100644 --- a/docs/app-directory/overview.md +++ b/docs/app-directory/overview.md @@ -91,7 +91,7 @@ knowledge of the AppD instance location. ### Authentication and Entitlements -The AppD API specification defines the optional use of an access token to identify the requesting user/launcher and implement authorizations which may affect appD API responses. For example, different subsets of the full list of applications may be returned for different users depending on their role in an organization. +The AppD API specification defines the optional use of an access token to identify the requesting user/launcher and implement authorizations which may affect appD API responses. For example, different subsets of the full list of applications may be returned for different users depending on their role in an organization. The specification does not define or make mandatory any authorizations or roles that a provider or enterprise can define. @@ -116,7 +116,7 @@ However, in order to do so, you must first discover the location of an app direc Three methods for discovering app directory services are defined in this Standard: 1. **Static configuration:** Statically defined URI records for use within client applications (typically a Desktop Agent implementation) directly. - 2. **Fully-qualified appID namespace syntax host resolution:** Discovery of the appD location using a fully qualified application ID (appId) domain name. + 2. **Fully-qualified appID namespace syntax host resolution:** Discovery of the appD location using a fully qualified application ID (appId) domain name. 3. **DNS lookup by domain name:** Discovery of the appD location using a domain name to lookup DNS SRV records identifying the host server location and TCP port. ([RFC2782](https://tools.ietf.org/html/rfc2782)) App directory service host discovery implementations SHOULD support each of these methods and MUST support at least static configuration. @@ -138,7 +138,7 @@ A launcher can then easily construct a URI by: 3. URI port is default `https/443`, but can be overridden by the launcher 4. URI url is by default `/api/appd/(version)/apps` . Calls that are made without version MUST automatically default to latest, i.e. `/api/appd/apps/app1` should return the same result as `/api/appd/v2/apps/app1". -The resulting URI to retrieve application data for `app1` would be +The resulting URI to retrieve application data for `app1` would be [https://appd.foo.com/api/appd/v2/apps/app1@appd.foo.com](https://appd.foo.com/api/appd/v2/apps/app1@appd.foo.com) ### DNS/SRV Records diff --git a/docs/context/ref/Action.md b/docs/context/ref/Action.md index 85800d3cf..db7150288 100644 --- a/docs/context/ref/Action.md +++ b/docs/context/ref/Action.md @@ -8,13 +8,16 @@ sidebar_label: 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. -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). +The action may be completed by calling: +- `fdc3.raiseIntent()` with the specified Intent and Context +- `fdc3.raiseIntentForContext()` if only a context is specified, (which the Desktop Agent will resolve by presenting the user with a list of available Intents for the Context). +- `channel.broadcast()` with the specified Context, if the `broadcast` action has been defined. Accepts an optional `app` parameter in order to specify a specific app. ## Schema - ([github](https://github.com/finos/FDC3/tree/main/schemas/context/action.schema.json)) +[https://fdc3.finos.org/schemas/next/context/action.schema.json](https://fdc3.finos.org/schemas/next/context/action.schema.json) ([github](https://github.com/finos/FDC3/tree/main/schemas/context/action.schema.json)) ## Type @@ -22,6 +25,19 @@ Accepts an optional `app` parameter in order to specify a specific app. ## Properties +
+ action + +**type**: `string` with values: +- `broadcast`, +- `raiseIntent` + +The **action** field indicates the type of action: +- **raiseIntent** : If no action or `raiseIntent` is specified, then `fdc3.raiseIntent` or `fdc3.raiseIntentForContext` will be called with the specified context (and intent if given). +- **broadcast** : If `broadcast` and a `channelId` are specified then `fdc3.getOrCreateChannel(channelId)` is called to retrieve the channel and broadcast the context to it with `channel.broadcast(context)`. If no `channelId` has been specified, the context should be broadcast to the current channel (`fdc3.broadcast()`) + +
+
title (required) @@ -50,20 +66,30 @@ A context object with which the action will be performed
+
+ channelId + +**type**: `string` + +Optional channel on which to broadcast the context. The `channelId` property is ignored unless the `action` is broadcast. + +
+
app **type**: api/AppIdentifier -An optional target application identifier that should perform the action +An optional target application identifier that should perform the action. The `app` property is ignored unless the action is raiseIntent.
-## Example +## Examples ```json { "type": "fdc3.action", + "action": "raiseIntent", "title": "Click to view Chart", "intent": "ViewChart", "context": { @@ -90,3 +116,29 @@ An optional target application identifier that should perform the action } ``` +```json +{ + "type": "fdc3.action", + "action": "broadcast", + "channelId": "Channel 1", + "title": "Click to view Chart", + "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" + } +} +``` + diff --git a/docs/context/ref/BaseContext.md b/docs/context/ref/BaseContext.md index c7f697dee..de9dc66e8 100644 --- a/docs/context/ref/BaseContext.md +++ b/docs/context/ref/BaseContext.md @@ -8,7 +8,7 @@ sidebar_label: BaseContext ## Schema - +[https://github.com/finos/FDC3/tree/main/schemas/context/context.schema.json](https://github.com/finos/FDC3/tree/main/schemas/context/context.schema.json) ## Type @@ -29,4 +29,3 @@ sidebar_label: BaseContext **type**: `object` - diff --git a/docs/context/ref/Chart.md b/docs/context/ref/Chart.md index cafa4f3a4..3437ec744 100644 --- a/docs/context/ref/Chart.md +++ b/docs/context/ref/Chart.md @@ -17,7 +17,7 @@ In addition to handling requests to plot charts, a charting application may use ## Schema - ([github](https://github.com/finos/FDC3/tree/main/schemas/context/chart.schema.json)) +[https://fdc3.finos.org/schemas/next/context/chart.schema.json](https://fdc3.finos.org/schemas/next/context/chart.schema.json) ([github](https://github.com/finos/FDC3/tree/main/schemas/context/chart.schema.json)) ## Type diff --git a/docs/context/ref/ChatInitSettings.md b/docs/context/ref/ChatInitSettings.md index 5d0b69339..4fbea5c60 100644 --- a/docs/context/ref/ChatInitSettings.md +++ b/docs/context/ref/ChatInitSettings.md @@ -10,7 +10,7 @@ A collection of settings to start a new chat conversation ## Schema - ([github](https://github.com/finos/FDC3/tree/main/schemas/context/chatInitSettings.schema.json)) +[https://fdc3.finos.org/schemas/next/context/chatInitSettings.schema.json](https://fdc3.finos.org/schemas/next/context/chatInitSettings.schema.json) ([github](https://github.com/finos/FDC3/tree/main/schemas/context/chatInitSettings.schema.json)) ## Type diff --git a/docs/context/ref/ChatMessage.md b/docs/context/ref/ChatMessage.md index 1b92ce33e..c4e0af28f 100644 --- a/docs/context/ref/ChatMessage.md +++ b/docs/context/ref/ChatMessage.md @@ -10,7 +10,7 @@ A context representing a chat message. Typically used to send the message or to ## Schema - ([github](https://github.com/finos/FDC3/tree/main/schemas/context/chatMessage.schema.json)) +[https://fdc3.finos.org/schemas/next/context/chatMessage.schema.json](https://fdc3.finos.org/schemas/next/context/chatMessage.schema.json) ([github](https://github.com/finos/FDC3/tree/main/schemas/context/chatMessage.schema.json)) ## Type diff --git a/docs/context/ref/ChatRoom.md b/docs/context/ref/ChatRoom.md index 781ae339a..50caf74b2 100644 --- a/docs/context/ref/ChatRoom.md +++ b/docs/context/ref/ChatRoom.md @@ -10,7 +10,7 @@ Reference to the chat room which could be used to send a message to the room ## Schema - ([github](https://github.com/finos/FDC3/tree/main/schemas/context/chatRoom.schema.json)) +[https://fdc3.finos.org/schemas/next/context/chatRoom.schema.json](https://fdc3.finos.org/schemas/next/context/chatRoom.schema.json) ([github](https://github.com/finos/FDC3/tree/main/schemas/context/chatRoom.schema.json)) ## Type diff --git a/docs/context/ref/ChatSearchCriteria.md b/docs/context/ref/ChatSearchCriteria.md index 6486cd5f2..a0ad9e3ac 100644 --- a/docs/context/ref/ChatSearchCriteria.md +++ b/docs/context/ref/ChatSearchCriteria.md @@ -10,7 +10,7 @@ A context type that represents a simple search criterion, based on a list of oth ## Schema - ([github](https://github.com/finos/FDC3/tree/main/schemas/context/chatSearchCriteria.schema.json)) +[https://fdc3.finos.org/schemas/next/context/chatSearchCriteria.schema.json](https://fdc3.finos.org/schemas/next/context/chatSearchCriteria.schema.json) ([github](https://github.com/finos/FDC3/tree/main/schemas/context/chatSearchCriteria.schema.json)) ## Type diff --git a/docs/context/ref/Contact.md b/docs/context/ref/Contact.md index 8056b405e..f2fd01713 100644 --- a/docs/context/ref/Contact.md +++ b/docs/context/ref/Contact.md @@ -10,7 +10,7 @@ A person contact that can be engaged with through email, calling, messaging, CMS ## Schema - ([github](https://github.com/finos/FDC3/tree/main/schemas/context/contact.schema.json)) +[https://fdc3.finos.org/schemas/next/context/contact.schema.json](https://fdc3.finos.org/schemas/next/context/contact.schema.json) ([github](https://github.com/finos/FDC3/tree/main/schemas/context/contact.schema.json)) ## Type diff --git a/docs/context/ref/ContactList.md b/docs/context/ref/ContactList.md index 6ed5ff9a6..c059e86b4 100644 --- a/docs/context/ref/ContactList.md +++ b/docs/context/ref/ContactList.md @@ -12,7 +12,7 @@ The contact list schema does not explicitly include identifiers in the `id` sect ## Schema - ([github](https://github.com/finos/FDC3/tree/main/schemas/context/contactList.schema.json)) +[https://fdc3.finos.org/schemas/next/context/contactList.schema.json](https://fdc3.finos.org/schemas/next/context/contactList.schema.json) ([github](https://github.com/finos/FDC3/tree/main/schemas/context/contactList.schema.json)) ## Type diff --git a/docs/context/ref/Context.md b/docs/context/ref/Context.md index 8a1b379b6..6606695cc 100644 --- a/docs/context/ref/Context.md +++ b/docs/context/ref/Context.md @@ -6,7 +6,7 @@ hide_title: true --- # `Context` -The `fdc3.context` type defines the basic contract or "shape" for all data exchanged by FDC3 operations. As such, it is not +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 (standardised or custom) to provide the structure and properties shared by all FDC3 context data types. @@ -24,7 +24,7 @@ can be expected to have, but this can always be extended with custom fields as a ## Schema - +[https://fdc3.finos.org/schemas/next/context/context.schema.json](https://fdc3.finos.org/schemas/next/context/context.schema.json) ## Details diff --git a/docs/context/ref/Country.md b/docs/context/ref/Country.md index 081fb515b..6684f1771 100644 --- a/docs/context/ref/Country.md +++ b/docs/context/ref/Country.md @@ -18,7 +18,7 @@ Notes: ## Schema - ([github](https://github.com/finos/FDC3/tree/main/schemas/context/country.schema.json)) +[https://fdc3.finos.org/schemas/next/context/country.schema.json](https://fdc3.finos.org/schemas/next/context/country.schema.json) ([github](https://github.com/finos/FDC3/tree/main/schemas/context/country.schema.json)) ## Type diff --git a/docs/context/ref/Currency.md b/docs/context/ref/Currency.md index 375d32d51..88f103d90 100644 --- a/docs/context/ref/Currency.md +++ b/docs/context/ref/Currency.md @@ -10,7 +10,7 @@ A context representing an individual Currency. ## Schema - ([github](https://github.com/finos/FDC3/tree/main/schemas/context/currency.schema.json)) +[https://fdc3.finos.org/schemas/next/context/currency.schema.json](https://fdc3.finos.org/schemas/next/context/currency.schema.json) ([github](https://github.com/finos/FDC3/tree/main/schemas/context/currency.schema.json)) ## Type diff --git a/docs/context/ref/DocumentedContext.md b/docs/context/ref/DocumentedContext.md index c2c154d7f..84f45a1ef 100644 --- a/docs/context/ref/DocumentedContext.md +++ b/docs/context/ref/DocumentedContext.md @@ -8,7 +8,7 @@ sidebar_label: DocumentedContext ## Schema - +[https://github.com/finos/FDC3/tree/main/schemas/context/context.schema.json](https://github.com/finos/FDC3/tree/main/schemas/context/context.schema.json) ## Type diff --git a/docs/context/ref/Email.md b/docs/context/ref/Email.md index 2c56b4ae9..c92e3fd5f 100644 --- a/docs/context/ref/Email.md +++ b/docs/context/ref/Email.md @@ -10,7 +10,7 @@ A collection of information to be used to initiate an email with a Contact or Co ## Schema - ([github](https://github.com/finos/FDC3/tree/main/schemas/context/email.schema.json)) +[https://fdc3.finos.org/schemas/next/context/email.schema.json](https://fdc3.finos.org/schemas/next/context/email.schema.json) ([github](https://github.com/finos/FDC3/tree/main/schemas/context/email.schema.json)) ## Type diff --git a/docs/context/ref/Instrument.md b/docs/context/ref/Instrument.md index 22310950d..d619ed0e9 100644 --- a/docs/context/ref/Instrument.md +++ b/docs/context/ref/Instrument.md @@ -10,7 +10,7 @@ A financial instrument from any asset class. ## Schema - ([github](https://github.com/finos/FDC3/tree/main/schemas/context/instrument.schema.json)) +[https://fdc3.finos.org/schemas/next/context/instrument.schema.json](https://fdc3.finos.org/schemas/next/context/instrument.schema.json) ([github](https://github.com/finos/FDC3/tree/main/schemas/context/instrument.schema.json)) ## Type diff --git a/docs/context/ref/InstrumentList.md b/docs/context/ref/InstrumentList.md index b01e3bdb3..1cdf1f3b0 100644 --- a/docs/context/ref/InstrumentList.md +++ b/docs/context/ref/InstrumentList.md @@ -12,7 +12,7 @@ The instrument list schema does not explicitly include identifiers in the `id` s ## Schema - ([github](https://github.com/finos/FDC3/tree/main/schemas/context/instrumentList.schema.json)) +[https://fdc3.finos.org/schemas/next/context/instrumentList.schema.json](https://fdc3.finos.org/schemas/next/context/instrumentList.schema.json) ([github](https://github.com/finos/FDC3/tree/main/schemas/context/instrumentList.schema.json)) ## Type diff --git a/docs/context/ref/Interaction.md b/docs/context/ref/Interaction.md index afadb2427..1a97caf53 100644 --- a/docs/context/ref/Interaction.md +++ b/docs/context/ref/Interaction.md @@ -10,7 +10,7 @@ An `Interaction` is a significant direct exchange of ideas or information betwee ## Schema - ([github](https://github.com/finos/FDC3/tree/main/schemas/context/interaction.schema.json)) +[https://fdc3.finos.org/schemas/next/context/interaction.schema.json](https://fdc3.finos.org/schemas/next/context/interaction.schema.json) ([github](https://github.com/finos/FDC3/tree/main/schemas/context/interaction.schema.json)) ## Type diff --git a/docs/context/ref/Message.md b/docs/context/ref/Message.md index 23c5c942c..286aec7ea 100644 --- a/docs/context/ref/Message.md +++ b/docs/context/ref/Message.md @@ -10,7 +10,7 @@ A chat message to be sent through an instant messaging application. Can contain ## Schema - ([github](https://github.com/finos/FDC3/tree/main/schemas/context/message.schema.json)) +[https://fdc3.finos.org/schemas/next/context/message.schema.json](https://fdc3.finos.org/schemas/next/context/message.schema.json) ([github](https://github.com/finos/FDC3/tree/main/schemas/context/message.schema.json)) ## Type diff --git a/docs/context/ref/Nothing.md b/docs/context/ref/Nothing.md index 8dd3d2265..b807451ea 100644 --- a/docs/context/ref/Nothing.md +++ b/docs/context/ref/Nothing.md @@ -18,7 +18,7 @@ Notes: ## Schema - ([github](https://github.com/finos/FDC3/tree/main/schemas/context/nothing.schema.json)) +[https://fdc3.finos.org/schemas/next/context/nothing.schema.json](https://fdc3.finos.org/schemas/next/context/nothing.schema.json) ([github](https://github.com/finos/FDC3/tree/main/schemas/context/nothing.schema.json)) ## Type diff --git a/docs/context/ref/Order.md b/docs/context/ref/Order.md index 2cb134994..2240c91f8 100644 --- a/docs/context/ref/Order.md +++ b/docs/context/ref/Order.md @@ -12,7 +12,7 @@ This type currently only defines a required `id` field, which should provide a r ## Schema - ([github](https://github.com/finos/FDC3/tree/main/schemas/context/order.schema.json)) +[https://fdc3.finos.org/schemas/next/context/order.schema.json](https://fdc3.finos.org/schemas/next/context/order.schema.json) ([github](https://github.com/finos/FDC3/tree/main/schemas/context/order.schema.json)) ## Type diff --git a/docs/context/ref/OrderList.md b/docs/context/ref/OrderList.md index fbb460773..7f5c963ee 100644 --- a/docs/context/ref/OrderList.md +++ b/docs/context/ref/OrderList.md @@ -12,7 +12,7 @@ The OrderList schema does not explicitly include identifiers in the id section, ## Schema - ([github](https://github.com/finos/FDC3/tree/main/schemas/context/orderList.schema.json)) +[https://fdc3.finos.org/schemas/next/context/orderList.schema.json](https://fdc3.finos.org/schemas/next/context/orderList.schema.json) ([github](https://github.com/finos/FDC3/tree/main/schemas/context/orderList.schema.json)) ## Type diff --git a/docs/context/ref/Organization.md b/docs/context/ref/Organization.md index 99a08ee32..2ada79d9d 100644 --- a/docs/context/ref/Organization.md +++ b/docs/context/ref/Organization.md @@ -12,7 +12,7 @@ It is valid to include extra properties and metadata as part of the organization ## Schema - ([github](https://github.com/finos/FDC3/tree/main/schemas/context/organization.schema.json)) +[https://fdc3.finos.org/schemas/next/context/organization.schema.json](https://fdc3.finos.org/schemas/next/context/organization.schema.json) ([github](https://github.com/finos/FDC3/tree/main/schemas/context/organization.schema.json)) ## Type diff --git a/docs/context/ref/Portfolio.md b/docs/context/ref/Portfolio.md index 8236211da..c287b2927 100644 --- a/docs/context/ref/Portfolio.md +++ b/docs/context/ref/Portfolio.md @@ -16,7 +16,7 @@ The portfolio schema does not explicitly include identifiers in the `id` section ## Schema - ([github](https://github.com/finos/FDC3/tree/main/schemas/context/portfolio.schema.json)) +[https://fdc3.finos.org/schemas/next/context/portfolio.schema.json](https://fdc3.finos.org/schemas/next/context/portfolio.schema.json) ([github](https://github.com/finos/FDC3/tree/main/schemas/context/portfolio.schema.json)) ## Type diff --git a/docs/context/ref/Position.md b/docs/context/ref/Position.md index 210f5c7e0..45859d1c4 100644 --- a/docs/context/ref/Position.md +++ b/docs/context/ref/Position.md @@ -16,7 +16,7 @@ The position schema does not explicitly include identifiers in the `id` section, ## Schema - ([github](https://github.com/finos/FDC3/tree/main/schemas/context/position.schema.json)) +[https://fdc3.finos.org/schemas/next/context/position.schema.json](https://fdc3.finos.org/schemas/next/context/position.schema.json) ([github](https://github.com/finos/FDC3/tree/main/schemas/context/position.schema.json)) ## Type diff --git a/docs/context/ref/Product.md b/docs/context/ref/Product.md index b027ccbcb..ba4a3ad7c 100644 --- a/docs/context/ref/Product.md +++ b/docs/context/ref/Product.md @@ -14,7 +14,7 @@ The Product schema does not explicitly include identifiers in the id section, as ## Schema - ([github](https://github.com/finos/FDC3/tree/main/schemas/context/product.schema.json)) +[https://fdc3.finos.org/schemas/next/context/product.schema.json](https://fdc3.finos.org/schemas/next/context/product.schema.json) ([github](https://github.com/finos/FDC3/tree/main/schemas/context/product.schema.json)) ## Type diff --git a/docs/context/ref/TimeRange.md b/docs/context/ref/TimeRange.md index 8aba9f07f..dcf6849c6 100644 --- a/docs/context/ref/TimeRange.md +++ b/docs/context/ref/TimeRange.md @@ -27,7 +27,7 @@ Notes: ## Schema - ([github](https://github.com/finos/FDC3/tree/main/schemas/context/timeRange.schema.json)) +[https://fdc3.finos.org/schemas/next/context/timeRange.schema.json](https://fdc3.finos.org/schemas/next/context/timeRange.schema.json) ([github](https://github.com/finos/FDC3/tree/main/schemas/context/timeRange.schema.json)) ## Type diff --git a/docs/context/ref/Trade.md b/docs/context/ref/Trade.md index 779cf68a3..20367252b 100644 --- a/docs/context/ref/Trade.md +++ b/docs/context/ref/Trade.md @@ -14,7 +14,7 @@ This type currently only defines a required `id` field, which should provide a r ## Schema - ([github](https://github.com/finos/FDC3/tree/main/schemas/context/trade.schema.json)) +[https://fdc3.finos.org/schemas/next/context/trade.schema.json](https://fdc3.finos.org/schemas/next/context/trade.schema.json) ([github](https://github.com/finos/FDC3/tree/main/schemas/context/trade.schema.json)) ## Type diff --git a/docs/context/ref/TradeList.md b/docs/context/ref/TradeList.md index d6d33b88c..e5f4e6988 100644 --- a/docs/context/ref/TradeList.md +++ b/docs/context/ref/TradeList.md @@ -12,7 +12,7 @@ The TradeList schema does not explicitly include identifiers in the id section, ## Schema - ([github](https://github.com/finos/FDC3/tree/main/schemas/context/tradeList.schema.json)) +[https://fdc3.finos.org/schemas/next/context/tradeList.schema.json](https://fdc3.finos.org/schemas/next/context/tradeList.schema.json) ([github](https://github.com/finos/FDC3/tree/main/schemas/context/tradeList.schema.json)) ## Type diff --git a/docs/context/ref/TransactionResult.md b/docs/context/ref/TransactionResult.md index 3d10cf01c..a968c3ff1 100644 --- a/docs/context/ref/TransactionResult.md +++ b/docs/context/ref/TransactionResult.md @@ -10,7 +10,7 @@ A context type representing the result of a transaction initiated via FDC3, whic ## Schema - ([github](https://github.com/finos/FDC3/tree/main/schemas/context/transactionresult.schema.json)) +[https://fdc3.finos.org/schemas/next/context/transactionresult.schema.json](https://fdc3.finos.org/schemas/next/context/transactionresult.schema.json) ([github](https://github.com/finos/FDC3/tree/main/schemas/context/transactionresult.schema.json)) ## Type diff --git a/docs/context/ref/Valuation.md b/docs/context/ref/Valuation.md index 7d7bfeaa0..273efc4de 100644 --- a/docs/context/ref/Valuation.md +++ b/docs/context/ref/Valuation.md @@ -10,7 +10,7 @@ A context type representing the price and value of a holding. ## Schema - ([github](https://github.com/finos/FDC3/tree/main/schemas/context/valuation.schema.json)) +[https://fdc3.finos.org/schemas/next/context/valuation.schema.json](https://fdc3.finos.org/schemas/next/context/valuation.schema.json) ([github](https://github.com/finos/FDC3/tree/main/schemas/context/valuation.schema.json)) ## Type diff --git a/docs/context/spec.md b/docs/context/spec.md index f001ac1c3..af838911c 100644 --- a/docs/context/spec.md +++ b/docs/context/spec.md @@ -97,7 +97,7 @@ or in JSON Schema as: :::note -This is a simplified version of the schema for illustrative purposes, the fully documented Context schema, which is composed with other FDC3 Standard context schemas, can be found at: . +This is a simplified version of the schema for illustrative purposes, the fully documented Context schema, which is composed with other FDC3 Standard context schemas, can be found at: [https://fdc3.finos.org/schemas/next/context/context.schema.json](https://fdc3.finos.org/schemas/next/context/context.schema.json). ::: @@ -360,8 +360,8 @@ e.g. as a JSON payload: { "type" : "fdc3.instrument", "name" : "Apple", - "id" : - { + "id" : + { "ticker" : "aapl", "ISIN" : "US0378331005", "CUSIP" : "037833100" diff --git a/docs/guides/submit-new-intent.md b/docs/guides/submit-new-intent.md index 35d29bddc..27e72d227 100644 --- a/docs/guides/submit-new-intent.md +++ b/docs/guides/submit-new-intent.md @@ -21,7 +21,7 @@ To run the website locally ```yarn start``` -This will open the home page or browse to +This will open the home page or browse to [https://localhost:3000](https://localhost:3000) Note that the page opens on the current release version of the docs and you will be changing the latest version. Click the version selector in the top left hand corner diff --git a/docs/references.md b/docs/references.md index 379c5342d..9efdaea90 100644 --- a/docs/references.md +++ b/docs/references.md @@ -7,29 +7,29 @@ sidebar_label: References The following normative documents contain provisions, which, through reference in this text, constitute provisions of this Standard. For dated references, subsequent amendments to, or revisions of, any of these publications do not apply. However, parties to agreements based on this Standard are encouraged to investigate the possibility of applying the most recent editions of the normative documents indicated below. For undated references, the latest edition of the normative document referred to applies: -- **Apache 2.0 open-source license**, . -- **Community Specification license**, -- **ISO 3166-1**, _Codes for the representation of names of countries and their subdivisions – Part 1: Country codes_, . -- **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_, . -- **RFC 5646**, _Tags for Identifying Languages, September 2009_, . -- **TypeScript Programming Language**, . -- **Web Application Manifest**, _W3C Working Draft_, February 2022 +- **Apache 2.0 open-source license**, [https://www.apache.org/licenses/LICENSE-2.0](https://www.apache.org/licenses/LICENSE-2.0). +- **Community Specification license**, [https://github.com/CommunitySpecification/1.0](https://github.com/CommunitySpecification/1.0) +- **ISO 3166-1**, _Codes for the representation of names of countries and their subdivisions – Part 1: Country codes_, [https://www.iso.org/iso-3166-country-codes.html](https://www.iso.org/iso-3166-country-codes.html). +- **ISO 8601-1:2019**, _Date and time — Representations for information interchange — Part 1: Basic rules_, [https://www.iso.org/standard/70907.html](https://www.iso.org/standard/70907.html) +- **JSON Schema**, [https://json-schema.org/](https://json-schema.org/). +- **OpenAPI Standard v3.0**, [https://www.openapis.org/](https://www.openapis.org/). +- **quicktype**, [https://quicktype.io/](https://quicktype.io/). +- **RFC 2119**, _Keywords for use in RFCs to Indicate Requirement Levels, March 1997_, [https://datatracker.ietf.org/doc/html/rfc2119](https://datatracker.ietf.org/doc/html/rfc2119). +- **RFC 2782**, _A DNS RR for specifying the location of services (DNS SRV), February 2000_, [https://datatracker.ietf.org/doc/html/rfc2782](https://datatracker.ietf.org/doc/html/rfc2782). +- **RFC 4122**, _A Universally Unique IDentifier (UUID) URN Namespace, July 2005_, [https://datatracker.ietf.org/doc/html/rfc4122](https://datatracker.ietf.org/doc/html/rfc4122). +- **RFC 5646**, _Tags for Identifying Languages, September 2009_, [https://datatracker.ietf.org/doc/html/rfc5646](https://datatracker.ietf.org/doc/html/rfc5646). +- **TypeScript Programming Language**, [https://www.typescriptlang.org/](https://www.typescriptlang.org/). +- **Web Application Manifest**, _W3C Working Draft_, February 2022 [https://www.w3.org/TR/appmanifest/](https://www.w3.org/TR/appmanifest/) The following documents may be useful in understanding certain aspects of this Standard; however, knowledge of them is not essential to the creation of a compliant implementation of this Standard: -- **CUSIP**, _Committee on Uniform Security Identification Procedures_, . -- **FIGI**, _Financial Instrument Global Identifier_, . -- **ISIN**, _International Securities Identification Number_, -- **LEI**, _Legal Entity Identifier based on the ISO 17442 standard_, . -- **npm**, . -- **PermID**, _Permanent Identifiers_, . -- **pnpm**, . -- **REST**, , . -- **SEDOL**, _Stock Exchange Daily Official List_, . -- **yarn**, . +- **CUSIP**, _Committee on Uniform Security Identification Procedures_, [https://www.cusip.com/identifiers.html#/CUSIP](https://www.cusip.com/identifiers.html#/CUSIP). +- **FIGI**, _Financial Instrument Global Identifier_, [https://www.openfigi.com/about/figi](https://www.openfigi.com/about/figi). +- **ISIN**, _International Securities Identification Number_, [https://www.isin.org/isin/](https://www.isin.org/isin/) +- **LEI**, _Legal Entity Identifier based on the ISO 17442 standard_, [https://www.legalentityidentifier.co.uk/what-is-lei-code/](https://www.legalentityidentifier.co.uk/what-is-lei-code/). +- **npm**, [https://docs.npmjs.com/about-npm](https://docs.npmjs.com/about-npm). +- **PermID**, _Permanent Identifiers_, [https://permid.org/](https://permid.org/). +- **pnpm**, [https://pnpm.io/motivation](https://pnpm.io/motivation). +- **REST**, [https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm), [https://restfulapi.net/](https://restfulapi.net/). +- **SEDOL**, _Stock Exchange Daily Official List_, [https://www.lseg.com/sedol](https://www.lseg.com/sedol). +- **yarn**, [https://yarnpkg.com/getting-started](https://yarnpkg.com/getting-started). diff --git a/toolbox/fdc3-conformance/Intents-Tests.md b/toolbox/fdc3-conformance/Intents-Tests.md index 6d331a5a3..cec99c9fe 100644 --- a/toolbox/fdc3-conformance/Intents-Tests.md +++ b/toolbox/fdc3-conformance/Intents-Tests.md @@ -35,8 +35,8 @@ Also we assume a fourth app **D** that is going to discover the intents in the o | App | Step | Details | |-----|----------------|---------------------------------------------------------------------------------------------------| -| D | 1. Raise | `fdc3.raiseIntent(‘sharedTestingIntent1’, {testContextY})`
starts app B. | -| B | 2. Gather Context | `fdc.addIntentListener(‘sharedTestingIntent1’)`
Receives testContextY, matching that sent by D | +| D | 1. Raise | `fdc3.raiseIntent(‘sharedTestingIntent1’, {testContextY})`
starts app B. | +| B | 2. Gather Context | `fdc.addIntentListener(‘sharedTestingIntent1’)`
Receives testContextY, matching that sent by D | - `SingleResolve1`: Perform above test - `TargetedResolve1`: Use `fdc3.raiseIntent(‘aTestingIntent’, {testContextX}, )` to start app A, otherwise, as above @@ -117,8 +117,8 @@ Finally, please note that this is a larger set of apps than were required for 1. | App | Step | Details | |-------|----------------|---------------------------------------------------------------------------------------------------| -| Test | 1. Raise | `fdc3.raiseIntent("aTestingIntent", testContextX)`
starts app A. | -| A | 2. Receive Intent & Context | After starting up, A runs `fdc3.addIntentListener("aTestingIntent1")` to register its listener.
It then receives `testContextX`, matching that sent by Test | +| Test | 1. Raise | `fdc3.raiseIntent("aTestingIntent", testContextX)`
starts app A. | +| A | 2. Receive Intent & Context | After starting up, A runs `fdc3.addIntentListener("aTestingIntent1")` to register its listener.
It then receives `testContextX`, matching that sent by Test | | Test | 3. IntentResolution | The `raiseIntent` call returns an `IntentResolution` Object with an `AppIdentifier` as the `source field` with App A's `appId` and `instanceId` set.** | - `2.0-RaiseIntentSingleResolve`: Perform above test @@ -127,12 +127,12 @@ Finally, please note that this is a larger set of apps than were required for 1. - Otherwise, as above. - `2.0-RaiseIntentTargetedInstanceResolveOpen`: Repeat the above test, but: - Before the first step, use `let appIdentifier = await fdc3.open({appId: ""})` to start A and retrieve its `AppIdentifier` with instance details. - - Then in the first step, use `fdc3.raiseIntent("aTestingIntent", testContextX, appIdentifier)` to target the running instance of app A. + - Then in the first step, use `fdc3.raiseIntent("aTestingIntent", testContextX, appIdentifier)` to target the running instance of app A. - Confirm that the intent is delivered to the correct instance and that another instance is NOT started. Otherwise, as above. - `2.0-RaiseIntentTargetedInstanceResolveFindInstances`: Repeat the above test, but: - Before the first step, use `let appIdentifier = await fdc3.open({appId: ""})` to start A. - Then use `const instances = await fdc3.findInstances({appId: ""})` to retrieve a list of instances of app A. Confirm that only one is present and retrieve its `AppIdentifier`, confirming that it contains an `instanceId` field that matches that returned by the `fdc3.open` call. - - Then in the first step, use `fdc3.raiseIntent("aTestingIntent", testContextX, appIdentifier)` to target the running instance of app A. + - Then in the first step, use `fdc3.raiseIntent("aTestingIntent", testContextX, appIdentifier)` to target the running instance of app A. - Confirm that the intent is delivered to the correct instance and that another instance is NOT started. Otherwise, as above. - `2.0-RaiseIntentFailedResolve`: Perform above test, but: - Use `fdc3.raiseIntent("aTestingIntent", testContextY)`. Note that no app supports this intent and context combination.** @@ -147,24 +147,24 @@ Finally, please note that this is a larger set of apps than were required for 1. - Use `fdc3.raiseIntent("sharedTestingIntent2", testContextY, {appId: ""})`. - You should receive a JavaScript Error with the message `ResolveError.IntentDeliveryFailed` (as this app is configured for the intent and context pair, but does not add any intent listeners). - **Note: Test will need an extended timeout to allow for this to be returned in time by the desktop agent, which will have a vendor-defined timeout.** -- `2.0-RaiseIntentFailTargetedAppResolve4`: Perform above test, but: +- `2.0-RaiseIntentFailTargetedAppResolve4`: Perform above test, but: - `fdc3.raiseIntent("sharedTestingIntent2", testContextY, {appId: ""})` - You should receive a JavaScript Error with the message `ResolveError.IntentDeliveryFailed` (as this app is configured for the intent and context pair, but adds intent listeners of the wrong type. - **Note: Test will need an extended timeout to allow for this to be returned in time by the desktop agent, which will have a vendor-defined timeout.** - `2.0-RaiseIntentFailTargetedAppInstanceResolve1`: Perform above test, but: - First spawn an instance of App **A** and collect its `AppIdentifier` with `const appIdentifier = await fdc3.open({appId: ""})`. - - Then use `fdc3.raiseIntent("aTestingIntent", testContextY, appIdentifier)` to target that instance. + - Then use `fdc3.raiseIntent("aTestingIntent", testContextY, appIdentifier)` to target that instance. - You should receive a JavaScript Error with the message `ResolveError.NoAppsFound` (since A doesn't support this context type). - `2.0-RaiseIntentFailTargetedAppInstanceResolve2`: Perform above test, but: - - Use `fdc3.raiseIntent("aTestingIntent", testContextX, {appId: "", instanceId "NonExistentInstanceId"})`. + - Use `fdc3.raiseIntent("aTestingIntent", testContextX, {appId: "", instanceId "NonExistentInstanceId"})`. - You should receive a JavaScript Error with the message `ResolveError.TargetInstanceUnavailable`. ### Raise Intent Result (void result) | App | Step | Details | |-----|----------------|---------------------------------------------------------------------------------------------------| -| Test | 1. Raise | `fdc3.raiseIntent("aTestingIntent", testContextX)`
starts app A. | -| A | 2. Receive Intent & Context | After starting up, A runs `fdc3.addIntentListener("aTestingIntent")` to register its listener.
It then receives `testContextX`, matching that sent by Test | +| Test | 1. Raise | `fdc3.raiseIntent("aTestingIntent", testContextX)`
starts app A. | +| A | 2. Receive Intent & Context | After starting up, A runs `fdc3.addIntentListener("aTestingIntent")` to register its listener.
It then receives `testContextX`, matching that sent by Test | | Test | 3. IntentResolution | The `raiseIntent` call returns an `IntentResolution` Object with an `AppIdentifier` as the `source field` with App A's `appId` and `instanceId` set. | | Test | 4. await results | Test should `await resolution.getResult()` on the `IntentResolution` object returned in the previous step. A promise should be returned quickly. | | A | 5. return void | A should return `void` after a short delay (e.g. 5 seconds). | @@ -178,8 +178,8 @@ Finally, please note that this is a larger set of apps than were required for 1. | App | Step | Details | |-----|----------------|---------------------------------------------------------------------------------------------------| -| Test | 1. Raise | `fdc3.raiseIntent("sharedTestingIntent1", testContextY)`
starts app **B**. | -| B | 2. Receive Intent & Context | After starting up, B runs `fdc3.addIntentListener("sharedTestingIntent1")` to register its listener.
It then receives `testContextY`, matching that sent by Test | +| Test | 1. Raise | `fdc3.raiseIntent("sharedTestingIntent1", testContextY)`
starts app **B**. | +| B | 2. Receive Intent & Context | After starting up, B runs `fdc3.addIntentListener("sharedTestingIntent1")` to register its listener.
It then receives `testContextY`, matching that sent by Test | | Test | 3. IntentResolution | The `raiseIntent` call returns an `IntentResolution` Object with an `AppIdentifier` as the `source field` with App B's `appId` and `instanceId` set. | | Test | 4. await results | Test should `await resolution.getResult()` on the `IntentResolution` object returned in the previous step. A promise should be returned quickly. | | B | 5. return `testContextY` | B should return a `testContextY` instance after a short delay (e.g. 5 seconds). | @@ -193,8 +193,8 @@ Finally, please note that this is a larger set of apps than were required for 1. | App | Step | Details | |-------|-----------------------|---------------------------------------------------------------------------------------------------| -| Test | 1. Raise Intent | Test raises an intent with `fdc3.raiseIntent("sharedTestingIntent2", testContextY, {appId: ""})`
starts app E. | -| E | 2. Receive Intent & Context | After starting up, E runs `fdc3.addIntentListener("sharedTestingIntent2")` to register its listener.
It them receives `testContextY`, matching that sent by Test | +| Test | 1. Raise Intent | Test raises an intent with `fdc3.raiseIntent("sharedTestingIntent2", testContextY, {appId: ""})`
starts app E. | +| E | 2. Receive Intent & Context | After starting up, E runs `fdc3.addIntentListener("sharedTestingIntent2")` to register its listener.
It them receives `testContextY`, matching that sent by Test | | Test | 3. IntentResolution | The `raiseIntent` call returns an `IntentResolution` Object with an `AppIdentifier` as the `source field` with App E's `appId` and `instanceId` set. | | Test | 4. await results | Test should `await resolution.getResult()` on the `IntentResolution` object returned in the previous step. A promise should be returned quickly. | | E | 5. return Channel | E should retrieve a Channel object via `fdc3.getOrCreateChannel("someChannelName")` and return it immediately. | @@ -227,11 +227,11 @@ Finally, please note that this is a larger set of apps than were required for 1. | App | Step | Details | |-------|-----------------|---------------------------------------------------------------------------------------------------| -| Test | 1. Raise intent | Test raises an intent with `fdc3.raiseIntent(‘"kTestingIntent", testContextX, {appId: ""})`
starts app K. | -| K | 2. Receive Intent & Context | After starting up, K runs `fdc3.addIntentListener("kTestingIntent")` to register its listener.
It them receives `testContextX`, matching that sent by Test | +| Test | 1. Raise intent | Test raises an intent with `fdc3.raiseIntent(‘"kTestingIntent", testContextX, {appId: ""})`
starts app K. | +| K | 2. Receive Intent & Context | After starting up, K runs `fdc3.addIntentListener("kTestingIntent")` to register its listener.
It them receives `testContextX`, matching that sent by Test | | Test | 3. IntentResolution | The `raiseIntent` call returns an `IntentResolution` Object with an `AppIdentifier` as the `source field` with App K's `appId` and `instanceId` set. | | Test | 4. await results | Test should `await resolution.getResult()` on the `IntentResolution` object returned in the previous step. A promise should be returned quickly. | -| K | 5. Create PrivateChannel and setup event listeners | K should create a `PrivateChannel` object via `const privChan = await fdc3.createPrivateChannel()`,
it should then add listeners for the 3 events offered + a context listener via:
- `const listener1 = await privChan.onAddContextListener(handler1);`
- `const listener2 = await privChan.onUnsubscribe(handler2);`
- `const listener3 = await privChan.onDisconnect(handler3);`
- `const listener4 = await privChan.addContextListener("testContextX", handler4)`
it should then return the `PrivateChannel`. | +| K | 5. Create PrivateChannel and setup event listeners | K should create a `PrivateChannel` object via `const privChan = await fdc3.createPrivateChannel()`,
it should then add listeners for the 3 events offered + a context listener via:
- `const listener1 = await privChan.onAddContextListener(handler1);`
- `const listener2 = await privChan.onUnsubscribe(handler2);`
- `const listener3 = await privChan.onDisconnect(handler3);`
- `const listener4 = await privChan.addContextListener("testContextX", handler4)`
it should then return the `PrivateChannel`. | | Test | 6. receive PrivateChannel | The promise received by Test from `resolution.getResult()` should resolve to a `PrivateChannel` object. Confirm that the `type` of the Channel object is "private". | Test | 7. addContextListener | Test should add a context listener to the PrivateChannel object via `const listener1 = privChan.addContextListener("testContextZ", handler)` | | K | 8. Receive event & broadcast context | The `onAddContextListener` handler (`listener1`) added in step 5 should fire after Test adds its listener. Once it has, K should broadcast a short stream of `testContextZ` objects, with consecutive integer values in them (e.g. 1-5). | @@ -248,7 +248,7 @@ Finally, please note that this is a larger set of apps than were required for 1. ### Resolving Ambiguous Intents -FDC3 Desktop Agent MUST provide a method of resolving ambiguous intents (i.e. those that might be resolved by multiple applications) or unspecified intents (calls to raiseIntentForContext that return multiple options). This is often accomplished by providing a user interface allowing the user to select the desired target application or intent and application. +FDC3 Desktop Agent MUST provide a method of resolving ambiguous intents (i.e. those that might be resolved by multiple applications) or unspecified intents (calls to raiseIntentForContext that return multiple options). This is often accomplished by providing a user interface allowing the user to select the desired target application or intent and application. As the methods of resolving ambiguous intents are often user interactive, it is either difficult or impossible to implement an automated test for this. Hence, manual tests should be performed as a final step in a conformance test. These tests are based on the same applications defined for and used in other intent tests - however a separate manual test app should be provided to enable the test. diff --git a/toolbox/fdc3-conformance/Metadata-Tests.md b/toolbox/fdc3-conformance/Metadata-Tests.md index 8fdcaf2f7..d62ce5fad 100644 --- a/toolbox/fdc3-conformance/Metadata-Tests.md +++ b/toolbox/fdc3-conformance/Metadata-Tests.md @@ -1,11 +1,11 @@ -# Metadata & Instance Test Cases +# Metadata & Instance Test Cases You will need to pre-populate the AppDirectory with the following items: | App | Required Metadata | |-----|------------------------------------------| -| A | Generic AppD Record which contains at least the following fields:
- `name`
- `version`
- `title`
- `tooltip`
- `description`
- `icons` (`Array`)
- `screenshots` (`Array`)
- `interop.intents.listensFor` (`aTestingIntent` with at least context type `testContextX`) | +| A | Generic AppD Record which contains at least the following fields:
- `name`
- `version`
- `title`
- `tooltip`
- `description`
- `icons` (`Array`)
- `screenshots` (`Array`)
- `interop.intents.listensFor` (`aTestingIntent` with at least context type `testContextX`) | ## Retrieve `AppMetadata` ![2.0](https://img.shields.io/badge/FDC3-2.0-blue) @@ -21,7 +21,7 @@ You will need to pre-populate the AppDirectory with the following items: | App | Step | Details | |-----|----------------|---------------------------------------------------------------------------------------------------| | Test | 1.Open1 | Open a first instance of App A using
`const appIdentifier1 = await fdc3.open({appId: ""})`
and confirm that its `AppIdentifier` contains an `instanceId`. | -| Test | 2.Open2 |Open a second instance of App A using
`const appIdentifier2 = await fdc3.open({appId: ""})`
and confirm that its `AppIdentifier` contains an `instanceId` and that its value differs from that returned for the first instance. | +| Test | 2.Open2 |Open a second instance of App A using
`const appIdentifier2 = await fdc3.open({appId: ""})`
and confirm that its `AppIdentifier` contains an `instanceId` and that its value differs from that returned for the first instance. | | Test | 3.getAppMetadata1 | Retrieve metadata for the first instance of the app with
`const metadata1 = fdc3.getAppMetadata(appIdentifier1)` | | Test | 4.Confirm1 | Compare the `AppMetadata` object to the expected definition for the fields provided above during setup and ensure that the metadata matches. | | Test | 5.getAppMetadata2 | Retrieve metadata for the second instance of the app with
`const metadata2 = fdc3.getAppMetadata(appIdentifier2)` | @@ -34,7 +34,7 @@ You will need to pre-populate the AppDirectory with the following items: | App | Step | Details | |-----|----------------|---------------------------------------------------------------------------------------------------| | Test | 1.Open1 | Open the first instance of App A using
`const appIdentifier1 = await fdc3.open({appId: ""})`
and confirm that its `AppIdentifier` contains an `instanceId`. | -| Test | 2.Open2 |Open a second instance of App A using
`const appIdentifier2 = await fdc3.open({appId: ""})`
and confirm that its `AppIdentifier` contains an `instanceId` and that its value differs from that returned for the first instance. | +| Test | 2.Open2 |Open a second instance of App A using
`const appIdentifier2 = await fdc3.open({appId: ""})`
and confirm that its `AppIdentifier` contains an `instanceId` and that its value differs from that returned for the first instance. | | Test | 3.FindInstances | Retrieve details of open instances of app A with
`let instances = await fdc3.findInstances({appId: ""})`
confirm that both `appIdentifier1` and `appIdentifier2` are both present in the array. | | Test | 4.RaiseIntent | Use `appIdentifier1` to raise an intent and target that instance, with
`const resolution = fdc3.raiseIntent("aTestingIntent", {"type": "testContextX"}, appIdentifier1)` | | Test | 5.Confirm1 | Check that `resolution.source` matches `appIdentifier1` | @@ -47,11 +47,11 @@ You will need to pre-populate the AppDirectory with the following items: | App | Step | Details | |-----|----------------|---------------------------------------------------------------------------------------------------| | Test | 1.getInfo |Retrieve the `ImplementationMetadata` for the DesktopAgent with
- ![1.2](https://img.shields.io/badge/FDC3-1.2-green) `let implMetadata = fdc3.getInfo()`
- ![2.0](https://img.shields.io/badge/FDC3-2.0-blue) `fdc3.getInfo().then((implMetadata) => { subsequent steps }`
**Note that the use of `then` is deliberate and intended to confirm that a promise returned (as this function switched from synchronous to asynchronous in 2.0)**| -| Test | 2.CheckVersion | Check that the `fdc3Version` variable is present and at or greater than:
- ![1.2](https://img.shields.io/badge/FDC3-1.2-green) 1.2
- ![2.0](https://img.shields.io/badge/FDC3-2.0-blue) 2.0
(which you can do with the [`versionIsAtLeast` function from FDC3's Methods.ts](https://github.com/finos/FDC3/blob/add64f8302c6dcdc8437cf0e245101e927b69ec2/src/api/Methods.ts#L207):
`const isFDC3v2 = versionIsAtLeast(implMetadata, "2.0")` | +| Test | 2.CheckVersion | Check that the `fdc3Version` variable is present and at or greater than:
- ![1.2](https://img.shields.io/badge/FDC3-1.2-green) 1.2
- ![2.0](https://img.shields.io/badge/FDC3-2.0-blue) 2.0
(which you can do with the [`versionIsAtLeast` function from FDC3's Methods.ts](https://github.com/finos/FDC3/blob/add64f8302c6dcdc8437cf0e245101e927b69ec2/src/api/Methods.ts#L207):
`const isFDC3v2 = versionIsAtLeast(implMetadata, "2.0")` | | Test | 3.CheckProvider | Check that the `provider` variable is present and not an empty string | | Test | 4.CheckFeatures | ![2.0](https://img.shields.io/badge/FDC3-2.0-blue) Check that the `optionalFeatures`, `optionalFeatures.OriginatingAppMetadata` and `optionalFeatures.UserChannelMembershipAPIs` variables are all present and that the latter two provide boolean values | -- ![1.2](https://img.shields.io/badge/FDC3-1.2-green) ![2.0](https://img.shields.io/badge/FDC3-2.0-blue) `GetInfo1`: Perform the above steps +- ![1.2](https://img.shields.io/badge/FDC3-1.2-green) ![2.0](https://img.shields.io/badge/FDC3-2.0-blue) `GetInfo1`: Perform the above steps | App | Step | Details | |-----|----------------|---------------------------------------------------------------------------------------------------| @@ -59,4 +59,4 @@ You will need to pre-populate the AppDirectory with the following items: | A | 2.getInfo | Retrieve the `ImplementationMetadata` for the DesktopAgent with:
`fdc3.getInfo().then((implMetadata) => { ... subsequent steps ...}`
This should include `AppMetadata` for the retrieving app. | | A + Test | 3.Confirm | Check that `implMetadata.appMetadata` contains an `appId` and `instanceId` matching that retrieved in the first step (will require transmission of the details from A to Test or vice-versa). Also compare the `AppMetadata` object to the expected definition for the fields provided above during setup and ensure that the metadata matches. | -- ![2.0](https://img.shields.io/badge/FDC3-2.0-blue) `GetInfo2`: Perform the above steps. +- ![2.0](https://img.shields.io/badge/FDC3-2.0-blue) `GetInfo2`: Perform the above steps. diff --git a/toolbox/fdc3-conformance/User-Channel-Tests.md b/toolbox/fdc3-conformance/User-Channel-Tests.md index 923a5332c..304b60ac0 100644 --- a/toolbox/fdc3-conformance/User-Channel-Tests.md +++ b/toolbox/fdc3-conformance/User-Channel-Tests.md @@ -13,7 +13,7 @@ _NB: User Channels were called System Channels in FDC3 1.2. The new terminolog | B | 4.Broadcast | B broadcasts an `fdc3.instrument` context to the channel using `fdc3.broadcast()`.
![2.0](https://img.shields.io/badge/FDC3-2.0-blue) Check a `void` promise is returned. | | A | 5.Receive Context | A receives the instrument object, matching the one broadcast by B. | -- `UCBasicUsage1` Perform above test +- `UCBasicUsage1` Perform above test - `UCBasicUsage2` Perform steps in order: 2,1,3,4,5 to confirm that the order of `joinUserChannel` and `addContextListener` calls doesn't matter - `UCBasicUsage3` Perform steps in order: 3,4,1,2,5 to confirm that the current context is automatically received on joining a channel. - `UCBasicUsage4` Perform steps in order: 3,4,2,1,5 to confirm that the current context is automatically received on adding a context listener to an already joined a channel. @@ -28,7 +28,7 @@ _NB: User Channels were called System Channels in FDC3 1.2. The new terminolog | B | 4.Broadcast | B broadcasts:
1.`fdc3.broadcast()`.
2. `fdc3.broadcast()`
![2.0](https://img.shields.io/badge/FDC3-2.0-blue) Check a `void` promise is returned. | | A | 5.Receive Context | A receives the `fdc3.instrument` object, matching the one broadcast by B.
Check that the `fdc3.contact` is NOT received. | -- `UCFilteredUsage1` Perform above test +- `UCFilteredUsage1` Perform above test - `UCFilteredUsage2` Perform steps in order: 2,1,3,4,5 - `UCFilteredUsage3` Perform steps in order: 3,4,1,2,5 - `UCFilteredUsage4` Perform steps in order: 3,4,2,1,5 @@ -41,11 +41,11 @@ _NB: User Channels were called System Channels in FDC3 1.2. The new terminolog | A | 2.joinUserChannel |A joins the first available user channel using:
![1.2](https://img.shields.io/badge/FDC3-1.2-green) `getSystemChannels()` Check channels are returned.
![2.0](https://img.shields.io/badge/FDC3-2.0-blue) `getUserChannels()` Check **user** channels are returned.
Call `fdc3.joinChannel()` on the first non-global channel.| | B | 3.joinUserChannel |B joins the same channel as A, via the same process in 2. | | B | 4.Broadcast | `fdc3.broadcast()`
`fdc3.broadcast()` . | -| A | 5.Receive Context | A's `fdc3.instrument` object matches the one broadcast by B, and arrives on the correct listener.
A's `fdc3.contact` object matches the one broadcast by B, and arrives on the correct listener. | +| A | 5.Receive Context | A's `fdc3.instrument` object matches the one broadcast by B, and arrives on the correct listener.
A's `fdc3.contact` object matches the one broadcast by B, and arrives on the correct listener. | - `UCFilteredUsage5`: Perform above test - `UCFilteredUsage6`: Perform above test, except B will join a _different_ channel to A. Check that you _don't_ receive anything. - `UCFilteredUsageChange`: Perform above test, except that after joining, **A** changes channel to a _different_ channel via a further call to `fdc3.joinUserChannel`. Check that **A** does NOT receive anything. - - `UCFilteredUsageUnsubscribe`: Perform above test, except that after joining, **A** then `unsubscribe()`s from the channel using the `listener.unsubscribe` function. Check that **A** does NOT receive anything. + - `UCFilteredUsageUnsubscribe`: Perform above test, except that after joining, **A** then `unsubscribe()`s from the channel using the `listener.unsubscribe` function. Check that **A** does NOT receive anything. - `UCFilteredUsageLeave`: Perform above test, except that immediately after joining, **A** _leaves the channel_, and so receives nothing. - `UCFilteredUsageNoJoin`: Perform the above test, but skip step 2 so that **A** does NOT join a channel. Confirm that the _current channel_ for **A** is NOT set before continuing with the rest of the test. **A** should receive nothing. diff --git a/toolbox/fdc3-explained/README.md b/toolbox/fdc3-explained/README.md index 88fb8c5e8..c17c2cb9d 100644 --- a/toolbox/fdc3-explained/README.md +++ b/toolbox/fdc3-explained/README.md @@ -1,4 +1,4 @@ -# FDC3 Explained Logo +# FDC3 Explained Logo FDC3 Explained was originally created by Johan Sandersson, an original maintainer of FDC3, and contributed to the project. It shows how easy it is to create very simple HTML and JavaScript that can use the FDC3 APIs to facilitate interoperability. diff --git a/website/versioned_docs/version-1.0/api/ref/DesktopAgent.md b/website/versioned_docs/version-1.0/api/ref/DesktopAgent.md index 30cb5b5d6..e587b6b50 100644 --- a/website/versioned_docs/version-1.0/api/ref/DesktopAgent.md +++ b/website/versioned_docs/version-1.0/api/ref/DesktopAgent.md @@ -76,7 +76,7 @@ const listener = await fdc3.addContextListener(null, context => { ... }); const contactListener = await fdc3.addContextListener('fdc3.contact', contact => { ... }); // listener that logs metadata for the message a specific type -const contactListener = await fdc3.addContextListener('fdc3.contact', (contact, metadata) => { +const contactListener = await fdc3.addContextListener('fdc3.contact', (contact, metadata) => { console.log(`Received context message\nContext: ${contact}\nOriginating app: ${metadata?.source}`); //do something else with the context }); @@ -112,7 +112,7 @@ const listener = fdc3.addIntentListener('StartChat', context => { }); //Handle a raised intent and log the originating app metadata -const listener = fdc3.addIntentListener('StartChat', (contact, metadata) => { +const listener = fdc3.addIntentListener('StartChat', (contact, metadata) => { console.log(`Received intent StartChat\nContext: ${contact}\nOriginating app: ${metadata?.source}`); return; }); @@ -284,8 +284,8 @@ const appIntent = await fdc3.findIntent("StartChat"); // { // intent: { name: "StartChat", displayName: "Chat" }, // apps: [ -// { appId: "Skype" }, -// { appId: "Symphony" }, +// { appId: "Skype" }, +// { appId: "Symphony" }, // { appId: "Slack" } // ] // } @@ -295,14 +295,14 @@ await fdc3.raiseIntent(appIntent.intent.name, context, appIntent.apps[0]); //later, we want to raise 'StartChat' intent again const appIntent = await fdc3.findIntent("StartChat"); -// returns an AppIntent, but with multiple options for resolution, +// returns an AppIntent, but with multiple options for resolution, // which includes an existing instance of an application: // { // intent: { name: "StartChat", displayName: "Chat" }, // apps: [ -// { appId: "Skype" }, -// { appId: "Symphony" }, -// { appId: "Symphony", instanceId: "93d2fe3e-a66c-41e1-b80b-246b87120859" }, +// { appId: "Skype" }, +// { appId: "Symphony" }, +// { appId: "Symphony", instanceId: "93d2fe3e-a66c-41e1-b80b-246b87120859" }, // { appId: "Slack" } // ] ``` @@ -366,11 +366,11 @@ const appIntents = await fdc3.findIntentsByContext(context); // apps: [{ appId: "Skype" }] // }, // { -// intent: { name: "StartChat", displayName: "Chat" }, +// intent: { name: "StartChat", displayName: "Chat" }, // apps: [ -// { appId: "Skype" }, -// { appId: "Symphony" }, -// { appId: "Symphony", instanceId: "93d2fe3e-a66c-41e1-b80b-246b87120859" }, +// { appId: "Skype" }, +// { appId: "Symphony" }, +// { appId: "Symphony", instanceId: "93d2fe3e-a66c-41e1-b80b-246b87120859" }, // { appId: "Slack" } // ] // }, @@ -390,7 +390,7 @@ const appIntentsForType = await fdc3.findIntentsByContext(context, "fdc3.Contact // intent: { name: "ViewContact", displayName: "View Contact" }, // apps: [{ appId: "Symphony" }, { appId: "MyCRM", resultType: "fdc3.ContactList"}] // }]; - + // select a particular intent to raise const startChat = appIntents[1]; @@ -608,7 +608,7 @@ If an error occurs while opening the app, the promise MUST be rejected with an ` let appIdentifier = { appId: 'myApp-v1.0.1' }; let instanceIdentifier = await fdc3.open(appIdentifier); -// Open an app with context +// Open an app with context let instanceIdentifier = await fdc3.open(appIdentifier, context); ``` @@ -628,7 +628,7 @@ raiseIntent(intent: string, context: Context, app?: AppIdentifier): Promise; ``` -Adds a listener for incoming context broadcasts from the Desktop Agent. Provided for backwards compatibility with versions FDC3 standard <2.0. +Adds a listener for incoming context broadcasts from the Desktop Agent. Provided for backwards compatibility with versions FDC3 standard <2.0. #### See also @@ -759,7 +759,7 @@ Alias to the [`joinUserChannel`](#joinuserchannel) function provided for backwar open(name: String, context?: Context): Promise; ``` -Version of `open` that launches an app by name rather than `AppIdentifier`. Provided for backwards compatibility with versions of the FDC3 Standard <2.0. +Version of `open` that launches an app by name rather than `AppIdentifier`. Provided for backwards compatibility with versions of the FDC3 Standard <2.0. #### See also @@ -771,7 +771,7 @@ Version of `open` that launches an app by name rather than `AppIdentifier`. Prov raiseIntent(intent: string, context: Context, name: String): Promise; ``` -Version of `raiseIntent` that targets an app by name rather than `AppIdentifier`. Provided for backwards compatibility with versions of the FDC3 Standard <2.0. +Version of `raiseIntent` that targets an app by name rather than `AppIdentifier`. Provided for backwards compatibility with versions of the FDC3 Standard <2.0. #### See also @@ -783,7 +783,7 @@ Version of `raiseIntent` that targets an app by name rather than `AppIdentifier` raiseIntentForContext(context: Context, name: String): Promise;; ``` -Version of `raiseIntentForContext` that targets an app by name rather than `AppIdentifier`. Provided for backwards compatibility with versions of the FDC3 Standard <2.0. +Version of `raiseIntentForContext` that targets an app by name rather than `AppIdentifier`. Provided for backwards compatibility with versions of the FDC3 Standard <2.0. #### See also diff --git a/website/versioned_docs/version-1.0/appd-discovery.md b/website/versioned_docs/version-1.0/appd-discovery.md index 262f18124..4c855d730 100644 --- a/website/versioned_docs/version-1.0/appd-discovery.md +++ b/website/versioned_docs/version-1.0/appd-discovery.md @@ -17,18 +17,18 @@ AppD services shall support a distributed or detached model to managing applicat ## Service Discovery Approach -In order to support the discovery of application data stored in a given directory, name space concepts are introduced to both identify the realm of application definitions and AppD service locations that host data. In simple terms, there has to be a way of discovering the location of the AppD service itself and the associated application definitions that are available from that service. +In order to support the discovery of application data stored in a given directory, name space concepts are introduced to both identify the realm of application definitions and AppD service locations that host data. In simple terms, there has to be a way of discovering the location of the AppD service itself and the associated application definitions that are available from that service. ### Application Identifier -- Application data discovery through nested namespace approach and email address construction (**name@fqdn**) defining the application identifier as the name part and AppD location as the fully qualified domain name part. The entire address should be considered the fully qualified application ID. +- Application data discovery through nested namespace approach and email address construction (**name@fqdn**) defining the application identifier as the name part and AppD location as the fully qualified domain name part. The entire address should be considered the fully qualified application ID. ### Resolving host system - AppD service host discovery implementations should support the following requirements; - 1. Discovery of the AppD location using the fully qualified application ID domain name. This would be the fqdn part of the email structure. - 2. Discovery of the AppD location using the fully qualified application ID domain name to lookup DNS SRV records identifying the host server location and access TCP port. ([RFC2782](https://tools.ietf.org/html/rfc2782) ) - 3. Statically defined URI records for use within client applications directly. This is similar to #1 above, but provides explicit protocol, port and url definitions as part of the defintion. + 1. Discovery of the AppD location using the fully qualified application ID domain name. This would be the fqdn part of the email structure. + 2. Discovery of the AppD location using the fully qualified application ID domain name to lookup DNS SRV records identifying the host server location and access TCP port. ([RFC2782](https://tools.ietf.org/html/rfc2782) ) + 3. Statically defined URI records for use within client applications directly. This is similar to #1 above, but provides explicit protocol, port and url definitions as part of the defintion. **Examples:** @@ -42,7 +42,7 @@ AppD Service distribution visual: ## Application data discovery -Application data discovery shall be accessible through a unique application identifier (AppId) representing a single application represented by a nested namespace syntax using dot notation and email address construction (**name@fqdn**) defining the application identifier as the name part and AppD location as the fully qualified domain name part. The entire address should be considered the fully qualified application ID. +Application data discovery shall be accessible through a unique application identifier (AppId) representing a single application represented by a nested namespace syntax using dot notation and email address construction (**name@fqdn**) defining the application identifier as the name part and AppD location as the fully qualified domain name part. The entire address should be considered the fully qualified application ID. **Example:** @@ -92,28 +92,28 @@ getAppData("app@sub.root") ## Service Discovery (Expanded) -The following represents the three ways AppD service instances should be discovered over a given network. Again, the view is that AppD services are distributed/decoupled based on associated application namespace on a given network. This takes into account the use of the application identifiers described in previous section. A launcher is required to use a URI (e.g. "https://appd.foo.com/api/appd/app1@appd.foo.com") to query a given directory instance for data. In order to construct a URI, the host location and port of a given AppD service instance is required. This proposal focuses on the following approaches to achieve this resolution. +The following represents the three ways AppD service instances should be discovered over a given network. Again, the view is that AppD services are distributed/decoupled based on associated application namespace on a given network. This takes into account the use of the application identifiers described in previous section. A launcher is required to use a URI (e.g. "https://appd.foo.com/api/appd/app1@appd.foo.com") to query a given directory instance for data. In order to construct a URI, the host location and port of a given AppD service instance is required. This proposal focuses on the following approaches to achieve this resolution. ### Application ID namespace syntax host resolution -An application directory URI can be constructed using a fully qualified application ID (email address syntax) by using fqdn part of the ID as the host location and the name part as the application name. Given an application name "app1" with a fully qualified identifier of "app1@appd.foo.com" an application directory host location can be derived by simply extracting the fqdn "appd.foo.com" from the email syntax. The extracted fqdn "app.foo.com" may resolve to the actual host location where the application directory is running. +An application directory URI can be constructed using a fully qualified application ID (email address syntax) by using fqdn part of the ID as the host location and the name part as the application name. Given an application name "app1" with a fully qualified identifier of "app1@appd.foo.com" an application directory host location can be derived by simply extracting the fqdn "appd.foo.com" from the email syntax. The extracted fqdn "app.foo.com" may resolve to the actual host location where the application directory is running. -A launcher can then easily construct a URI by; +A launcher can then easily construct a URI by; -1. URI protocol is defaulted to https, but can be overridden by the launcher. -2. URI hostname is the fully qualified domain of the application ID. +1. URI protocol is defaulted to https, but can be overridden by the launcher. +2. URI hostname is the fully qualified domain of the application ID. 3. URI port is default https/443, but can be overridden by the launcher -4. URI url is by default "/api/**(service)/(version)" .** It is recommended that we identify service label as "**appd**" with version being optional. Calls that are made without version automatically default to latest "/api/appd/app1" vs "/api/appd/v1/app1" +4. URI url is by default "/api/**(service)/(version)" .** It is recommended that we identify service label as "**appd**" with version being optional. Calls that are made without version automatically default to latest "/api/appd/app1" vs "/api/appd/v1/app1" -The resulting URI to retrieve application data for "app1" would be "[https://appd.foo.com/api/appd/v1/app1@appd.foo.com](https://appd.foo.com/api/appd/v1/app1.appd.foo.com)" +The resulting URI to retrieve application data for "app1" would be "[https://appd.foo.com/api/appd/v1/app1@appd.foo.com](https://appd.foo.com/api/appd/v1/app1.appd.foo.com)" ### Application identifiers, Shrinking the URI and AppdD defaults -Although the concept of fully qualified application IDs are useful in resolving the actual host of the application directory, there is no requirement for an application directory to use this fully qualified application ID as the resolver for a record. An application ID is unique to given application directory, but there is no requirement to use the fully qualified representation when querying an interface. Taking the prior example, the fully qualified application ID "app1@appd.foo.com" is represented as "app1" within the application directory. As a result a launcher can use a shortened URI construct "" to resolve the application data vs "https://appd.foo.com/api/appd/v1/app1@appd.foo.com". +Although the concept of fully qualified application IDs are useful in resolving the actual host of the application directory, there is no requirement for an application directory to use this fully qualified application ID as the resolver for a record. An application ID is unique to given application directory, but there is no requirement to use the fully qualified representation when querying an interface. Taking the prior example, the fully qualified application ID "app1@appd.foo.com" is represented as "app1" within the application directory. As a result a launcher can use a shortened URI construct "[https://appd.foo.com/api/appd/v1/app1](https://appd.foo.com/api/appd/v1/app1)" to resolve the application data vs "https://appd.foo.com/api/appd/v1/app1@appd.foo.com". ### DNS/SRV Records -Another approach to support AppD service discovery (resolution) is through use of existing domain name service (DNS) implementations that are broadly used on the Internet today (see: [RFCs](https://www.isc.org/community/rfcs/dns/)). Name service implementations can be considered critical infrastructure and are proven stable with over twenty years of use. Name services can be used both through public Internet or locally deployed intranet, which provides optionality to deployment schemes. +Another approach to support AppD service discovery (resolution) is through use of existing domain name service (DNS) implementations that are broadly used on the Internet today (see: [RFCs](https://www.isc.org/community/rfcs/dns/)). Name service implementations can be considered critical infrastructure and are proven stable with over twenty years of use. Name services can be used both through public Internet or locally deployed intranet, which provides optionality to deployment schemes. More specifically, resolution of an AppD service instance (host location) can be implemented using DNS "service records" (SRV) providing the host instance, protocol and associated port. The following is a well known description of a SRV record ([RFC2782](https://tools.ietf.org/html/rfc2782)): @@ -123,13 +123,13 @@ zone name { _service._proto.name. TTL class SRV priority weight port target.} - *service*: the symbolic name of the desired service. For AppD service, this must be identified as "**_appd**" - *proto*: the transport protocol of the desired service; this is usually either [TCP](https://en.wikipedia.org/wiki/Transmission_Control_Protocol) or [UDP](https://en.wikipedia.org/wiki/User_Datagram_Protocol). For AppD service **_tcp** must be used. -- *name*: the domain name for which this record is valid, ending in a dot. For AppD service, the name should directly map to the application identifier domain. +- *name*: the domain name for which this record is valid, ending in a dot. For AppD service, the name should directly map to the application identifier domain. - *TTL*: standard DNS [time to live](https://en.wikipedia.org/wiki/Time_to_live) field. - *class*: standard DNS class field (this is always *IN*). - *priority*: the priority of the target host, lower value means more preferred. - *weight*: A relative weight for records with the same priority, higher value means more preferred. -- *port*: the TCP or UDP port on which the service is to be found. For AppD service, TCP should always be used. -- *target*: the canonical hostname of the machine providing the service, ending in a dot. This would be the host where the AppD service is running. +- *port*: the TCP or UDP port on which the service is to be found. For AppD service, TCP should always be used. +- *target*: the canonical hostname of the machine providing the service, ending in a dot. This would be the host where the AppD service is running. For AppD Service the SRV record **must use** the following definitions: @@ -139,10 +139,10 @@ For AppD Service the SRV record **must use** the following definitions: **Known domains:** -Although SRV records provide the means of resolving the location of an AppD service for a specific domain, there could be a need to know what domains exist in the universe. This would be a list of domains representing all known directory instances. It is recommended that the FDC3/FINOS organization publish a list of known domains which support AppD services. This publication can be handled in multiple ways, such as structured files or API endpoints. This proposal shall not provide a qualified solution to achieve this, but rather draw attention to a potential requirement. +Although SRV records provide the means of resolving the location of an AppD service for a specific domain, there could be a need to know what domains exist in the universe. This would be a list of domains representing all known directory instances. It is recommended that the FDC3/FINOS organization publish a list of known domains which support AppD services. This publication can be handled in multiple ways, such as structured files or API endpoints. This proposal shall not provide a qualified solution to achieve this, but rather draw attention to a potential requirement. ### Static configuration -As the name implies, a static configuration for the AppD service location is predefined within the launcher following the same domain:URI model mentioned in previous sections. +As the name implies, a static configuration for the AppD service location is predefined within the launcher following the same domain:URI model mentioned in previous sections. -![img](https://finosfoundation.atlassian.net/wiki/download/thumbnails/129597550/StaticConfig.png?version=1&modificationDate=1526330937517&cacheVersion=1&api=v2&width=800&height=376) \ No newline at end of file +![img](https://finosfoundation.atlassian.net/wiki/download/thumbnails/129597550/StaticConfig.png?version=1&modificationDate=1526330937517&cacheVersion=1&api=v2&width=800&height=376) diff --git a/website/versioned_docs/version-1.0/context/ref/Chart.md b/website/versioned_docs/version-1.0/context/ref/Chart.md index fb2913d82..694961c93 100644 --- a/website/versioned_docs/version-1.0/context/ref/Chart.md +++ b/website/versioned_docs/version-1.0/context/ref/Chart.md @@ -27,10 +27,10 @@ https://fdc3.finos.org/schemas/next/chart.schema.json | Property | Type | Required | Example Value | |------------------|-----------------|----------|----------------------| | `type` | string | Yes | `'fdc3.chart'` | -| `instruments` | Instrument[] | Yes | 
[
  {
    "type": "fdc3.instrument",
    "id": {
      "ticker": "AAPL"
    }
  },
  {
    "type": "fdc3.instrument",
    "id": {
      "ticker": "MSFT"
    }
  }
]
| -| `range` | TimeRange | No | 
{
  "type": "fdc3.timeRange",
  "startTime": "2022-03-30T15:44:44+00:00",
  "endTime": "2022-04-30T23:59:59+00:00"
}
| +| `instruments` | Instrument[] | Yes | 
[
  \{
    "type": "fdc3.instrument",
    "id": \{
      "ticker": "AAPL"
    \}
  \},
  \{
    "type": "fdc3.instrument",
    "id": \{
      "ticker": "MSFT"
    \}
  \}
]
| +| `range` | TimeRange | No | 
\{
  "type": "fdc3.timeRange",
  "startTime": "2022-03-30T15:44:44+00:00",
  "endTime": "2022-04-30T23:59:59+00:00"
\}
| | `style` | string | No | one of: `'line'`, `'bar'`, `'stacked-bar'`, `'mountain'`, `'candle'`, `'pie'`, `'scatter'`, `'histogram'`, `'heatmap'`, `'custom'` | -| `otherConfig`* | object | No | `{ /* unstandardized additional config */}` | +| `otherConfig`* | object | No | `\{ /* unstandardized additional config */\}` | \* It is common for charts to support other configuration, such as indicators, annotations etc., which do not have standarized formats, but may be included in the `otherConfig` element. diff --git a/website/versioned_docs/version-1.0/context/ref/Email.md b/website/versioned_docs/version-1.0/context/ref/Email.md index 7f183245d..ef7500b9f 100644 --- a/website/versioned_docs/version-1.0/context/ref/Email.md +++ b/website/versioned_docs/version-1.0/context/ref/Email.md @@ -20,7 +20,7 @@ https://fdc3.finos.org/schemas/next/email.schema.json | Property | Type | Required | Example Value | |-------------------|---------------------------------------|----------|---------------------| | `type` | string | Yes | `'fdc3.email'` | -| `recipients` | fdc3.contact or fdc3.contactList | Yes | { type: "fdc3.contact", name: "John Doe", id: { "email": "john@sample.com"}} | +| `recipients` | fdc3.contact or fdc3.contactList | Yes | \{ type: "fdc3.contact", name: "John Doe", id: \{ "email": "john@sample.com"\}\} | | `subject` | string | No | `'The information you requested'` | | `textBody` | string | No | `'Blah, blah, bah` | diff --git a/website/versioned_docs/version-1.1/app-directory/discovery.md b/website/versioned_docs/version-1.1/app-directory/discovery.md index e6f2e8173..9d3c410fe 100644 --- a/website/versioned_docs/version-1.1/app-directory/discovery.md +++ b/website/versioned_docs/version-1.1/app-directory/discovery.md @@ -17,17 +17,17 @@ AppD services shall support a distributed or detached model to managing applicat ## Service Discovery Approach -In order to support the discovery of application data stored in a given directory, name space concepts are introduced to both identify the realm of application definitions and AppD service locations that host data. In simple terms, there has to be a way of discovering the location of the AppD service itself and the associated application definitions that are available from that service. +In order to support the discovery of application data stored in a given directory, name space concepts are introduced to both identify the realm of application definitions and AppD service locations that host data. In simple terms, there has to be a way of discovering the location of the AppD service itself and the associated application definitions that are available from that service. ### Application Identifier -- Application data discovery through nested namespace approach and email address construction (**name@fqdn**) defining the application identifier as the name part and AppD location as the fully qualified domain name part. The entire address should be considered the fully qualified application ID. +- Application data discovery through nested namespace approach and email address construction (**name@fqdn**) defining the application identifier as the name part and AppD location as the fully qualified domain name part. The entire address should be considered the fully qualified application ID. ### Resolving host system - AppD service host discovery implementations should support the following requirements; - 1. Discovery of the AppD location using the fully qualified application ID domain name. This would be the fqdn part of the email structure. - 2. Discovery of the AppD location using the fully qualified application ID domain name to lookup DNS SRV records identifying the host server location and access TCP port. ([RFC2782](https://tools.ietf.org/html/rfc2782) ) + 1. Discovery of the AppD location using the fully qualified application ID domain name. This would be the fqdn part of the email structure. + 2. Discovery of the AppD location using the fully qualified application ID domain name to lookup DNS SRV records identifying the host server location and access TCP port. ([RFC2782](https://tools.ietf.org/html/rfc2782) ) 3. Statically defined URI records for use within client applications directly. This is similar to #1 above, but provides explicit protocol, port and url definitions as part of the defintion. **Examples:** @@ -101,19 +101,19 @@ An application directory URI can be constructed using a fully qualified applicat A launcher can then easily construct a URI by; 1. URI protocol is defaulted to https, but can be overridden by the launcher. -2. URI hostname is the fully qualified domain of the application ID. +2. URI hostname is the fully qualified domain of the application ID. 3. URI port is default https/443, but can be overridden by the launcher -4. URI url is by default "/api/**(service)/(version)/apps" .** It is recommended that we identify service label as "**appd**" with version being optional. Calls that are made without version automatically default to latest "/api/appd/apps/app1" vs "/api/appd/v1/apps/app1" +4. URI url is by default "/api/**(service)/(version)/apps" .** It is recommended that we identify service label as "**appd**" with version being optional. Calls that are made without version automatically default to latest "/api/appd/apps/app1" vs "/api/appd/v1/apps/app1" -The resulting URI to retrieve application data for "app1" would be "[https://appd.foo.com/api/appd/v1/apps/app1@appd.foo.com](https://appd.foo.com/api/appd/v1/apps/app1.appd.foo.com)" +The resulting URI to retrieve application data for "app1" would be "[https://appd.foo.com/api/appd/v1/apps/app1@appd.foo.com](https://appd.foo.com/api/appd/v1/apps/app1.appd.foo.com)" ### Application identifiers, Shrinking the URI and AppdD defaults -Although the concept of fully qualified application IDs are useful in resolving the actual host of the application directory, there is no requirement for an application directory to use this fully qualified application ID as the resolver for a record. An application ID is unique to given application directory, but there is no requirement to use the fully qualified representation when querying an interface. Taking the prior example, the fully qualified application ID "app1@appd.foo.com" is represented as "app1" within the application directory. As a result a launcher can use a shortened URI construct "" to resolve the application data vs "https://appd.foo.com/api/appd/v1/apps/app1@appd.foo.com". +Although the concept of fully qualified application IDs are useful in resolving the actual host of the application directory, there is no requirement for an application directory to use this fully qualified application ID as the resolver for a record. An application ID is unique to given application directory, but there is no requirement to use the fully qualified representation when querying an interface. Taking the prior example, the fully qualified application ID "app1@appd.foo.com" is represented as "app1" within the application directory. As a result a launcher can use a shortened URI construct "[https://appd.foo.com/api/appd/v1/apps/app1](https://appd.foo.com/api/appd/v1/apps/app1)" to resolve the application data vs "https://appd.foo.com/api/appd/v1/apps/app1@appd.foo.com". ### DNS/SRV Records -Another approach to support AppD service discovery (resolution) is through use of existing domain name service (DNS) implementations that are broadly used on the Internet today (see: [RFCs](https://www.isc.org/community/rfcs/dns/)). Name service implementations can be considered critical infrastructure and are proven stable with over twenty years of use. Name services can be used both through public Internet or locally deployed intranet, which provides optionality to deployment schemes. +Another approach to support AppD service discovery (resolution) is through use of existing domain name service (DNS) implementations that are broadly used on the Internet today (see: [RFCs](https://www.isc.org/community/rfcs/dns/)). Name service implementations can be considered critical infrastructure and are proven stable with over twenty years of use. Name services can be used both through public Internet or locally deployed intranet, which provides optionality to deployment schemes. More specifically, resolution of an AppD service instance (host location) can be implemented using DNS "service records" (SRV) providing the host instance, protocol and associated port. The following is a well known description of a SRV record ([RFC2782](https://tools.ietf.org/html/rfc2782)): @@ -123,13 +123,13 @@ zone name { _service._proto.name. TTL class SRV priority weight port target.} - *service*: the symbolic name of the desired service. For AppD service, this must be identified as "**_appd**" - *proto*: the transport protocol of the desired service; this is usually either [TCP](https://en.wikipedia.org/wiki/Transmission_Control_Protocol) or [UDP](https://en.wikipedia.org/wiki/User_Datagram_Protocol). For AppD service **_tcp** must be used. -- *name*: the domain name for which this record is valid, ending in a dot. For AppD service, the name should directly map to the application identifier domain. +- *name*: the domain name for which this record is valid, ending in a dot. For AppD service, the name should directly map to the application identifier domain. - *TTL*: standard DNS [time to live](https://en.wikipedia.org/wiki/Time_to_live) field. - *class*: standard DNS class field (this is always *IN*). - *priority*: the priority of the target host, lower value means more preferred. - *weight*: A relative weight for records with the same priority, higher value means more preferred. -- *port*: the TCP or UDP port on which the service is to be found. For AppD service, TCP should always be used. -- *target*: the canonical hostname of the machine providing the service, ending in a dot. This would be the host where the AppD service is running. +- *port*: the TCP or UDP port on which the service is to be found. For AppD service, TCP should always be used. +- *target*: the canonical hostname of the machine providing the service, ending in a dot. This would be the host where the AppD service is running. For AppD Service the SRV record **must use** the following definitions: @@ -139,10 +139,10 @@ For AppD Service the SRV record **must use** the following definitions: **Known domains:** -Although SRV records provide the means of resolving the location of an AppD service for a specific domain, there could be a need to know what domains exist in the universe. This would be a list of domains representing all known directory instances. It is recommended that the FDC3/FINOS organization publish a list of known domains which support AppD services. This publication can be handled in multiple ways, such as structured files or API endpoints. This proposal shall not provide a qualified solution to achieve this, but rather draw attention to a potential requirement. +Although SRV records provide the means of resolving the location of an AppD service for a specific domain, there could be a need to know what domains exist in the universe. This would be a list of domains representing all known directory instances. It is recommended that the FDC3/FINOS organization publish a list of known domains which support AppD services. This publication can be handled in multiple ways, such as structured files or API endpoints. This proposal shall not provide a qualified solution to achieve this, but rather draw attention to a potential requirement. ### Static configuration -As the name implies, a static configuration for the AppD service location is predefined within the launcher following the same domain:URI model mentioned in previous sections. +As the name implies, a static configuration for the AppD service location is predefined within the launcher following the same domain:URI model mentioned in previous sections. -![img](https://finosfoundation.atlassian.net/wiki/download/thumbnails/129597550/StaticConfig.png?version=1&modificationDate=1526330937517&cacheVersion=1&api=v2&width=800&height=376) \ No newline at end of file +![img](https://finosfoundation.atlassian.net/wiki/download/thumbnails/129597550/StaticConfig.png?version=1&modificationDate=1526330937517&cacheVersion=1&api=v2&width=800&height=376) diff --git a/website/versioned_docs/version-1.1/appd-discovery.md b/website/versioned_docs/version-1.1/appd-discovery.md index 262f18124..4c855d730 100644 --- a/website/versioned_docs/version-1.1/appd-discovery.md +++ b/website/versioned_docs/version-1.1/appd-discovery.md @@ -17,18 +17,18 @@ AppD services shall support a distributed or detached model to managing applicat ## Service Discovery Approach -In order to support the discovery of application data stored in a given directory, name space concepts are introduced to both identify the realm of application definitions and AppD service locations that host data. In simple terms, there has to be a way of discovering the location of the AppD service itself and the associated application definitions that are available from that service. +In order to support the discovery of application data stored in a given directory, name space concepts are introduced to both identify the realm of application definitions and AppD service locations that host data. In simple terms, there has to be a way of discovering the location of the AppD service itself and the associated application definitions that are available from that service. ### Application Identifier -- Application data discovery through nested namespace approach and email address construction (**name@fqdn**) defining the application identifier as the name part and AppD location as the fully qualified domain name part. The entire address should be considered the fully qualified application ID. +- Application data discovery through nested namespace approach and email address construction (**name@fqdn**) defining the application identifier as the name part and AppD location as the fully qualified domain name part. The entire address should be considered the fully qualified application ID. ### Resolving host system - AppD service host discovery implementations should support the following requirements; - 1. Discovery of the AppD location using the fully qualified application ID domain name. This would be the fqdn part of the email structure. - 2. Discovery of the AppD location using the fully qualified application ID domain name to lookup DNS SRV records identifying the host server location and access TCP port. ([RFC2782](https://tools.ietf.org/html/rfc2782) ) - 3. Statically defined URI records for use within client applications directly. This is similar to #1 above, but provides explicit protocol, port and url definitions as part of the defintion. + 1. Discovery of the AppD location using the fully qualified application ID domain name. This would be the fqdn part of the email structure. + 2. Discovery of the AppD location using the fully qualified application ID domain name to lookup DNS SRV records identifying the host server location and access TCP port. ([RFC2782](https://tools.ietf.org/html/rfc2782) ) + 3. Statically defined URI records for use within client applications directly. This is similar to #1 above, but provides explicit protocol, port and url definitions as part of the defintion. **Examples:** @@ -42,7 +42,7 @@ AppD Service distribution visual: ## Application data discovery -Application data discovery shall be accessible through a unique application identifier (AppId) representing a single application represented by a nested namespace syntax using dot notation and email address construction (**name@fqdn**) defining the application identifier as the name part and AppD location as the fully qualified domain name part. The entire address should be considered the fully qualified application ID. +Application data discovery shall be accessible through a unique application identifier (AppId) representing a single application represented by a nested namespace syntax using dot notation and email address construction (**name@fqdn**) defining the application identifier as the name part and AppD location as the fully qualified domain name part. The entire address should be considered the fully qualified application ID. **Example:** @@ -92,28 +92,28 @@ getAppData("app@sub.root") ## Service Discovery (Expanded) -The following represents the three ways AppD service instances should be discovered over a given network. Again, the view is that AppD services are distributed/decoupled based on associated application namespace on a given network. This takes into account the use of the application identifiers described in previous section. A launcher is required to use a URI (e.g. "https://appd.foo.com/api/appd/app1@appd.foo.com") to query a given directory instance for data. In order to construct a URI, the host location and port of a given AppD service instance is required. This proposal focuses on the following approaches to achieve this resolution. +The following represents the three ways AppD service instances should be discovered over a given network. Again, the view is that AppD services are distributed/decoupled based on associated application namespace on a given network. This takes into account the use of the application identifiers described in previous section. A launcher is required to use a URI (e.g. "https://appd.foo.com/api/appd/app1@appd.foo.com") to query a given directory instance for data. In order to construct a URI, the host location and port of a given AppD service instance is required. This proposal focuses on the following approaches to achieve this resolution. ### Application ID namespace syntax host resolution -An application directory URI can be constructed using a fully qualified application ID (email address syntax) by using fqdn part of the ID as the host location and the name part as the application name. Given an application name "app1" with a fully qualified identifier of "app1@appd.foo.com" an application directory host location can be derived by simply extracting the fqdn "appd.foo.com" from the email syntax. The extracted fqdn "app.foo.com" may resolve to the actual host location where the application directory is running. +An application directory URI can be constructed using a fully qualified application ID (email address syntax) by using fqdn part of the ID as the host location and the name part as the application name. Given an application name "app1" with a fully qualified identifier of "app1@appd.foo.com" an application directory host location can be derived by simply extracting the fqdn "appd.foo.com" from the email syntax. The extracted fqdn "app.foo.com" may resolve to the actual host location where the application directory is running. -A launcher can then easily construct a URI by; +A launcher can then easily construct a URI by; -1. URI protocol is defaulted to https, but can be overridden by the launcher. -2. URI hostname is the fully qualified domain of the application ID. +1. URI protocol is defaulted to https, but can be overridden by the launcher. +2. URI hostname is the fully qualified domain of the application ID. 3. URI port is default https/443, but can be overridden by the launcher -4. URI url is by default "/api/**(service)/(version)" .** It is recommended that we identify service label as "**appd**" with version being optional. Calls that are made without version automatically default to latest "/api/appd/app1" vs "/api/appd/v1/app1" +4. URI url is by default "/api/**(service)/(version)" .** It is recommended that we identify service label as "**appd**" with version being optional. Calls that are made without version automatically default to latest "/api/appd/app1" vs "/api/appd/v1/app1" -The resulting URI to retrieve application data for "app1" would be "[https://appd.foo.com/api/appd/v1/app1@appd.foo.com](https://appd.foo.com/api/appd/v1/app1.appd.foo.com)" +The resulting URI to retrieve application data for "app1" would be "[https://appd.foo.com/api/appd/v1/app1@appd.foo.com](https://appd.foo.com/api/appd/v1/app1.appd.foo.com)" ### Application identifiers, Shrinking the URI and AppdD defaults -Although the concept of fully qualified application IDs are useful in resolving the actual host of the application directory, there is no requirement for an application directory to use this fully qualified application ID as the resolver for a record. An application ID is unique to given application directory, but there is no requirement to use the fully qualified representation when querying an interface. Taking the prior example, the fully qualified application ID "app1@appd.foo.com" is represented as "app1" within the application directory. As a result a launcher can use a shortened URI construct "" to resolve the application data vs "https://appd.foo.com/api/appd/v1/app1@appd.foo.com". +Although the concept of fully qualified application IDs are useful in resolving the actual host of the application directory, there is no requirement for an application directory to use this fully qualified application ID as the resolver for a record. An application ID is unique to given application directory, but there is no requirement to use the fully qualified representation when querying an interface. Taking the prior example, the fully qualified application ID "app1@appd.foo.com" is represented as "app1" within the application directory. As a result a launcher can use a shortened URI construct "[https://appd.foo.com/api/appd/v1/app1](https://appd.foo.com/api/appd/v1/app1)" to resolve the application data vs "https://appd.foo.com/api/appd/v1/app1@appd.foo.com". ### DNS/SRV Records -Another approach to support AppD service discovery (resolution) is through use of existing domain name service (DNS) implementations that are broadly used on the Internet today (see: [RFCs](https://www.isc.org/community/rfcs/dns/)). Name service implementations can be considered critical infrastructure and are proven stable with over twenty years of use. Name services can be used both through public Internet or locally deployed intranet, which provides optionality to deployment schemes. +Another approach to support AppD service discovery (resolution) is through use of existing domain name service (DNS) implementations that are broadly used on the Internet today (see: [RFCs](https://www.isc.org/community/rfcs/dns/)). Name service implementations can be considered critical infrastructure and are proven stable with over twenty years of use. Name services can be used both through public Internet or locally deployed intranet, which provides optionality to deployment schemes. More specifically, resolution of an AppD service instance (host location) can be implemented using DNS "service records" (SRV) providing the host instance, protocol and associated port. The following is a well known description of a SRV record ([RFC2782](https://tools.ietf.org/html/rfc2782)): @@ -123,13 +123,13 @@ zone name { _service._proto.name. TTL class SRV priority weight port target.} - *service*: the symbolic name of the desired service. For AppD service, this must be identified as "**_appd**" - *proto*: the transport protocol of the desired service; this is usually either [TCP](https://en.wikipedia.org/wiki/Transmission_Control_Protocol) or [UDP](https://en.wikipedia.org/wiki/User_Datagram_Protocol). For AppD service **_tcp** must be used. -- *name*: the domain name for which this record is valid, ending in a dot. For AppD service, the name should directly map to the application identifier domain. +- *name*: the domain name for which this record is valid, ending in a dot. For AppD service, the name should directly map to the application identifier domain. - *TTL*: standard DNS [time to live](https://en.wikipedia.org/wiki/Time_to_live) field. - *class*: standard DNS class field (this is always *IN*). - *priority*: the priority of the target host, lower value means more preferred. - *weight*: A relative weight for records with the same priority, higher value means more preferred. -- *port*: the TCP or UDP port on which the service is to be found. For AppD service, TCP should always be used. -- *target*: the canonical hostname of the machine providing the service, ending in a dot. This would be the host where the AppD service is running. +- *port*: the TCP or UDP port on which the service is to be found. For AppD service, TCP should always be used. +- *target*: the canonical hostname of the machine providing the service, ending in a dot. This would be the host where the AppD service is running. For AppD Service the SRV record **must use** the following definitions: @@ -139,10 +139,10 @@ For AppD Service the SRV record **must use** the following definitions: **Known domains:** -Although SRV records provide the means of resolving the location of an AppD service for a specific domain, there could be a need to know what domains exist in the universe. This would be a list of domains representing all known directory instances. It is recommended that the FDC3/FINOS organization publish a list of known domains which support AppD services. This publication can be handled in multiple ways, such as structured files or API endpoints. This proposal shall not provide a qualified solution to achieve this, but rather draw attention to a potential requirement. +Although SRV records provide the means of resolving the location of an AppD service for a specific domain, there could be a need to know what domains exist in the universe. This would be a list of domains representing all known directory instances. It is recommended that the FDC3/FINOS organization publish a list of known domains which support AppD services. This publication can be handled in multiple ways, such as structured files or API endpoints. This proposal shall not provide a qualified solution to achieve this, but rather draw attention to a potential requirement. ### Static configuration -As the name implies, a static configuration for the AppD service location is predefined within the launcher following the same domain:URI model mentioned in previous sections. +As the name implies, a static configuration for the AppD service location is predefined within the launcher following the same domain:URI model mentioned in previous sections. -![img](https://finosfoundation.atlassian.net/wiki/download/thumbnails/129597550/StaticConfig.png?version=1&modificationDate=1526330937517&cacheVersion=1&api=v2&width=800&height=376) \ No newline at end of file +![img](https://finosfoundation.atlassian.net/wiki/download/thumbnails/129597550/StaticConfig.png?version=1&modificationDate=1526330937517&cacheVersion=1&api=v2&width=800&height=376) diff --git a/website/versioned_docs/version-1.2/app-directory/discovery.md b/website/versioned_docs/version-1.2/app-directory/discovery.md index f2376cb2c..fd9909dce 100644 --- a/website/versioned_docs/version-1.2/app-directory/discovery.md +++ b/website/versioned_docs/version-1.2/app-directory/discovery.md @@ -27,7 +27,7 @@ In order to support the discovery of application data stored in a given director - AppD service host discovery implementations should support the following requirements; 1. Discovery of the AppD location using the fully qualified application ID domain name. This would be the fqdn part of the email structure. - 2. Discovery of the AppD location using the fully qualified application ID domain name to lookup DNS SRV records identifying the host server location and access TCP port. ([RFC2782](https://tools.ietf.org/html/rfc2782) ) + 2. Discovery of the AppD location using the fully qualified application ID domain name to lookup DNS SRV records identifying the host server location and access TCP port. ([RFC2782](https://tools.ietf.org/html/rfc2782) ) 3. Statically defined URI records for use within client applications directly. This is similar to #1 above, but provides explicit protocol, port and url definitions as part of the defintion. **Examples:** @@ -42,7 +42,7 @@ AppD Service distribution visual: ## Application data discovery -Application data discovery shall be accessible through a unique application identifier (AppId) representing a single application represented by a nested namespace syntax using dot notation and email address construction (**name@fqdn**) defining the application identifier as the name part and AppD location as the fully qualified domain name part. The entire address should be considered the fully qualified application ID. +Application data discovery shall be accessible through a unique application identifier (AppId) representing a single application represented by a nested namespace syntax using dot notation and email address construction (**name@fqdn**) defining the application identifier as the name part and AppD location as the fully qualified domain name part. The entire address should be considered the fully qualified application ID. **Example:** @@ -103,17 +103,17 @@ A launcher can then easily construct a URI by; 1. URI protocol is defaulted to https, but can be overridden by the launcher. 2. URI hostname is the fully qualified domain of the application ID. 3. URI port is default https/443, but can be overridden by the launcher -4. URI url is by default "/api/**(service)/(version)" .** It is recommended that we identify service label as "**appd**" with version being optional. Calls that are made without version automatically default to latest "/api/appd/app1" vs "/api/appd/v1/app1" +4. URI url is by default "/api/**(service)/(version)" .** It is recommended that we identify service label as "**appd**" with version being optional. Calls that are made without version automatically default to latest "/api/appd/app1" vs "/api/appd/v1/app1" -The resulting URI to retrieve application data for "app1" would be "[https://appd.foo.com/api/appd/v1/apps/app1@appd.foo.com](https://appd.foo.com/api/appd/v1/apps/app1.appd.foo.com)" +The resulting URI to retrieve application data for "app1" would be "[https://appd.foo.com/api/appd/v1/apps/app1@appd.foo.com](https://appd.foo.com/api/appd/v1/apps/app1.appd.foo.com)" ### Application identifiers, Shrinking the URI and AppdD defaults -Although the concept of fully qualified application IDs are useful in resolving the actual host of the application directory, there is no requirement for an application directory to use this fully qualified application ID as the resolver for a record. An application ID is unique to given application directory, but there is no requirement to use the fully qualified representation when querying an interface. Taking the prior example, the fully qualified application ID "app1@appd.foo.com" is represented as "app1" within the application directory. As a result a launcher can use a shortened URI construct "" to resolve the application data vs "https://appd.foo.com/api/appd/v1/apps/app1@appd.foo.com". +Although the concept of fully qualified application IDs are useful in resolving the actual host of the application directory, there is no requirement for an application directory to use this fully qualified application ID as the resolver for a record. An application ID is unique to given application directory, but there is no requirement to use the fully qualified representation when querying an interface. Taking the prior example, the fully qualified application ID "app1@appd.foo.com" is represented as "app1" within the application directory. As a result a launcher can use a shortened URI construct "[https://appd.foo.com/api/appd/v1/apps/app1](https://appd.foo.com/api/appd/v1/apps/app1)" to resolve the application data vs "https://appd.foo.com/api/appd/v1/apps/app1@appd.foo.com". ### DNS/SRV Records -Another approach to support AppD service discovery (resolution) is through use of existing domain name service (DNS) implementations that are broadly used on the Internet today (see: [RFCs](https://www.isc.org/community/rfcs/dns/)). Name service implementations can be considered critical infrastructure and are proven stable with over twenty years of use. Name services can be used both through public Internet or locally deployed intranet, which provides optionality to deployment schemes. +Another approach to support AppD service discovery (resolution) is through use of existing domain name service (DNS) implementations that are broadly used on the Internet today (see: [RFCs](https://www.isc.org/community/rfcs/dns/)). Name service implementations can be considered critical infrastructure and are proven stable with over twenty years of use. Name services can be used both through public Internet or locally deployed intranet, which provides optionality to deployment schemes. More specifically, resolution of an AppD service instance (host location) can be implemented using DNS "service records" (SRV) providing the host instance, protocol and associated port. The following is a well known description of a SRV record ([RFC2782](https://tools.ietf.org/html/rfc2782)): @@ -123,13 +123,13 @@ zone name { _service._proto.name. TTL class SRV priority weight port target.} - *service*: the symbolic name of the desired service. For AppD service, this must be identified as "**_appd**" - *proto*: the transport protocol of the desired service; this is usually either [TCP](https://en.wikipedia.org/wiki/Transmission_Control_Protocol) or [UDP](https://en.wikipedia.org/wiki/User_Datagram_Protocol). For AppD service **_tcp** must be used. -- *name*: the domain name for which this record is valid, ending in a dot. For AppD service, the name should directly map to the application identifier domain. +- *name*: the domain name for which this record is valid, ending in a dot. For AppD service, the name should directly map to the application identifier domain. - *TTL*: standard DNS [time to live](https://en.wikipedia.org/wiki/Time_to_live) field. - *class*: standard DNS class field (this is always *IN*). - *priority*: the priority of the target host, lower value means more preferred. - *weight*: A relative weight for records with the same priority, higher value means more preferred. -- *port*: the TCP or UDP port on which the service is to be found. For AppD service, TCP should always be used. -- *target*: the canonical hostname of the machine providing the service, ending in a dot. This would be the host where the AppD service is running. +- *port*: the TCP or UDP port on which the service is to be found. For AppD service, TCP should always be used. +- *target*: the canonical hostname of the machine providing the service, ending in a dot. This would be the host where the AppD service is running. For AppD Service the SRV record **must use** the following definitions: @@ -139,10 +139,10 @@ For AppD Service the SRV record **must use** the following definitions: **Known domains:** -Although SRV records provide the means of resolving the location of an AppD service for a specific domain, there could be a need to know what domains exist in the universe. This would be a list of domains representing all known directory instances. It is recommended that the FDC3/FINOS organization publish a list of known domains which support AppD services. This publication can be handled in multiple ways, such as structured files or API endpoints. This proposal shall not provide a qualified solution to achieve this, but rather draw attention to a potential requirement. +Although SRV records provide the means of resolving the location of an AppD service for a specific domain, there could be a need to know what domains exist in the universe. This would be a list of domains representing all known directory instances. It is recommended that the FDC3/FINOS organization publish a list of known domains which support AppD services. This publication can be handled in multiple ways, such as structured files or API endpoints. This proposal shall not provide a qualified solution to achieve this, but rather draw attention to a potential requirement. ### Static configuration -As the name implies, a static configuration for the AppD service location is predefined within the launcher following the same domain:URI model mentioned in previous sections. +As the name implies, a static configuration for the AppD service location is predefined within the launcher following the same domain:URI model mentioned in previous sections. -![img](https://finosfoundation.atlassian.net/wiki/download/thumbnails/129597550/StaticConfig.png?version=1&modificationDate=1526330937517&cacheVersion=1&api=v2&width=800&height=376) \ No newline at end of file +![img](https://finosfoundation.atlassian.net/wiki/download/thumbnails/129597550/StaticConfig.png?version=1&modificationDate=1526330937517&cacheVersion=1&api=v2&width=800&height=376) diff --git a/website/versioned_docs/version-1.2/appd-discovery.md b/website/versioned_docs/version-1.2/appd-discovery.md index 262f18124..4c855d730 100644 --- a/website/versioned_docs/version-1.2/appd-discovery.md +++ b/website/versioned_docs/version-1.2/appd-discovery.md @@ -17,18 +17,18 @@ AppD services shall support a distributed or detached model to managing applicat ## Service Discovery Approach -In order to support the discovery of application data stored in a given directory, name space concepts are introduced to both identify the realm of application definitions and AppD service locations that host data. In simple terms, there has to be a way of discovering the location of the AppD service itself and the associated application definitions that are available from that service. +In order to support the discovery of application data stored in a given directory, name space concepts are introduced to both identify the realm of application definitions and AppD service locations that host data. In simple terms, there has to be a way of discovering the location of the AppD service itself and the associated application definitions that are available from that service. ### Application Identifier -- Application data discovery through nested namespace approach and email address construction (**name@fqdn**) defining the application identifier as the name part and AppD location as the fully qualified domain name part. The entire address should be considered the fully qualified application ID. +- Application data discovery through nested namespace approach and email address construction (**name@fqdn**) defining the application identifier as the name part and AppD location as the fully qualified domain name part. The entire address should be considered the fully qualified application ID. ### Resolving host system - AppD service host discovery implementations should support the following requirements; - 1. Discovery of the AppD location using the fully qualified application ID domain name. This would be the fqdn part of the email structure. - 2. Discovery of the AppD location using the fully qualified application ID domain name to lookup DNS SRV records identifying the host server location and access TCP port. ([RFC2782](https://tools.ietf.org/html/rfc2782) ) - 3. Statically defined URI records for use within client applications directly. This is similar to #1 above, but provides explicit protocol, port and url definitions as part of the defintion. + 1. Discovery of the AppD location using the fully qualified application ID domain name. This would be the fqdn part of the email structure. + 2. Discovery of the AppD location using the fully qualified application ID domain name to lookup DNS SRV records identifying the host server location and access TCP port. ([RFC2782](https://tools.ietf.org/html/rfc2782) ) + 3. Statically defined URI records for use within client applications directly. This is similar to #1 above, but provides explicit protocol, port and url definitions as part of the defintion. **Examples:** @@ -42,7 +42,7 @@ AppD Service distribution visual: ## Application data discovery -Application data discovery shall be accessible through a unique application identifier (AppId) representing a single application represented by a nested namespace syntax using dot notation and email address construction (**name@fqdn**) defining the application identifier as the name part and AppD location as the fully qualified domain name part. The entire address should be considered the fully qualified application ID. +Application data discovery shall be accessible through a unique application identifier (AppId) representing a single application represented by a nested namespace syntax using dot notation and email address construction (**name@fqdn**) defining the application identifier as the name part and AppD location as the fully qualified domain name part. The entire address should be considered the fully qualified application ID. **Example:** @@ -92,28 +92,28 @@ getAppData("app@sub.root") ## Service Discovery (Expanded) -The following represents the three ways AppD service instances should be discovered over a given network. Again, the view is that AppD services are distributed/decoupled based on associated application namespace on a given network. This takes into account the use of the application identifiers described in previous section. A launcher is required to use a URI (e.g. "https://appd.foo.com/api/appd/app1@appd.foo.com") to query a given directory instance for data. In order to construct a URI, the host location and port of a given AppD service instance is required. This proposal focuses on the following approaches to achieve this resolution. +The following represents the three ways AppD service instances should be discovered over a given network. Again, the view is that AppD services are distributed/decoupled based on associated application namespace on a given network. This takes into account the use of the application identifiers described in previous section. A launcher is required to use a URI (e.g. "https://appd.foo.com/api/appd/app1@appd.foo.com") to query a given directory instance for data. In order to construct a URI, the host location and port of a given AppD service instance is required. This proposal focuses on the following approaches to achieve this resolution. ### Application ID namespace syntax host resolution -An application directory URI can be constructed using a fully qualified application ID (email address syntax) by using fqdn part of the ID as the host location and the name part as the application name. Given an application name "app1" with a fully qualified identifier of "app1@appd.foo.com" an application directory host location can be derived by simply extracting the fqdn "appd.foo.com" from the email syntax. The extracted fqdn "app.foo.com" may resolve to the actual host location where the application directory is running. +An application directory URI can be constructed using a fully qualified application ID (email address syntax) by using fqdn part of the ID as the host location and the name part as the application name. Given an application name "app1" with a fully qualified identifier of "app1@appd.foo.com" an application directory host location can be derived by simply extracting the fqdn "appd.foo.com" from the email syntax. The extracted fqdn "app.foo.com" may resolve to the actual host location where the application directory is running. -A launcher can then easily construct a URI by; +A launcher can then easily construct a URI by; -1. URI protocol is defaulted to https, but can be overridden by the launcher. -2. URI hostname is the fully qualified domain of the application ID. +1. URI protocol is defaulted to https, but can be overridden by the launcher. +2. URI hostname is the fully qualified domain of the application ID. 3. URI port is default https/443, but can be overridden by the launcher -4. URI url is by default "/api/**(service)/(version)" .** It is recommended that we identify service label as "**appd**" with version being optional. Calls that are made without version automatically default to latest "/api/appd/app1" vs "/api/appd/v1/app1" +4. URI url is by default "/api/**(service)/(version)" .** It is recommended that we identify service label as "**appd**" with version being optional. Calls that are made without version automatically default to latest "/api/appd/app1" vs "/api/appd/v1/app1" -The resulting URI to retrieve application data for "app1" would be "[https://appd.foo.com/api/appd/v1/app1@appd.foo.com](https://appd.foo.com/api/appd/v1/app1.appd.foo.com)" +The resulting URI to retrieve application data for "app1" would be "[https://appd.foo.com/api/appd/v1/app1@appd.foo.com](https://appd.foo.com/api/appd/v1/app1.appd.foo.com)" ### Application identifiers, Shrinking the URI and AppdD defaults -Although the concept of fully qualified application IDs are useful in resolving the actual host of the application directory, there is no requirement for an application directory to use this fully qualified application ID as the resolver for a record. An application ID is unique to given application directory, but there is no requirement to use the fully qualified representation when querying an interface. Taking the prior example, the fully qualified application ID "app1@appd.foo.com" is represented as "app1" within the application directory. As a result a launcher can use a shortened URI construct "" to resolve the application data vs "https://appd.foo.com/api/appd/v1/app1@appd.foo.com". +Although the concept of fully qualified application IDs are useful in resolving the actual host of the application directory, there is no requirement for an application directory to use this fully qualified application ID as the resolver for a record. An application ID is unique to given application directory, but there is no requirement to use the fully qualified representation when querying an interface. Taking the prior example, the fully qualified application ID "app1@appd.foo.com" is represented as "app1" within the application directory. As a result a launcher can use a shortened URI construct "[https://appd.foo.com/api/appd/v1/app1](https://appd.foo.com/api/appd/v1/app1)" to resolve the application data vs "https://appd.foo.com/api/appd/v1/app1@appd.foo.com". ### DNS/SRV Records -Another approach to support AppD service discovery (resolution) is through use of existing domain name service (DNS) implementations that are broadly used on the Internet today (see: [RFCs](https://www.isc.org/community/rfcs/dns/)). Name service implementations can be considered critical infrastructure and are proven stable with over twenty years of use. Name services can be used both through public Internet or locally deployed intranet, which provides optionality to deployment schemes. +Another approach to support AppD service discovery (resolution) is through use of existing domain name service (DNS) implementations that are broadly used on the Internet today (see: [RFCs](https://www.isc.org/community/rfcs/dns/)). Name service implementations can be considered critical infrastructure and are proven stable with over twenty years of use. Name services can be used both through public Internet or locally deployed intranet, which provides optionality to deployment schemes. More specifically, resolution of an AppD service instance (host location) can be implemented using DNS "service records" (SRV) providing the host instance, protocol and associated port. The following is a well known description of a SRV record ([RFC2782](https://tools.ietf.org/html/rfc2782)): @@ -123,13 +123,13 @@ zone name { _service._proto.name. TTL class SRV priority weight port target.} - *service*: the symbolic name of the desired service. For AppD service, this must be identified as "**_appd**" - *proto*: the transport protocol of the desired service; this is usually either [TCP](https://en.wikipedia.org/wiki/Transmission_Control_Protocol) or [UDP](https://en.wikipedia.org/wiki/User_Datagram_Protocol). For AppD service **_tcp** must be used. -- *name*: the domain name for which this record is valid, ending in a dot. For AppD service, the name should directly map to the application identifier domain. +- *name*: the domain name for which this record is valid, ending in a dot. For AppD service, the name should directly map to the application identifier domain. - *TTL*: standard DNS [time to live](https://en.wikipedia.org/wiki/Time_to_live) field. - *class*: standard DNS class field (this is always *IN*). - *priority*: the priority of the target host, lower value means more preferred. - *weight*: A relative weight for records with the same priority, higher value means more preferred. -- *port*: the TCP or UDP port on which the service is to be found. For AppD service, TCP should always be used. -- *target*: the canonical hostname of the machine providing the service, ending in a dot. This would be the host where the AppD service is running. +- *port*: the TCP or UDP port on which the service is to be found. For AppD service, TCP should always be used. +- *target*: the canonical hostname of the machine providing the service, ending in a dot. This would be the host where the AppD service is running. For AppD Service the SRV record **must use** the following definitions: @@ -139,10 +139,10 @@ For AppD Service the SRV record **must use** the following definitions: **Known domains:** -Although SRV records provide the means of resolving the location of an AppD service for a specific domain, there could be a need to know what domains exist in the universe. This would be a list of domains representing all known directory instances. It is recommended that the FDC3/FINOS organization publish a list of known domains which support AppD services. This publication can be handled in multiple ways, such as structured files or API endpoints. This proposal shall not provide a qualified solution to achieve this, but rather draw attention to a potential requirement. +Although SRV records provide the means of resolving the location of an AppD service for a specific domain, there could be a need to know what domains exist in the universe. This would be a list of domains representing all known directory instances. It is recommended that the FDC3/FINOS organization publish a list of known domains which support AppD services. This publication can be handled in multiple ways, such as structured files or API endpoints. This proposal shall not provide a qualified solution to achieve this, but rather draw attention to a potential requirement. ### Static configuration -As the name implies, a static configuration for the AppD service location is predefined within the launcher following the same domain:URI model mentioned in previous sections. +As the name implies, a static configuration for the AppD service location is predefined within the launcher following the same domain:URI model mentioned in previous sections. -![img](https://finosfoundation.atlassian.net/wiki/download/thumbnails/129597550/StaticConfig.png?version=1&modificationDate=1526330937517&cacheVersion=1&api=v2&width=800&height=376) \ No newline at end of file +![img](https://finosfoundation.atlassian.net/wiki/download/thumbnails/129597550/StaticConfig.png?version=1&modificationDate=1526330937517&cacheVersion=1&api=v2&width=800&height=376) diff --git a/website/versioned_docs/version-2.0/api/ref/DesktopAgent.md b/website/versioned_docs/version-2.0/api/ref/DesktopAgent.md index 8876c1c7e..773ef23fa 100644 --- a/website/versioned_docs/version-2.0/api/ref/DesktopAgent.md +++ b/website/versioned_docs/version-2.0/api/ref/DesktopAgent.md @@ -77,7 +77,7 @@ const listener = await fdc3.addContextListener(null, context => { ... }); const contactListener = await fdc3.addContextListener('fdc3.contact', contact => { ... }); // listener that logs metadata for the message a specific type -const contactListener = await fdc3.addContextListener('fdc3.contact', (contact, metadata) => { +const contactListener = await fdc3.addContextListener('fdc3.contact', (contact, metadata) => { console.log(`Received context message\nContext: ${contact}\nOriginating app: ${metadata?.source}`); //do something else with the context }); @@ -97,7 +97,7 @@ addIntentListener(intent: string, handler: IntentHandler): Promise; Adds a listener for incoming intents from the Desktop Agent. The handler function may return void or a promise that resolves to a [`IntentResult`](Types#intentresult), which is either a [`Context`](Types#context) object, representing any data that should be returned to the app that raised the intent, or a [`Channel`](Channel) or [`PrivateChannel`](PrivateChannel) over which data responses will be sent. The `IntentResult` will be returned to the app that raised the intent via the [`IntentResolution`](Metadata#intentresolution) and retrieved from it using the `getResult()` function. -The Desktop Agent MUST reject the promise returned by the `getResult()` function of `IntentResolution` if any of the following is true: +The Desktop Agent MUST reject the promise returned by the `getResult()` function of `IntentResolution` if any of the following is true: 1. The intent handling function's returned promise rejects. 2. The intent handling function doesn't return a promise. 3. The returned promise resolves to an invalid type. @@ -116,7 +116,7 @@ const listener = fdc3.addIntentListener('StartChat', context => { }); //Handle a raised intent and log the originating app metadata -const listener = fdc3.addIntentListener('StartChat', (contact, metadata) => { +const listener = fdc3.addIntentListener('StartChat', (contact, metadata) => { console.log(`Received intent StartChat\nContext: ${contact}\nOriginating app: ${metadata?.source}`); return; }); @@ -288,8 +288,8 @@ const appIntent = await fdc3.findIntent("StartChat"); // { // intent: { name: "StartChat", displayName: "Chat" }, // apps: [ -// { appId: "Skype" }, -// { appId: "Symphony" }, +// { appId: "Skype" }, +// { appId: "Symphony" }, // { appId: "Slack" } // ] // } @@ -299,14 +299,14 @@ await fdc3.raiseIntent(appIntent.intent.name, context, appIntent.apps[0]); //later, we want to raise 'StartChat' intent again const appIntent = await fdc3.findIntent("StartChat"); -// returns an AppIntent, but with multiple options for resolution, +// returns an AppIntent, but with multiple options for resolution, // which includes an existing instance of an application: // { // intent: { name: "StartChat", displayName: "Chat" }, // apps: [ -// { appId: "Skype" }, -// { appId: "Symphony" }, -// { appId: "Symphony", instanceId: "93d2fe3e-a66c-41e1-b80b-246b87120859" }, +// { appId: "Skype" }, +// { appId: "Symphony" }, +// { appId: "Symphony", instanceId: "93d2fe3e-a66c-41e1-b80b-246b87120859" }, // { appId: "Slack" } // ] ``` @@ -370,11 +370,11 @@ const appIntents = await fdc3.findIntentsByContext(context); // apps: [{ appId: "Skype" }] // }, // { -// intent: { name: "StartChat", displayName: "Chat" }, +// intent: { name: "StartChat", displayName: "Chat" }, // apps: [ -// { appId: "Skype" }, -// { appId: "Symphony" }, -// { appId: "Symphony", instanceId: "93d2fe3e-a66c-41e1-b80b-246b87120859" }, +// { appId: "Skype" }, +// { appId: "Symphony" }, +// { appId: "Symphony", instanceId: "93d2fe3e-a66c-41e1-b80b-246b87120859" }, // { appId: "Slack" } // ] // }, @@ -394,7 +394,7 @@ const appIntentsForType = await fdc3.findIntentsByContext(context, "fdc3.Contact // intent: { name: "ViewContact", displayName: "View Contact" }, // apps: [{ appId: "Symphony" }, { appId: "MyCRM", resultType: "fdc3.ContactList"}] // }]; - + // select a particular intent to raise const startChat = appIntents[1]; @@ -614,7 +614,7 @@ If an error occurs while opening the app, the promise MUST be rejected with an ` let appIdentifier = { appId: 'myApp-v1.0.1' }; let instanceIdentifier = await fdc3.open(appIdentifier); -// Open an app with context +// Open an app with context let instanceIdentifier = await fdc3.open(appIdentifier, context); ``` @@ -634,7 +634,7 @@ raiseIntent(intent: string, context: Context, app?: AppIdentifier): Promise; ``` -Adds a listener for incoming context broadcasts from the Desktop Agent. Provided for backwards compatibility with versions FDC3 standard <2.0. +Adds a listener for incoming context broadcasts from the Desktop Agent. Provided for backwards compatibility with versions FDC3 standard <2.0. #### See also @@ -765,7 +765,7 @@ Alias to the [`joinUserChannel`](#joinuserchannel) function provided for backwar open(name: String, context?: Context): Promise; ``` -Version of `open` that launches an app by name rather than `AppIdentifier`. Provided for backwards compatibility with versions of the FDC3 Standard <2.0. +Version of `open` that launches an app by name rather than `AppIdentifier`. Provided for backwards compatibility with versions of the FDC3 Standard <2.0. #### See also @@ -777,7 +777,7 @@ Version of `open` that launches an app by name rather than `AppIdentifier`. Prov raiseIntent(intent: string, context: Context, name: String): Promise; ``` -Version of `raiseIntent` that targets an app by name rather than `AppIdentifier`. Provided for backwards compatibility with versions of the FDC3 Standard <2.0. +Version of `raiseIntent` that targets an app by name rather than `AppIdentifier`. Provided for backwards compatibility with versions of the FDC3 Standard <2.0. #### See also @@ -789,7 +789,7 @@ Version of `raiseIntent` that targets an app by name rather than `AppIdentifier` raiseIntentForContext(context: Context, name: String): Promise;; ``` -Version of `raiseIntentForContext` that targets an app by name rather than `AppIdentifier`. Provided for backwards compatibility with versions of the FDC3 Standard <2.0. +Version of `raiseIntentForContext` that targets an app by name rather than `AppIdentifier`. Provided for backwards compatibility with versions of the FDC3 Standard <2.0. #### See also diff --git a/website/versioned_docs/version-2.0/context/ref/Chart.md b/website/versioned_docs/version-2.0/context/ref/Chart.md index 809a31589..95a8553cd 100644 --- a/website/versioned_docs/version-2.0/context/ref/Chart.md +++ b/website/versioned_docs/version-2.0/context/ref/Chart.md @@ -34,10 +34,10 @@ The `fdc3.timeRange` context type is inconsistently used in FDC3 2.0, occasional | Property | Type | Required | Example Value | |------------------|-----------------|----------|----------------------| | `type` | string | Yes | `'fdc3.chart'` | -| `instruments` | Instrument[] | Yes | 
[
  {
    "type": "fdc3.instrument",
    "id": {
      "ticker": "AAPL"
    }
  },
  {
    "type": "fdc3.instrument",
    "id": {
      "ticker": "MSFT"
    }
  }
]
| -| `range` | TimeRange | No | 
{
  "type": "fdc3.timeRange",
  "startTime": "2022-03-30T15:44:44+00:00",
  "endTime": "2022-04-30T23:59:59+00:00"
}
| +| `instruments` | Instrument[] | Yes | 
[
  \{
    "type": "fdc3.instrument",
    "id": \{
      "ticker": "AAPL"
    \}
  \},
  \{
    "type": "fdc3.instrument",
    "id": \{
      "ticker": "MSFT"
    \}
  \}
]
| +| `range` | TimeRange | No | 
\{
  "type": "fdc3.timeRange",
  "startTime": "2022-03-30T15:44:44+00:00",
  "endTime": "2022-04-30T23:59:59+00:00"
\}
| | `style` | string | No | one of: `'line'`, `'bar'`, `'stacked-bar'`, `'mountain'`, `'candle'`, `'pie'`, `'scatter'`, `'histogram'`, `'heatmap'`, `'custom'` | -| `otherConfig`* | object | No | `{ /* unstandardized additional config */}` | +| `otherConfig`* | object | No | `\{ /* unstandardized additional config */\}` | \* It is common for charts to support other configuration, such as indicators, annotations etc., which do not have standarized formats, but may be included in the `otherConfig` element. diff --git a/website/versioned_docs/version-2.0/context/ref/Email.md b/website/versioned_docs/version-2.0/context/ref/Email.md index 6d5e1d0e5..0b7c200eb 100644 --- a/website/versioned_docs/version-2.0/context/ref/Email.md +++ b/website/versioned_docs/version-2.0/context/ref/Email.md @@ -21,7 +21,7 @@ https://fdc3.finos.org/schemas/2.0/email.schema.json | Property | Type | Required | Example Value | |-------------------|---------------------------------------|----------|---------------------| | `type` | string | Yes | `'fdc3.email'` | -| `recipients` | fdc3.contact or fdc3.contactList | Yes | { type: "fdc3.contact", name: "John Doe", id: { "email": "john@sample.com"}} | +| `recipients` | fdc3.contact or fdc3.contactList | Yes | \{ type: "fdc3.contact", name: "John Doe", id: \{ "email": "john@sample.com"\}\} | | `subject` | string | No | `'The information you requested'` | | `textBody` | string | No | `'Blah, blah, bah` | diff --git a/website/versioned_docs/version-2.1/api/ref/DesktopAgent.md b/website/versioned_docs/version-2.1/api/ref/DesktopAgent.md index 7ab8d692e..b78277126 100644 --- a/website/versioned_docs/version-2.1/api/ref/DesktopAgent.md +++ b/website/versioned_docs/version-2.1/api/ref/DesktopAgent.md @@ -79,7 +79,7 @@ const listener = await fdc3.addContextListener(null, context => { ... }); const contactListener = await fdc3.addContextListener('fdc3.contact', contact => { ... }); // listener that logs metadata for the message a specific type -const contactListener = await fdc3.addContextListener('fdc3.contact', (contact, metadata) => { +const contactListener = await fdc3.addContextListener('fdc3.contact', (contact, metadata) => { console.log(`Received context message\nContext: ${contact}\nOriginating app: ${metadata?.source}`); //do something else with the context }); @@ -121,7 +121,7 @@ const listener = fdc3.addIntentListener('StartChat', context => { }); //Handle a raised intent and log the originating app metadata -const listener = fdc3.addIntentListener('StartChat', (contact, metadata) => { +const listener = fdc3.addIntentListener('StartChat', (contact, metadata) => { console.log(`Received intent StartChat\nContext: ${contact}\nOriginating app: ${metadata?.source}`); return; }); @@ -295,8 +295,8 @@ const appIntent = await fdc3.findIntent("StartChat"); // { // intent: { name: "StartChat" }, // apps: [ -// { appId: "Skype" }, -// { appId: "Symphony" }, +// { appId: "Skype" }, +// { appId: "Symphony" }, // { appId: "Slack" } // ] // } @@ -306,14 +306,14 @@ await fdc3.raiseIntent(appIntent.intent.name, context, appIntent.apps[0]); //later, we want to raise 'StartChat' intent again const appIntent = await fdc3.findIntent("StartChat"); -// returns an AppIntent, but with multiple options for resolution, +// returns an AppIntent, but with multiple options for resolution, // which includes an existing instance of an application: // { // intent: { name: "StartChat" }, // apps: [ -// { appId: "Skype" }, -// { appId: "Symphony" }, -// { appId: "Symphony", instanceId: "93d2fe3e-a66c-41e1-b80b-246b87120859" }, +// { appId: "Skype" }, +// { appId: "Symphony" }, +// { appId: "Symphony", instanceId: "93d2fe3e-a66c-41e1-b80b-246b87120859" }, // { appId: "Slack" } // ] ``` @@ -377,11 +377,11 @@ const appIntents = await fdc3.findIntentsByContext(context); // apps: [{ appId: "Skype" }] // }, // { -// intent: { name: "StartChat" }, +// intent: { name: "StartChat" }, // apps: [ -// { appId: "Skype" }, -// { appId: "Symphony" }, -// { appId: "Symphony", instanceId: "93d2fe3e-a66c-41e1-b80b-246b87120859" }, +// { appId: "Skype" }, +// { appId: "Symphony" }, +// { appId: "Symphony", instanceId: "93d2fe3e-a66c-41e1-b80b-246b87120859" }, // { appId: "Slack" } // ] // }, @@ -401,7 +401,7 @@ const appIntentsForType = await fdc3.findIntentsByContext(context, "fdc3.Contact // intent: { name: "ViewContact" }, // apps: [{ appId: "Symphony" }, { appId: "MyCRM", resultType: "fdc3.ContactList"}] // }]; - + // select a particular intent to raise const startChat = appIntents[1]; @@ -622,7 +622,7 @@ If an error occurs while opening the app, the promise MUST be rejected with an ` let appIdentifier = { appId: 'myApp-v1.0.1' }; let instanceIdentifier = await fdc3.open(appIdentifier); -// Open an app with context +// Open an app with context let instanceIdentifier = await fdc3.open(appIdentifier, context); ``` @@ -642,7 +642,7 @@ raiseIntent(intent: string, context: Context, app?: AppIdentifier): Promise; ``` -Adds a listener for incoming context broadcasts from the Desktop Agent. Provided for backwards compatibility with versions FDC3 standard <2.0. +Adds a listener for incoming context broadcasts from the Desktop Agent. Provided for backwards compatibility with versions FDC3 standard <2.0. **See also:** @@ -774,7 +774,7 @@ Alias to the [`joinUserChannel`](#joinuserchannel) function provided for backwar open(name: string, context?: Context): Promise; ``` -Version of `open` that launches an app by name rather than `AppIdentifier`. Provided for backwards compatibility with versions of the FDC3 Standard <2.0. +Version of `open` that launches an app by name rather than `AppIdentifier`. Provided for backwards compatibility with versions of the FDC3 Standard <2.0. **See also:** @@ -786,7 +786,7 @@ Version of `open` that launches an app by name rather than `AppIdentifier`. Prov raiseIntent(intent: string, context: Context, name: string): Promise; ``` -Version of `raiseIntent` that targets an app by name rather than `AppIdentifier`. Provided for backwards compatibility with versions of the FDC3 Standard <2.0. +Version of `raiseIntent` that targets an app by name rather than `AppIdentifier`. Provided for backwards compatibility with versions of the FDC3 Standard <2.0. **See also:** @@ -798,7 +798,7 @@ Version of `raiseIntent` that targets an app by name rather than `AppIdentifier` raiseIntentForContext(context: Context, name: string): Promise;; ``` -Version of `raiseIntentForContext` that targets an app by name rather than `AppIdentifier`. Provided for backwards compatibility with versions of the FDC3 Standard <2.0. +Version of `raiseIntentForContext` that targets an app by name rather than `AppIdentifier`. Provided for backwards compatibility with versions of the FDC3 Standard <2.0. **See also:** diff --git a/website/versioned_docs/version-2.1/app-directory/overview.md b/website/versioned_docs/version-2.1/app-directory/overview.md index 285448565..9f630901f 100644 --- a/website/versioned_docs/version-2.1/app-directory/overview.md +++ b/website/versioned_docs/version-2.1/app-directory/overview.md @@ -91,7 +91,7 @@ knowledge of the AppD instance location. ### Authentication and Entitlements -The AppD API specification defines the optional use of an access token to identify the requesting user/launcher and implement authorizations which may affect appD API responses. For example, different subsets of the full list of applications may be returned for different users depending on their role in an organization. +The AppD API specification defines the optional use of an access token to identify the requesting user/launcher and implement authorizations which may affect appD API responses. For example, different subsets of the full list of applications may be returned for different users depending on their role in an organization. The specification does not define or make mandatory any authorizations or roles that a provider or enterprise can define. @@ -116,7 +116,7 @@ However, in order to do so, you must first discover the location of an app direc Three methods for discovering app directory services are defined in this Standard: 1. **Static configuration:** Statically defined URI records for use within client applications (typically a Desktop Agent implementation) directly. - 2. **Fully-qualified appID namespace syntax host resolution:** Discovery of the appD location using a fully qualified application ID (appId) domain name. + 2. **Fully-qualified appID namespace syntax host resolution:** Discovery of the appD location using a fully qualified application ID (appId) domain name. 3. **DNS lookup by domain name:** Discovery of the appD location using a domain name to lookup DNS SRV records identifying the host server location and TCP port. ([RFC2782](https://tools.ietf.org/html/rfc2782)) App directory service host discovery implementations SHOULD support each of these methods and MUST support at least static configuration. @@ -138,7 +138,7 @@ A launcher can then easily construct a URI by: 3. URI port is default `https/443`, but can be overridden by the launcher 4. URI url is by default `/api/appd/(version)/apps` . Calls that are made without version MUST automatically default to latest, i.e. `/api/appd/apps/app1` should return the same result as `/api/appd/v2/apps/app1". -The resulting URI to retrieve application data for `app1` would be +The resulting URI to retrieve application data for `app1` would be [https://appd.foo.com/api/appd/v2/apps/app1@appd.foo.com](https://appd.foo.com/api/appd/v2/apps/app1@appd.foo.com) ### DNS/SRV Records diff --git a/website/versioned_docs/version-2.1/context/ref/Action.md b/website/versioned_docs/version-2.1/context/ref/Action.md index 982fa8177..e9876c44e 100644 --- a/website/versioned_docs/version-2.1/context/ref/Action.md +++ b/website/versioned_docs/version-2.1/context/ref/Action.md @@ -18,7 +18,7 @@ Accepts an optional `app` parameter in order to specify a specific app. ## Schema - +[https://fdc3.finos.org/schemas/2.1/context/action.schema.json](https://fdc3.finos.org/schemas/2.1/context/action.schema.json) ## Details diff --git a/website/versioned_docs/version-2.1/context/ref/Chart.md b/website/versioned_docs/version-2.1/context/ref/Chart.md index b6392fcdf..d11b2b742 100644 --- a/website/versioned_docs/version-2.1/context/ref/Chart.md +++ b/website/versioned_docs/version-2.1/context/ref/Chart.md @@ -21,17 +21,17 @@ In addition to handling requests to plot charts, a charting application may use ## Schema - +[https://fdc3.finos.org/schemas/2.1/context/chart.schema.json](https://fdc3.finos.org/schemas/2.1/context/chart.schema.json) ## Details | Property | Type | Required | Example Value | |------------------|-----------------|----------|----------------------| | `type` | string | Yes | `'fdc3.chart'` | -| `instruments` | Instrument[] | Yes | 
[
  {
    "type": "fdc3.instrument",
    "id": {
      "ticker": "AAPL"
    }
  },
  {
    "type": "fdc3.instrument",
    "id": {
      "ticker": "MSFT"
    }
  }
]
| -| `range` | TimeRange | No | 
{
  "type": "fdc3.timeRange",
  "startTime": "2022-03-30T15:44:44+00:00",
  "endTime": "2022-04-30T23:59:59+00:00"
}
| +| `instruments` | Instrument[] | Yes | 
[
  \{
    "type": "fdc3.instrument",
    "id": \{
      "ticker": "AAPL"
    \}
  \},
  \{
    "type": "fdc3.instrument",
    "id": \{
      "ticker": "MSFT"
    \}
  \}
]
| +| `range` | TimeRange | No | 
\{
  "type": "fdc3.timeRange",
  "startTime": "2022-03-30T15:44:44+00:00",
  "endTime": "2022-04-30T23:59:59+00:00"
\}
| | `style` | string | No | one of: `'line'`, `'bar'`, `'stacked-bar'`, `'mountain'`, `'candle'`, `'pie'`, `'scatter'`, `'histogram'`, `'heatmap'`, `'custom'` | -| `otherConfig`* | array | No | `[ {/* additional config context objects */} ]` | +| `otherConfig`* | array | No | `[ \{/* additional config context objects */\} ]` | ::: info diff --git a/website/versioned_docs/version-2.1/context/ref/ChatInitSettings.md b/website/versioned_docs/version-2.1/context/ref/ChatInitSettings.md index 1dab98548..cebd1e73a 100644 --- a/website/versioned_docs/version-2.1/context/ref/ChatInitSettings.md +++ b/website/versioned_docs/version-2.1/context/ref/ChatInitSettings.md @@ -15,7 +15,7 @@ A collection of settings to start a new chat conversation ## Schema - +[https://fdc3.finos.org/schemas/2.1/context/chatInitSettings.schema.json](https://fdc3.finos.org/schemas/2.1/context/chatInitSettings.schema.json) ## Details diff --git a/website/versioned_docs/version-2.1/context/ref/ChatMessage.md b/website/versioned_docs/version-2.1/context/ref/ChatMessage.md index e9f5b4376..10a74f11f 100644 --- a/website/versioned_docs/version-2.1/context/ref/ChatMessage.md +++ b/website/versioned_docs/version-2.1/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/2.1/context/chatMessage.schema.json](https://fdc3.finos.org/schemas/2.1/context/chatMessage.schema.json) ## Details diff --git a/website/versioned_docs/version-2.1/context/ref/ChatRoom.md b/website/versioned_docs/version-2.1/context/ref/ChatRoom.md index f995cf0cd..854f3c10d 100644 --- a/website/versioned_docs/version-2.1/context/ref/ChatRoom.md +++ b/website/versioned_docs/version-2.1/context/ref/ChatRoom.md @@ -14,7 +14,7 @@ Reference to the chat room, which could be used later to send a message to the r ## Schema - +[https://fdc3.finos.org/schemas/2.1/context/chatRoom.schema.json](https://fdc3.finos.org/schemas/2.1/context/chatRoom.schema.json) ## Details diff --git a/website/versioned_docs/version-2.1/context/ref/ChatSearchCriteria.md b/website/versioned_docs/version-2.1/context/ref/ChatSearchCriteria.md index 043019bf2..909464faf 100644 --- a/website/versioned_docs/version-2.1/context/ref/ChatSearchCriteria.md +++ b/website/versioned_docs/version-2.1/context/ref/ChatSearchCriteria.md @@ -14,14 +14,14 @@ A context type that represents a simple search criterion, based on a list of oth ## Schema - +[https://fdc3.finos.org/schemas/2.1/context/chatSearchCriteria.schema.json](https://fdc3.finos.org/schemas/2.1/context/chatSearchCriteria.schema.json) ## Details | Property | Type | Required | Example Value | |------------------|-----------------|----------|----------------------| | `type` | string | Yes | `'fdc3.chat.searchCriteria'` | -| `criteria` | (Instrument |
Contact |
Organization |
string)[] | Yes | 
[
  {
    "type": "fdc3.instrument",
    "id": {
      "ticker": "AAPL"
    }
  },
  {
    "type": "fdc3.contact",
    "name":"Jane Doe",
    "id": {
      "email": "jane.doe@mail.com"
    }
  },
  {
    "type": "fdc3.organization",
    "name":"Symphony",
  },
  "#OrderID45788422",
]
| +| `criteria` | (Instrument |
Contact |
Organization |
string)[] | Yes | 
[
  \{
    "type": "fdc3.instrument",
    "id": \{
      "ticker": "AAPL"
    \}
  \},
  \{
    "type": "fdc3.contact",
    "name":"Jane Doe",
    "id": \{
      "email": "jane.doe@mail.com"
    \}
  \},
  \{
    "type": "fdc3.organization",
    "name":"Symphony",
  \},
  "#OrderID45788422",
]
| ⚠️ 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. diff --git a/website/versioned_docs/version-2.1/context/ref/Contact.md b/website/versioned_docs/version-2.1/context/ref/Contact.md index 38a0d0ac9..c2d3267bc 100644 --- a/website/versioned_docs/version-2.1/context/ref/Contact.md +++ b/website/versioned_docs/version-2.1/context/ref/Contact.md @@ -14,7 +14,7 @@ A person contact that can be engaged with through email, calling, messaging, CMS ## Schema - +[https://fdc3.finos.org/schemas/2.1/context/contact.schema.json](https://fdc3.finos.org/schemas/2.1/context/contact.schema.json) ## Details diff --git a/website/versioned_docs/version-2.1/context/ref/ContactList.md b/website/versioned_docs/version-2.1/context/ref/ContactList.md index 138975778..537ac6106 100644 --- a/website/versioned_docs/version-2.1/context/ref/ContactList.md +++ b/website/versioned_docs/version-2.1/context/ref/ContactList.md @@ -20,7 +20,7 @@ this part of the contract with custom identifiers if so desired. ## Schema - +[https://fdc3.finos.org/schemas/2.1/context/contactList.schema.json](https://fdc3.finos.org/schemas/2.1/context/contactList.schema.json) ## Details diff --git a/website/versioned_docs/version-2.1/context/ref/Context.md b/website/versioned_docs/version-2.1/context/ref/Context.md index fbc6d48cf..6d3705a32 100644 --- a/website/versioned_docs/version-2.1/context/ref/Context.md +++ b/website/versioned_docs/version-2.1/context/ref/Context.md @@ -6,7 +6,7 @@ hide_title: true --- # `Context` -The `fdc3.context` type defines the basic contract or "shape" for all data exchanged by FDC3 operations. As such, it is not +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 (standardised or custom) to provide the structure and properties shared by all FDC3 context data types. @@ -24,7 +24,7 @@ can be expected to have, but this can always be extended with custom fields as a ## Schema - +[https://fdc3.finos.org/schemas/2.1/context/context.schema.json](https://fdc3.finos.org/schemas/2.1/context/context.schema.json) ## Details diff --git a/website/versioned_docs/version-2.1/context/ref/Country.md b/website/versioned_docs/version-2.1/context/ref/Country.md index f606d1ff5..2d1320c5b 100644 --- a/website/versioned_docs/version-2.1/context/ref/Country.md +++ b/website/versioned_docs/version-2.1/context/ref/Country.md @@ -22,7 +22,7 @@ is for at least one standardized identifier to be provided ## Schema - +[https://fdc3.finos.org/schemas/2.1/context/country.schema.json](https://fdc3.finos.org/schemas/2.1/context/country.schema.json) ## Details diff --git a/website/versioned_docs/version-2.1/context/ref/Currency.md b/website/versioned_docs/version-2.1/context/ref/Currency.md index 9dd913815..3ba2a5725 100644 --- a/website/versioned_docs/version-2.1/context/ref/Currency.md +++ b/website/versioned_docs/version-2.1/context/ref/Currency.md @@ -15,7 +15,7 @@ A context representing an individual Currency. ## Schema - +[https://fdc3.finos.org/schemas/2.1/context/currency.schema.json](https://fdc3.finos.org/schemas/2.1/context/currency.schema.json) ## Details diff --git a/website/versioned_docs/version-2.1/context/ref/Email.md b/website/versioned_docs/version-2.1/context/ref/Email.md index e3291c1fd..deeb7c2f5 100644 --- a/website/versioned_docs/version-2.1/context/ref/Email.md +++ b/website/versioned_docs/version-2.1/context/ref/Email.md @@ -14,7 +14,7 @@ A collection of information to be used to initiate an email with a Contact or Co ## Schema - +[https://fdc3.finos.org/schemas/2.1/context/email.schema.json](https://fdc3.finos.org/schemas/2.1/context/email.schema.json) ## Details diff --git a/website/versioned_docs/version-2.1/context/ref/Instrument.md b/website/versioned_docs/version-2.1/context/ref/Instrument.md index 0d6f70cf6..3efb98273 100644 --- a/website/versioned_docs/version-2.1/context/ref/Instrument.md +++ b/website/versioned_docs/version-2.1/context/ref/Instrument.md @@ -30,7 +30,7 @@ a property that makes it clear what value represents. Doing so will make interpr ## Schema - +[https://fdc3.finos.org/schemas/2.1/context/instrument.schema.json](https://fdc3.finos.org/schemas/2.1/context/instrument.schema.json) ## Details @@ -39,18 +39,18 @@ a property that makes it clear what value represents. Doing so will make interpr | `type` | string | Yes | `"fdc3.instrument"` | | | `name` | string | No | `"Microsoft"` | | | `id.ticker` | string | No | `"MSFT"` | | -| `id.BBG` | string | No | `"MSFT:US"` | | -| `id.CUSIP` | string | No | `"594918104"` | | -| `id.FDS_ID` | string | No | `"P8R3C2-R"` | | -| `id.FIGI` | string | No | `"BBG000BPH459"` | | -| `id.ISIN` | string | No | `"US5949181045"` | | -| `id.PERMID` | string | No | `"4295907168"` | | -| `id.RIC` | string | No | `"MSFT.OQ"` | | -| `id.SEDOL` | string | No | `"2588173"` | | -| `market.MIC` | string | No | `"XNAS"` | | +| `id.BBG` | string | No | `"MSFT:US"` | [https://www.bloomberg.com/](https://www.bloomberg.com/) | +| `id.CUSIP` | string | No | `"594918104"` | [https://www.cusip.com/](https://www.cusip.com/) | +| `id.FDS_ID` | string | No | `"P8R3C2-R"` | [https://www.factset.com/](https://www.factset.com/) | +| `id.FIGI` | string | No | `"BBG000BPH459"` | [https://www.openfigi.com/](https://www.openfigi.com/) | +| `id.ISIN` | string | No | `"US5949181045"` | [https://www.isin.org/](https://www.isin.org/) | +| `id.PERMID` | string | No | `"4295907168"` | [https://permid.org/](https://permid.org/) | +| `id.RIC` | string | No | `"MSFT.OQ"` | [https://www.refinitiv.com/](https://www.refinitiv.com/) | +| `id.SEDOL` | string | No | `"2588173"` | [https://www.lseg.com/sedol](https://www.lseg.com/sedol) | +| `market.MIC` | string | No | `"XNAS"` | [https://en.wikipedia.org/wiki/Market_Identifier_Code](https://en.wikipedia.org/wiki/Market_Identifier_Code) | | `market.name` | string | No | `"NASDAQ - All Markets"` | | | `market.COUNTRY_ISOALPHA2` | string | No | `"US"` | | -| `market.BBG` | string | No | `"US"` | | +| `market.BBG` | string | No | `"US"` | [https://www.bloomberg.com/](https://www.bloomberg.com/) | ## Example diff --git a/website/versioned_docs/version-2.1/context/ref/InstrumentList.md b/website/versioned_docs/version-2.1/context/ref/InstrumentList.md index 7f2e3bc0c..575c7ecb9 100644 --- a/website/versioned_docs/version-2.1/context/ref/InstrumentList.md +++ b/website/versioned_docs/version-2.1/context/ref/InstrumentList.md @@ -22,7 +22,7 @@ this part of the contract with custom identifiers if so desired. ## Schema - +[https://fdc3.finos.org/schemas/2.1/context/instrumentList.schema.json](https://fdc3.finos.org/schemas/2.1/context/instrumentList.schema.json) ## Details diff --git a/website/versioned_docs/version-2.1/context/ref/Interaction.md b/website/versioned_docs/version-2.1/context/ref/Interaction.md index fdb965944..1b2ff79ee 100644 --- a/website/versioned_docs/version-2.1/context/ref/Interaction.md +++ b/website/versioned_docs/version-2.1/context/ref/Interaction.md @@ -12,9 +12,9 @@ Notes: - `interactionType` SHOULD be one of `'Instant Message'`, `'Email'`, `'Call'`, or `'Meeting'` although other string values are permitted. - `origin` is used to represent the application or service that the interaction was created from to aid in tracing the source of 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` 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` 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. -- `id.URI` 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. +- `id.URI` 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. ## Type @@ -22,7 +22,7 @@ Notes: ## Schema - +[https://fdc3.finos.org/schemas/2.1/context/interaction.schema.json](https://fdc3.finos.org/schemas/2.1/context/interaction.schema.json) ## Details @@ -93,4 +93,4 @@ Other Types Intents - [CreateInteraction](../../intents/ref/CreateInteraction) -- [ViewInteractions](../../intents/ref/ViewInteractions) \ No newline at end of file +- [ViewInteractions](../../intents/ref/ViewInteractions) diff --git a/website/versioned_docs/version-2.1/context/ref/Message.md b/website/versioned_docs/version-2.1/context/ref/Message.md index 05c25e1c0..f6d79e0c9 100644 --- a/website/versioned_docs/version-2.1/context/ref/Message.md +++ b/website/versioned_docs/version-2.1/context/ref/Message.md @@ -6,7 +6,7 @@ hide_title: true --- # `Message` -A chat message to be sent through an instant messaging application. Can contain one or several text bodies (organised by mime-type, plaintext or markdown), +A chat message to be sent through an instant messaging application. Can contain one or several text bodies (organised 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. ## Type @@ -15,14 +15,14 @@ as well as attached entities (either arbitrary file attachments or FDC3 actions ## Schema - +[https://fdc3.finos.org/schemas/2.1/context/message.schema.json](https://fdc3.finos.org/schemas/2.1/context/message.schema.json) ## Details | Property | Type | Required | Example Value | |-------------------|-------------------------------------------|----------|-------------------------| | `type` | string | Yes | `'fdc3.message'` | -| `text` | map of string mime-type to string content | No | { text/plain: 'Hello' } | +| `text` | map of string mime-type to string content | No | \{ text/plain: 'Hello' \} | | `entities` | map of json entity to string id | No | See Below | ## Example diff --git a/website/versioned_docs/version-2.1/context/ref/Nothing.md b/website/versioned_docs/version-2.1/context/ref/Nothing.md index f31822dc1..3b22447c9 100644 --- a/website/versioned_docs/version-2.1/context/ref/Nothing.md +++ b/website/versioned_docs/version-2.1/context/ref/Nothing.md @@ -25,7 +25,7 @@ Notes: ## Schema - +[https://fdc3.finos.org/schemas/2.1/context/nothing.schema.json](https://fdc3.finos.org/schemas/2.1/context/nothing.schema.json) ## Example diff --git a/website/versioned_docs/version-2.1/context/ref/Order.md b/website/versioned_docs/version-2.1/context/ref/Order.md index c00fa3b4e..2795de3e8 100644 --- a/website/versioned_docs/version-2.1/context/ref/Order.md +++ b/website/versioned_docs/version-2.1/context/ref/Order.md @@ -8,7 +8,7 @@ hide_title: true [`@experimental`](/docs/fdc3-compliance#experimental-features) context type representing an order. To be used with OMS and EMS systems. -This 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 an unspecified Context type, but both `details` and `details.product` are expected to be standardized in the future. +This 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 an unspecified Context type, but both `details` and `details.product` are expected to be standardized in the future. ## Type @@ -16,7 +16,7 @@ This type currently only defines a required `id` field, which should provide a r ## Schema - +[https://fdc3.finos.org/schemas/2.1/context/order.schema.json](https://fdc3.finos.org/schemas/2.1/context/order.schema.json) ## Details diff --git a/website/versioned_docs/version-2.1/context/ref/OrderList.md b/website/versioned_docs/version-2.1/context/ref/OrderList.md index 4ff9eb49e..409aa8ea9 100644 --- a/website/versioned_docs/version-2.1/context/ref/OrderList.md +++ b/website/versioned_docs/version-2.1/context/ref/OrderList.md @@ -18,7 +18,7 @@ Notes: ## Schema - +[https://fdc3.finos.org/schemas/2.1/context/orderList.schema.json](https://fdc3.finos.org/schemas/2.1/context/orderList.schema.json) ## Details diff --git a/website/versioned_docs/version-2.1/context/ref/Organization.md b/website/versioned_docs/version-2.1/context/ref/Organization.md index 86a355046..6c3fb5c53 100644 --- a/website/versioned_docs/version-2.1/context/ref/Organization.md +++ b/website/versioned_docs/version-2.1/context/ref/Organization.md @@ -19,7 +19,7 @@ is for at least one specified identifier to be provided. ## Schema - +[https://fdc3.finos.org/schemas/2.1/context/organization.schema.json](https://fdc3.finos.org/schemas/2.1/context/organization.schema.json) ## Details diff --git a/website/versioned_docs/version-2.1/context/ref/Portfolio.md b/website/versioned_docs/version-2.1/context/ref/Portfolio.md index 6fcf3b787..1f5b00217 100644 --- a/website/versioned_docs/version-2.1/context/ref/Portfolio.md +++ b/website/versioned_docs/version-2.1/context/ref/Portfolio.md @@ -29,7 +29,7 @@ this part of the contract with custom identifiers if so desired. ## Schema - +[https://fdc3.finos.org/schemas/2.1/context/portfolio.schema.json](https://fdc3.finos.org/schemas/2.1/context/portfolio.schema.json) ## Details diff --git a/website/versioned_docs/version-2.1/context/ref/Position.md b/website/versioned_docs/version-2.1/context/ref/Position.md index 82f8481ec..8d85682b0 100644 --- a/website/versioned_docs/version-2.1/context/ref/Position.md +++ b/website/versioned_docs/version-2.1/context/ref/Position.md @@ -29,7 +29,7 @@ this part of the contract with custom identifiers if so desired. ## Schema - +[https://fdc3.finos.org/schemas/2.1/context/position.schema.json](https://fdc3.finos.org/schemas/2.1/context/position.schema.json) ## Details diff --git a/website/versioned_docs/version-2.1/context/ref/Product.md b/website/versioned_docs/version-2.1/context/ref/Product.md index 21bc6abc2..61f8ef6a8 100644 --- a/website/versioned_docs/version-2.1/context/ref/Product.md +++ b/website/versioned_docs/version-2.1/context/ref/Product.md @@ -18,7 +18,7 @@ Notes: ## Schema - +[https://fdc3.finos.org/schemas/2.1/context/product.schema.json](https://fdc3.finos.org/schemas/2.1/context/product.schema.json) ## Details diff --git a/website/versioned_docs/version-2.1/context/ref/TimeRange.md b/website/versioned_docs/version-2.1/context/ref/TimeRange.md index 476351abf..3a4a60c91 100644 --- a/website/versioned_docs/version-2.1/context/ref/TimeRange.md +++ b/website/versioned_docs/version-2.1/context/ref/TimeRange.md @@ -33,7 +33,7 @@ Notes: ## Schema - +[https://fdc3.finos.org/schemas/2.1/context/timeRange.schema.json](https://fdc3.finos.org/schemas/2.1/context/timeRange.schema.json) ## Details @@ -82,4 +82,4 @@ Other Types - [Chart](Chart) Intents -- [CreateInteraction](../../intents/ref/CreateInteraction) \ No newline at end of file +- [CreateInteraction](../../intents/ref/CreateInteraction) diff --git a/website/versioned_docs/version-2.1/context/ref/Trade.md b/website/versioned_docs/version-2.1/context/ref/Trade.md index 767aff36f..00bea3620 100644 --- a/website/versioned_docs/version-2.1/context/ref/Trade.md +++ b/website/versioned_docs/version-2.1/context/ref/Trade.md @@ -20,7 +20,7 @@ Notes: ## Schema - +[https://fdc3.finos.org/schemas/2.1/context/trade.schema.json](https://fdc3.finos.org/schemas/2.1/context/trade.schema.json) ## Details diff --git a/website/versioned_docs/version-2.1/context/ref/TradeList.md b/website/versioned_docs/version-2.1/context/ref/TradeList.md index 592966b2f..afb2a235e 100644 --- a/website/versioned_docs/version-2.1/context/ref/TradeList.md +++ b/website/versioned_docs/version-2.1/context/ref/TradeList.md @@ -18,7 +18,7 @@ Notes: ## Schema - +[https://fdc3.finos.org/schemas/2.1/context/tradeList.schema.json](https://fdc3.finos.org/schemas/2.1/context/tradeList.schema.json) ## Details diff --git a/website/versioned_docs/version-2.1/context/ref/TransactionResult.md b/website/versioned_docs/version-2.1/context/ref/TransactionResult.md index 308721902..46a826983 100644 --- a/website/versioned_docs/version-2.1/context/ref/TransactionResult.md +++ b/website/versioned_docs/version-2.1/context/ref/TransactionResult.md @@ -14,7 +14,7 @@ A context type representing the result of a transaction initiated via FDC3, whic ## Schema - +[https://fdc3.finos.org/schemas/2.1/context/transactionresult.schema.json](https://fdc3.finos.org/schemas/2.1/context/transactionresult.schema.json) ## Details diff --git a/website/versioned_docs/version-2.1/context/ref/Valuation.md b/website/versioned_docs/version-2.1/context/ref/Valuation.md index 4ba83e10c..c1a5b95e3 100644 --- a/website/versioned_docs/version-2.1/context/ref/Valuation.md +++ b/website/versioned_docs/version-2.1/context/ref/Valuation.md @@ -14,7 +14,7 @@ A context type representing the price and value of a holding. ## Schema - +[https://fdc3.finos.org/schemas/2.1/context/valuation.schema.json](https://fdc3.finos.org/schemas/2.1/context/valuation.schema.json) ## Details diff --git a/website/versioned_docs/version-2.1/guides/submit-new-intent.md b/website/versioned_docs/version-2.1/guides/submit-new-intent.md index 35d29bddc..27e72d227 100644 --- a/website/versioned_docs/version-2.1/guides/submit-new-intent.md +++ b/website/versioned_docs/version-2.1/guides/submit-new-intent.md @@ -21,7 +21,7 @@ To run the website locally ```yarn start``` -This will open the home page or browse to +This will open the home page or browse to [https://localhost:3000](https://localhost:3000) Note that the page opens on the current release version of the docs and you will be changing the latest version. Click the version selector in the top left hand corner diff --git a/website/versioned_docs/version-2.1/references.md b/website/versioned_docs/version-2.1/references.md index 379c5342d..9efdaea90 100644 --- a/website/versioned_docs/version-2.1/references.md +++ b/website/versioned_docs/version-2.1/references.md @@ -7,29 +7,29 @@ sidebar_label: References The following normative documents contain provisions, which, through reference in this text, constitute provisions of this Standard. For dated references, subsequent amendments to, or revisions of, any of these publications do not apply. However, parties to agreements based on this Standard are encouraged to investigate the possibility of applying the most recent editions of the normative documents indicated below. For undated references, the latest edition of the normative document referred to applies: -- **Apache 2.0 open-source license**, . -- **Community Specification license**, -- **ISO 3166-1**, _Codes for the representation of names of countries and their subdivisions – Part 1: Country codes_, . -- **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_, . -- **RFC 5646**, _Tags for Identifying Languages, September 2009_, . -- **TypeScript Programming Language**, . -- **Web Application Manifest**, _W3C Working Draft_, February 2022 +- **Apache 2.0 open-source license**, [https://www.apache.org/licenses/LICENSE-2.0](https://www.apache.org/licenses/LICENSE-2.0). +- **Community Specification license**, [https://github.com/CommunitySpecification/1.0](https://github.com/CommunitySpecification/1.0) +- **ISO 3166-1**, _Codes for the representation of names of countries and their subdivisions – Part 1: Country codes_, [https://www.iso.org/iso-3166-country-codes.html](https://www.iso.org/iso-3166-country-codes.html). +- **ISO 8601-1:2019**, _Date and time — Representations for information interchange — Part 1: Basic rules_, [https://www.iso.org/standard/70907.html](https://www.iso.org/standard/70907.html) +- **JSON Schema**, [https://json-schema.org/](https://json-schema.org/). +- **OpenAPI Standard v3.0**, [https://www.openapis.org/](https://www.openapis.org/). +- **quicktype**, [https://quicktype.io/](https://quicktype.io/). +- **RFC 2119**, _Keywords for use in RFCs to Indicate Requirement Levels, March 1997_, [https://datatracker.ietf.org/doc/html/rfc2119](https://datatracker.ietf.org/doc/html/rfc2119). +- **RFC 2782**, _A DNS RR for specifying the location of services (DNS SRV), February 2000_, [https://datatracker.ietf.org/doc/html/rfc2782](https://datatracker.ietf.org/doc/html/rfc2782). +- **RFC 4122**, _A Universally Unique IDentifier (UUID) URN Namespace, July 2005_, [https://datatracker.ietf.org/doc/html/rfc4122](https://datatracker.ietf.org/doc/html/rfc4122). +- **RFC 5646**, _Tags for Identifying Languages, September 2009_, [https://datatracker.ietf.org/doc/html/rfc5646](https://datatracker.ietf.org/doc/html/rfc5646). +- **TypeScript Programming Language**, [https://www.typescriptlang.org/](https://www.typescriptlang.org/). +- **Web Application Manifest**, _W3C Working Draft_, February 2022 [https://www.w3.org/TR/appmanifest/](https://www.w3.org/TR/appmanifest/) The following documents may be useful in understanding certain aspects of this Standard; however, knowledge of them is not essential to the creation of a compliant implementation of this Standard: -- **CUSIP**, _Committee on Uniform Security Identification Procedures_, . -- **FIGI**, _Financial Instrument Global Identifier_, . -- **ISIN**, _International Securities Identification Number_, -- **LEI**, _Legal Entity Identifier based on the ISO 17442 standard_, . -- **npm**, . -- **PermID**, _Permanent Identifiers_, . -- **pnpm**, . -- **REST**, , . -- **SEDOL**, _Stock Exchange Daily Official List_, . -- **yarn**, . +- **CUSIP**, _Committee on Uniform Security Identification Procedures_, [https://www.cusip.com/identifiers.html#/CUSIP](https://www.cusip.com/identifiers.html#/CUSIP). +- **FIGI**, _Financial Instrument Global Identifier_, [https://www.openfigi.com/about/figi](https://www.openfigi.com/about/figi). +- **ISIN**, _International Securities Identification Number_, [https://www.isin.org/isin/](https://www.isin.org/isin/) +- **LEI**, _Legal Entity Identifier based on the ISO 17442 standard_, [https://www.legalentityidentifier.co.uk/what-is-lei-code/](https://www.legalentityidentifier.co.uk/what-is-lei-code/). +- **npm**, [https://docs.npmjs.com/about-npm](https://docs.npmjs.com/about-npm). +- **PermID**, _Permanent Identifiers_, [https://permid.org/](https://permid.org/). +- **pnpm**, [https://pnpm.io/motivation](https://pnpm.io/motivation). +- **REST**, [https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm), [https://restfulapi.net/](https://restfulapi.net/). +- **SEDOL**, _Stock Exchange Daily Official List_, [https://www.lseg.com/sedol](https://www.lseg.com/sedol). +- **yarn**, [https://yarnpkg.com/getting-started](https://yarnpkg.com/getting-started). From e894b9d58e9151a85a027856ebbb65d094236221 Mon Sep 17 00:00:00 2001 From: DILPREET1910 Date: Wed, 6 Nov 2024 10:32:53 +0530 Subject: [PATCH 2/2] update schema2Markdown.js to generate MDX v3 compatible files --- website/schema2Markdown.js | 74 +++++++++++++++++++------------------- 1 file changed, 37 insertions(+), 37 deletions(-) diff --git a/website/schema2Markdown.js b/website/schema2Markdown.js index 145f52fdc..7603c985d 100644 --- a/website/schema2Markdown.js +++ b/website/schema2Markdown.js @@ -10,12 +10,12 @@ function processProperty(propertyName, propertyDetails, required, currentSchemaF if (propertyName === 'type') { //skip rendering the type property as it should be rendered at the top level return markdownContent; - } - + } + if (wrapInDetails) { markdownContent += "
\n" }; markdownContent += ` ${propertyName}${required ? " (required)" : ""}\n\n`; - - //Note this block doesn't support inline property definitions... only base types and references, + + //Note this block doesn't support inline property definitions... only base types and references, // it will not render an object or array defined inline beyond stating that it is one if (propertyDetails.type) { //if enum doesn't exist, its ignored @@ -24,7 +24,7 @@ function processProperty(propertyName, propertyDetails, required, currentSchemaF if (propertyDetails.type == "object") { if (propertyDetails.properties && Object.entries(propertyDetails.properties).length > 0) { markdownContent += '**Subproperties:**\n\n'; - + for (const [subpropertyName, subpropertyDetails] of Object.entries(propertyDetails.properties)) { let subPropRequired = propertyDetails?.required?.includes(subpropertyName) ?? false; markdownContent += processProperty(subpropertyName, subpropertyDetails, subPropRequired, currentSchemaFilePath); @@ -74,7 +74,7 @@ function processProperty(propertyName, propertyDetails, required, currentSchemaF if (wrapInDetails) { markdownContent += "
" } markdownContent += "\n\n"; - + return markdownContent; } @@ -116,7 +116,7 @@ function renderRef(contextRef, currentSchemaFilePath) { //render the content as it won't have its own page const referencedSchemaData = retrievePathInSchema(schemaData, objectPath); const referencedTitle = referencedSchemaData.title ?? ""; - + return processProperty(referencedTitle, referencedSchemaData, false, currentSchemaFilePath, false); } else { @@ -142,19 +142,19 @@ function renderRef(contextRef, currentSchemaFilePath) { //custom handling for other standard parts... return `**type**: ${standardPart}/${title}\n`; - //TODO handle API schema refs + //TODO handle API schema refs // - which are currently split across two different docs pages (Types and Metadata) // - perhaps reunite these pages and just link to the resulting page. } } - - + + } function hasAllOf(allOfArray) { - return Array.isArray(allOfArray) && - allOfArray.length > 0 && - allOfArray[0] != null && + return Array.isArray(allOfArray) && + allOfArray.length > 0 && + allOfArray[0] != null && allOfArray[0].properties != null } @@ -164,14 +164,14 @@ function hasProperties(schema) { // Function to generate Markdown content from JSON schema function generateObjectMD(schema, objectName, schemaFolderName, filePath) { - //If the schema doesn't contain a title, + //If the schema doesn't contain a title, // it may have been embedded in a definition who's name would have been passed in title = schema.title ?? objectName; let markdownContent = `# ${title}\n\n`; if (schema.description != null) { - markdownContent += `${escapeExperimental(schema.description)}\n\n`; + markdownContent += `${escapeExperimental(schema.description)}\n\n`; } //If the schema has a top level enum (e.g. API error schemas) then it needs rendering here. @@ -183,7 +183,7 @@ function generateObjectMD(schema, objectName, schemaFolderName, filePath) { const workingPath = filePath.replaceAll("\\","/"); const url = schema.$id; const githubUrl = workingPath.replace("../schemas/", `https://github.com/finos/FDC3/tree/main/schemas/`); - markdownContent += `## Schema\n\n<${url}> ([github](${githubUrl}))\n\n`; + markdownContent += `## Schema\n\n[${url}](${url}) ([github](${githubUrl}))\n\n`; if (hasAllOf(schema.allOf) || hasProperties(schema)) { // Extract properties, required fields, and $ref from the first allOf object @@ -191,15 +191,15 @@ function generateObjectMD(schema, objectName, schemaFolderName, filePath) { if (hasAllOf(schema.allOf)) { root = schema.allOf[0]; } - + const properties = root.properties; const requiredProperties = root.required; const typeString = properties?.type?.const; const ref = root.$ref; - + markdownContent += `## Type\n\n`; markdownContent += `\`${typeString}\`\n\n`; - markdownContent += `## Properties\n\n`; + markdownContent += `## Properties\n\n`; for (const [propertyName, propertyDetails] of Object.entries(properties)) { if (propertyName != "type"){ @@ -218,7 +218,7 @@ function generateObjectMD(schema, objectName, schemaFolderName, filePath) { } else { markdownContent += `## Example\n\n`; } - + schema.examples.forEach((example) => { markdownContent += '```json\n'; markdownContent += JSON.stringify(example, null, 2); @@ -269,13 +269,13 @@ function processSchemaFile(schemaFile, schemaFolderName) { } /** * Given a path to a schema file, retrieves the schema file contents. - * If a currentFilePath is specified the path is resolved relative to it + * If a currentFilePath is specified the path is resolved relative to it * (as it is assumed that the path to be resolved is relative to that file). - * + * * Does not support retrieving schemas via a full URL. - * - * @param {string} schemaFilePath - * @param {string} currentFilePath + * + * @param {string} schemaFilePath + * @param {string} currentFilePath * @returns Contents of the referenced schema file */ function retrieveSchemaFile (schemaFilePath, currentFilePath) { @@ -291,7 +291,7 @@ function retrieveSchemaFile (schemaFilePath, currentFilePath) { pathComponents.push(schemaFilePathData.base); resolvedPath = path.join(...pathComponents); } - + //read the file return fse.readJSONSync(resolvedPath); } @@ -306,9 +306,9 @@ function retrieveFolderName (schemaFilePath) { /** * Retrieve the content at a particular path in a schema object. - * @param {*} schemaData - * @param {*} pathInSchema - * @returns + * @param {*} schemaData + * @param {*} pathInSchema + * @returns */ function retrievePathInSchema(schemaData, pathInSchema) { let outputData = schemaData; @@ -323,18 +323,18 @@ function retrievePathInSchema(schemaData, pathInSchema) { } /** - * Retrieves the title element from a schema object, with an optional path + * Retrieves the title element from a schema object, with an optional path * (e.g. to a definition) within that schema. - * @param {*} schemaData - * @param {*} pathInSchema - * @returns + * @param {*} schemaData + * @param {*} pathInSchema + * @returns */ function retrieveTitleFromSchemaData(schemaData, pathInSchema) { //if a path within the schema was specified, navigate to it if (pathInSchema){ schemaData = retrievePathInSchema(schemaData, pathInSchema); } - + if (schemaData?.title) { return schemaData.title; } else { @@ -359,7 +359,7 @@ function parseSchemaFolder(schemaFolderName) { // Process each schema file let sidebarItems = []; for (const schemaFile of schemaFiles) { - + if (path.basename(schemaFile) === "context.schema.json"){ console.log(` Skipping ${schemaFile}`); } else { @@ -376,7 +376,7 @@ function main() { console.log("Generating Context reference pages...") //generate markdown docs for the current schema versions in the current docs draft - let sidebarObject = fse.readJsonSync(`./sidebars.json`) + let sidebarObject = fse.readJsonSync(`./sidebars.json`) let sidebarContextObject = { "type": "category", @@ -399,7 +399,7 @@ function main() { elem.items = sidebarContextObject.items; console.log("Replaced content of 'Context Data Part' of website navigation."); } - + }); //or create it if not found