@finos/fdc3

FDC3 aims to provide an open standard for interoperability on the financial desktop. This includes standardized verbs to invoke actions between applications (called "intents"), a standardized data format, an OpenAPI app directory standard, and standardized API operations.

The standard currently consists of four specifications:

1. API Specification
2. Intents Specification
3. Context Data Specification
4. App Directory Specification

The specifications are informed by agreed business use cases, and implemented and used by leading financial industry participants.

See https://fdc3.finos.org for more information, including on compliance and the FDC3 charter, as well as a comprehensive API Reference. You can also take the free FDC3 Training for an introduction to FDC3's core concepts and usage.

Supported Platforms

As an open standard, FDC3 can be implemented on any platform and in any language.

All that is required is a "desktop agent" that supports the FDC3 standard, which is responsible for co-ordinating application interactions.

Web

For web applications to be FDC3-enabled, they need to run in the context of an agent that makes the FDC3 API available to the application. This desktop agent is also responsible for launching and co-ordinating applications. It could be a browser extension, web app, or full-fledged desktop container framework.

Example

// declare FDC3-compliant data
const instrument = {
    type: 'fdc3.instrument',
    id: {
        ticker: 'AAPL',
        ISIN: 'US0378331005',
        FIGI : 'BBG000B9XRY4'
    }
}

// invoke an action in another application, with the required data
const result = await fdc3.raiseIntent('ViewAnalysis', instrument)

// join the red channel and broadcast data to subscribers
await fdc3.joinChannel('red')
fdc3.broadcast(instrument)

// set up a listener for incoming data
const listener = fdc3.addContextListener('fdc3.contact', contact => { })

Installation

To access the APIs in your application, simply install the FDC3 npm package:

# npm
npm install @finos/fdc3

# yarn
yarn add @finos/fdc3

# pnpm
pnpm install @finos/fdc3

Note that the web application still needs to run in the context of an FDC3 desktop agent to work. For more details, please see the relevant documentation.

Usage

FDC3 can be accessed either via the global window object:

if (window.fdc3) {
  const channel = await window.fdc3.getOrCreateChannel('myChannel')
  channel.broadcast({ ... })
}

Or by importing relevant FDC3 functions with ES6 module syntax:

import { getOrCreateChannel } from '@finos/fdc3'

// will throw if window.fdc3 is not available
const channel = await getOrCreateChannel('myChannel')
channel.broadcast({ ... })

Native

The FDC3 standard does not define wire formats for communication. Hence, for native applications to be FDC3-enabled, they need to make use of a library (e.g. a DLL in .Net or Jar file in Java) that provides them with an implementation of the FDC3 API. FDC3-enabled native applications are therefore specific to particular desktop container frameworks (or other suitable environments) that provide the necessary libraries.

Despite this limitation, implementing support for FDC3 in a native application can allow it to interact with a wide variety of FDC3-enabled web applications.

Roadmap

• Publish versioned NPM packages to ease adoption and implementation of FDC3 APIs.
• Release version 1.2 of the standard with expanded API capabilities.
• Establish a process to accelerate community-contributed context data definitions.
• Improve the app directory specification, with support for container-agnostic app manifests, and more type metadata around channels and launching apps.
• Release version 2.0 of the standard with API support for app instances, two-way data flow and requesting channels with context.
• Introduce a hosted app directory example with sample application definitions.
• Continue building out business use cases to inform future versions of the FDC3 Standard.

Using the standard? Let us know!

If you are an existing individual or corporate user of the FDC3 standard, we would love to hear from you: just email [e-mail] with details about how you are using the standard.

If you'd like to be listed as a user of the standard, you can directly send a pull request to update the FDC3 website: upload your logo to this folder and update this file with your company's details. If listing your logo publicly requires legal evaluation, you can reach out privately to FDC3 Maintainers.

Getting Involved

Interact with the FDC3 community

GitHub

FDC3 activity primarily happens in this FDC3 GitHub repository. Watch the repository in order to be notified of new Pull Requests and issues.

Slack

The fastest and more interactive way to connect and ask questions to the FDC3 community is to join the #fdc3 channel on the FINOS slack.

Email

If you'd like to receive official updates, and/or you don't have access to Slack, please send an email to [e-mail]. You can join the list by sending an email to [e-mail].

Meetings

Finally, another great way to interact with the community, is to attend the monthly FDC3 Standard Working Group Meeting and/or the quarterly FDC3 General Meeting: email [e-mail] to be added to the meeting invite directly, or find the meeting in the FINOS Community Calendar.

Need help?

Email [e-mail] if you need help getting started in the FDC3 Community. If you encounter technical difficulties accessing repositories, joining Slack, mailing lists or meetings, please email [e-mail].

Why should you get involved in FDC3?

If you or your firm intends to make use of the FDC3 Standard (by implementing a Desktop Agent or App Directory, by adding support to apps to interoperate with others via FDC3, or even by using apps, Desktop Agents or App Directories written by others) then participating in the governance, maintenance and onward development of the FDC3 Standard will help to protect and strengthen the ecosystem developing around FDC3. Doing so will also empower you to help guide the Standard in directions that are relevant to your use or that of your firm. If you or your firm are new to contributing to open source projects, please see the variety of resources available from FINOS, (such as the Open Source readiness project), Linux Foundation (Participating in Open Source communities) and others (e.g. opensource.guide).

What it means to be an FDC3 Participant, Editor or Maintainer

According to Governance document document:

• "Participants" are those that have made contributions to the FDC3 Standard Working Group (subject to the FINOS IP Policy). The FDC3 Standard Working Group has the specific purpose of defining and releasing subsequent updates to the Standard. In practice, that means people that attend and contribute to meetings, raise issues, pull requests (to submit patches to the Standard) and reviews.

• "Editors" are responsible for ensuring that the contents of the Standard's documents accurately reflect the decisions that have been made by the group, and that the specification adheres to formatting and content guidelines.

• "Maintainers" are responsible for organizing activities around developing, maintaining, and updating the specification(s) developed by the Working Group. Maintainers are also responsible for determining consensus and coordinating appeals.

Whilst all 3 roles require some amount of attention, being an Editor or Maintainer will obviously require a greater and more regular investment of time from anyone taking on that role.

How do you become a Participant, Editor or Maintainer?

Becoming an FDC3 participant is as easy as attending meetings and/or raising issues for changes you'd like see in the Standard, commenting on issues others have raised or even asking questions (which can often result in the clarification of the Standard's documentation to help others with the same questions in future).

If you are going to use, implement or benefit from the FDC3 Standard, we also recommend that you sign up as a voting participant. To do so, please use this link: [e-mail] to send a templated email email to join the enrolled voting participants group. Please note that standard participants are bound to the provisions in the FINOS IP Policy as described in the FINOS Standards governance document.

Upon enrollment as an FDC3 voting participant, you will be invited to join the FINOS GitHub organization and the fdc3-participants GitHub team.

Become an FDC3 Editor or Maintainer

Once you are an enrolled participant in FDC3, you can apply to become an editor or maintainer by contacting the existing FDC3 maintainers at [e-mail] and then seeking the approval of the FDC3 Standards Working Group. Generally, the maintainers will look for both a history of contribution to FDC3 and a commitment to investing sufficient time in the role from any prospective candidates before proposing them to the Standards Working Group for approval. If you are new to FDC3, but willing to make the investment of time, the maintainers can work with you to build up a history of contribution.

Mailing list

You can contact the FDC3 maintainers by sending an email to [e-mail].

FDC3 Archive

An archive of FDC3 documentation and meeting notes is available at https://finosfoundation.atlassian.net/wiki/spaces/FDC3/overview. The mailing list archive for [e-mail] is available at https://groups.google.com/a/finos.org/g/fdc3

Contributing

If you'd like to contribute to the FDC3 standard, or have noticed something that needs correcting, the first step is to raise an issue on the FDC3 Github Repo and describe what you'd like to see changed. There are a number of issue templates that you can choose from here.

Issues that change the Standard usually need discussion. You can post comments directly on the issue or can ask for it to be added to a Standards Working Group meeting agenda by emailing [e-mail], sending a message to the #fdc3 channel on the FINOS slack or tag the FDC3 maintainers (@finos/fdc3-maintainers) in your issue.

To implement changes in the FDC3 repository resolving an issue please read our contribution guidelines.

Contributions merged into the master branch of the FDC3 repository will form part of the next pre-draft of the FDC3 Standard (as defined by the FDC3 Governance document), which must be approved by the Standard Working Group voting participants before it is accepted as a draft and subsequently released as the next version of the Standard.

NOTE: Commits and pull requests to FINOS repositories will only be accepted from those contributors with an active, executed Individual Contributor License Agreement (ICLA) with FINOS, OR who are covered under an existing and active Corporate Contribution License Agreement (CCLA) executed with FINOS. Commits from individuals not covered under an ICLA or CCLA will be flagged and blocked by the Linux Foundation EasyCLA tool. Please note that some CCLAs require individuals/employees to be explicitly named on the CCLA.

Need an ICLA? Unsure if you are covered under an existing CCLA? Email [e-mail].

License

Copyright 2017-2022 FINOS and FDC3 Participants

Version 1.0 of the FDC3 specification is licensed under the FDC3 1.0 Final Specification License.

Subsequent FDC3 specifications and draft specifications are subject to the FINOS IP Policy, which authorizes implementation of FDC3 specifications without charge, on a RAND basis, subject to the terms of the policy. For details of the IP commitments made by contributors to FDC3, please refer to the policy.

Reference implementations and other software contained in FDC3 repositories is licensed under the Apache License, Version 2.0 unless otherwise noted. SPDX-License-Identifier: Apache-2.0.

Intellectual Property Claims

Users of the FDC3 standard are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.

THIS STANDARD IS BEING OFFERED WITHOUT ANY WARRANTY WHATSOEVER, AND IN PARTICULAR, ANY WARRANTY OF NON-INFRINGEMENT IS EXPRESSLY DISCLAIMED. ANY USE OF THIS STANDARD SHALL BE MADE ENTIRELY AT THE IMPLEMENTER'S OWN RISK, AND NEITHER THE FOUNDATION, NOR ANY OF ITS MEMBERS OR SUBMITTERS, SHALL HAVE ANY LIABILITY WHATSOEVER TO ANY IMPLEMENTER OR THIRD PARTY FOR ANY DAMAGES OF ANY NATURE WHATSOEVER, DIRECTLY OR INDIRECTLY, ARISING FROM THE USE OF THIS STANDARD.