Skip to content

Commit e1caa62

Browse files
rikoerikoe
committed
docs: update main readme for release branch to match master
1 parent 5918db2 commit e1caa62

File tree

1 file changed

+166
-57
lines changed

1 file changed

+166
-57
lines changed

‎README.md‎

Lines changed: 166 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,87 +1,196 @@
1-
[![npm-build](https://github.com/finos/FDC3/workflows/npm-build/badge.svg)](https://github.com/finos/FDC3/actions?query=workflow%3Anpm-build)
2-
[![website-build](https://github.com/finos/FDC3/workflows/website-build/badge.svg)](https://github.com/finos/FDC3/actions?query=workflow%3Awebsite-build)
1+
# <a href='http://fdc3.finos.org'><img src='./website/static/img/fdc3-logo-2019-color.png' height='150' alt='FDC3 Logo' aria-label='fdc3.finos.org' /></a>
2+
33
[![GitHub release (latest by date)](https://img.shields.io/github/v/release/finos/fdc3)](https://github.com/finos/fdc3/releases/latest)
44
[![npm](https://img.shields.io/npm/v/@finos/fdc3)](https://www.npmjs.com/package/@finos/fdc3)
55
[![FINOS - Released](https://cdn.jsdelivr.net/gh/finos/contrib-toolbox@master/images/badge-released.svg)](https://finosfoundation.atlassian.net/wiki/display/FINOS/Released)
6-
[![GitHub](https://img.shields.io/github/license/finos/fdc3)](https://opensource.org/licenses/Apache-2.0
7-
)
6+
[![GitHub](https://img.shields.io/github/license/finos/fdc3)](https://opensource.org/licenses/Apache-2.0)
87
[![Stack Overflow](https://img.shields.io/badge/stackoverflow-fdc3-orange.svg)](https://stackoverflow.com/questions/tagged/fdc3)
8+
[![npm-build](https://github.com/finos/FDC3/workflows/npm-build/badge.svg)](https://github.com/finos/FDC3/actions?query=workflow%3Anpm-build)
9+
[![website-build](https://github.com/finos/FDC3/workflows/website-build/badge.svg)](https://github.com/finos/FDC3/actions?query=workflow%3Awebsite-build)
10+
[![Slack](https://img.shields.io/badge/slack-@finos/fdc3-green.svg?logo=slack)](https://finos-lf.slack.com/messages/fdc3/)
11+
12+
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.
13+
14+
The standard currently consists of four specifications:
15+
16+
1. [API Specification](https://fdc3.finos.org/docs/api/spec)
17+
2. [Intents Specification](https://fdc3.finos.org/docs/intents/spec)
18+
3. [Context Data Specification](https://fdc3.finos.org/docs/context/spec)
19+
4. [App Directory Specification](https://fdc3.finos.org/docs/app-directory/spec)
20+
21+
The specifications are informed by agreed [business use cases](https://fdc3.finos.org/docs/use-cases/overview),
22+
and implemented and used by leading [financial industry participants](https://fdc3.finos.org/users).
23+
24+
See https://fdc3.finos.org for more information, including on [compliance] and the [FDC3 charter], as well as a comprehensive [API Reference].
25+
26+
[FDC3 Charter]: https://fdc3.finos.org/docs/fdc3-charter
27+
[Compliance]: https://fdc3.finos.org/docs/fdc3-compliance
28+
[API Reference]: https://fdc3.finos.org/docs/api/ref/DesktopAgent
29+
30+
# Supported Platforms
31+
32+
As an open standard, FDC3 can be implemented on any platform and in any language.
33+
34+
All that is required is a "desktop agent" that supports the FDC3 standard, which is responsible for co-ordinating application interactions.
35+
36+
## Web
37+
38+
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 lauching and co-ordinating applications. It could be a browser extension, web app, or full-fledged desktop container framework.
39+
40+
### Example
41+
42+
```ts
43+
// declare FDC3-compliant data
44+
const instrument = {
45+
type: 'fdc3.instrument',
46+
id: {
47+
ticker: 'AAPL',
48+
ISIN: 'US0378331005',
49+
FIGI : 'BBG000B9XRY4'
50+
}
51+
}
52+
53+
// invoke an action in another application, with the required data
54+
const result = await fdc3.raiseIntent('ViewAnalysis', instrument)
55+
56+
// join the red channel and broadcast data to subscribers
57+
await fdc3.joinChannel('red')
58+
fdc3.broadcast(instrument)
59+
60+
// set up a listener for incoming data
61+
const listener = fdc3.addContextListener('fdc3.contact', contact => { })
62+
```
63+
64+
### Installation
65+
66+
To access the APIs in your application, simply install the FDC3 npm package:
67+
68+
```sh
69+
# npm
70+
npm install @finos/fdc3
71+
72+
# yarn
73+
yarn add @finos/fdc3
974

10-
# FDC3
75+
# pnpm
76+
pnpm install @finos/fdc3
77+
```
1178

12-
The mission of the Financial Desktop Connectivity and Collaboration Consortium (FDC3) is to develop specific protocols and taxonomies to advance the ability of desktop applications in financial workflows to interoperate in a plug-and-play fashion and without prior, bi-lateral agreements.
79+
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](https://fdc3.finos.org/docs/installation).
1380

14-
## About this Repository
15-
FDC3 is a standard. This repository houses the documentation and specifications for the ratified FDC3 standards.
81+
### Usage
1682

17-
## Using the standard
18-
Check out [the documentation website](https://fdc3.finos.org) for the different components of the standard, an overview of [common use cases](https://fdc3.finos.org/docs/1.1/use-cases/overview), developer [API docs](https://fdc3.finos.org/docs/1.1/api/overview) and [standard compliance information](https://fdc3.finos.org/docs/1.1/fdc3-compliance).
83+
FDC3 can be accessed either via the global window object:
1984

20-
Latest version of the standard is [1.1](https://fdc3.finos.org/docs/1.1/fdc3-intro). See [all available versions](https://fdc3.finos.org/versions).
85+
```ts
86+
if (window.fdc3) {
87+
const channel = await window.fdc3.getOrCreateChannel('myChannel')
88+
channel.broadcast({ ... })
89+
}
90+
```
2191

22-
## Learn more and interact with the Community
23-
To learn more and ask questions you subscribe to the [FDC3 General List]([email protected]) by emailing [[email protected]](mailto:[email protected]). Another great way to interact with the standard participants is to attend the quarterly [FDC3 General meeting](https://github.com/finos/FDC3/issues?q=label%3A%22General+Meeting%22): you should receive an invite by signing up to the general list or you can find the meeting in the [FINOS Project Meetings Calendar](https://calendar.google.com/calendar/embed?src=finos.org_fac8mo1rfc6ehscg0d80fi8jig%40group.calendar.google.com).
92+
Or by importing relevant FDC3 functions with ES6 module syntax:
93+
94+
```ts
95+
import { getOrCreateChannel } from '@finos/fdc3'
96+
97+
// will throw if window.fdc3 is not available
98+
const channel = await getOrCreateChannel('myChannel')
99+
channel.broadcast({ ... })
100+
```
101+
102+
## Native
103+
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.
104+
105+
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.
106+
107+
108+
# Roadmap
109+
110+
- [ ] Publish versioned NPM packages to ease adoption and implementation of FDC3 APIs.
111+
- [ ] Establish a process to accelerate community-contributed context data definitions.
112+
- [ ] Release version 1.2 of the standard with expanded API capabilities.
113+
- [ ] Release version 2.0 of the standard with support for app instances, two-way data flow and joining multiple channels.
114+
- [ ] Improve the app directory specification, with support for container-agnostic app manifests, and more type metadata around channels and launching apps.
115+
- [ ] Introduce a hosted app directory example with sample application definitions.
116+
- [ ] Continue building out business use cases to inform future versions of the FDC3 Standard.
117+
118+
# Getting Involved
119+
120+
## Learn more and interact with the community
121+
122+
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](https://finos-lf.slack.com/messages/fdc3/).
123+
124+
If you'd like to receive official updates, and/or you don't have access to Slack, please send an email to [[email protected]]. You can join the list by sending an email to [[email protected]].
125+
126+
Finally, another great way to interact with the community, is to attend the quarterly [FDC3 General Meeting]: you will receive an invite by signing up to the mailing list, or you can find the meeting in the [FINOS Project Meetings Calendar].
127+
128+
[[email protected]]: mailto:[email protected]
129+
[[email protected]]: mailto:[email protected]
130+
[FDC3 General Meeting]: https://github.com/finos/FDC3/issues?q=label%3A%22General+Meeting%22
131+
[FINOS Project Meetings Calendar]: https://calendar.google.com/calendar/embed?src=finos.org_fac8mo1rfc6ehscg0d80fi8jig%40group.calendar.google.com
24132

25133
## Using the standard? Let us know!
26-
If you an existing individual or corporate user of the FDC3 standard, we would love to hear from you: just email the [FDC3 General List]([email protected]) with details about how you are using the standard. If you'd like to be listed as a standard user, you can directly [send a pull request to update our website](./website/data/users.json) or, if listing your logo publicly requires legal evaluation, you can reach out privately to the [FDC3 Product Management Committee]([email protected]).
27134

28-
## Participate in the standard process
29-
The [FDC3 Standard Working Group](https://github.com/finos/FDC3/issues?q=label%3A%22Standard+WG+Meeting%22) meets monthly: you are welcome to join by subscribing to the [FINOS Project Meetings Calendar](https://calendar.google.com/calendar/embed?src=finos.org_fac8mo1rfc6ehscg0d80fi8jig%40group.calendar.google.com). If you'd like to formally enroll as a voting standard participant process (as described in [our standards governance](https://github.com/finos/community/tree/master/governance/Standards-Projects#joining-a-standards-project-grace-period-for-new-participants)) please email [[email protected]](mailto:[email protected]?subject=Please%20enroll%20me%20as%20FDC3%20standard%20participant&amp;cc=fdc3-pmc%40finos.org&amp;body=HI%2C%20my%20name%20is%20%3CFirstName%20LastName%3E%20and%20I%27d%20like%20to%20formally%20participate%20to%20the%20FDC3%20standard%20process.%20I%20plan%20to%20contribute%20as%20%3Cindividual%7Con%20behalf%20of%20organizationName%3E%20and%20I%20have%20reviewed%20the%20policies%20described%20at%20https%3A%2F%2Fgithub.com%2Ffinos%2Fcommunity%2Ftree%2Fmaster%2Fgovernance%2FStandards-Projects%20.%20Thank%20you!) making your intent to participate in the standard process explicit. Please note that standard participants are bound to the provisions in the [FINOS IP Policy](https://github.com/finos/community/blob/master/governance/IP-Policy.pdf) as described in the [FINOS standards governance](https://github.com/finos/community/tree/master/governance/Standards-Projects).
135+
If you are an existing individual or corporate user of the FDC3 standard, we would love to hear from you: just email [[email protected]] with details about how you are using the standard.
30136

31-
## Contributing code to this repository
32-
If you'd like to contribute code to this repository:
137+
If you'd like to be listed as a user of the standard, you can directly send a pull request to update the website: upload your logo to [this folder](https://github.com/finos/FDC3/tree/master/website/static/img/users) and update [this file](https://github.com/finos/FDC3/edit/master/website/data/users.json) with your company's details. If listing your logo publicly requires legal evaluation, you can reach out privately to the [FDC3 Product Management Committee](mailto:[email protected]).
33138

34-
1. Fork it (<https://github.com/finos/FDC3/fork>)
35-
2. Create your feature branch (`git checkout -b feature/fooBar`)
36-
3. Commit your changes (`git commit -am 'Add some fooBar'`)
37-
4. Push to the branch (`git push origin feature/fooBar`)
38-
5. Create a new Pull Request
139+
## The Standard Working Group
140+
141+
The [FDC3 Standard Working Group] has the specific purpose of defining and releasing subsequent updates to the standard.
142+
For more context, see the [April 2020 announcement] of the new streamlined approach to FDC3 meetings.
143+
144+
[FDC3 Standard Working Group]: https://github.com/finos/FDC3/issues?q=label%3A%22Standard+WG+Meeting%22
145+
[April 2020 announcement]: https://groups.google.com/a/finos.org/g/fdc3/c/Jp3Etp42Waw
146+
147+
### Meetings
148+
The Standard WG meets monthly on the fourth Thursday at 10am ET / 3pm GMT, and has an open participation model. You are welcome to join by subscribing to the [FINOS Project Meetings Calendar].
39149

40-
The team will review the PR and decide about merging.
150+
### Enrollment
151+
If you would like to formally enroll as a voting participant to the standard (as described in our standards governance),
152+
please email [[email protected]] making your intent to participate in the standard process explicit.
153+
Please note that standard participants are bound to the provisions in the [FINOS IP Policy] as described in the [FINOS standards governance].
41154

42-
Note that you will require a contributor agreement (individual or corporate) before your code can be merge, so please review [FINOS Contribution requirements](.github/CONTRIBUTING.md).
155+
[[email protected]]: mailto:[email protected]?subject=Please%20enroll%20me%20as%20FDC3%20standard%20participant&amp;cc=fdc3-pmc%40finos.org&amp;body=HI%2C%20my%20name%20is%20%3CFirstName%20LastName%3E%20and%20I%27d%20like%20to%20formally%20participate%20to%20the%20FDC3%20standard%20process.%20I%20plan%20to%20contribute%20as%20%3Cindividual%7Con%20behalf%20of%20organizationName%3E%20and%20I%20have%20reviewed%20the%20policies%20described%20at%20https%3A%2F%2Fgithub.com%2Ffinos%2Fcommunity%2Ftree%2Fmaster%2Fgovernance%2FStandards-Projects%20.%20Thank%20you!
156+
[FINOS IP Policy]: https://github.com/finos/community/blob/master/governance/IP-Policy.pdf
157+
[FINOS standards governance]: https://github.com/finos/community/tree/master/governance/Standards-Projects
43158

44-
_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 FINOS Cla-bot tool. Please note that some CCLAs require individuals/employees to be explicitly named on the CCLA.
159+
## The Product Management Committee
45160

46-
*Need an ICLA? Unsure if you are covered under an existing CCLA? Email [[email protected]](mailto:[email protected])*
161+
The [FDC3 Product Management Committee] (PMC) is responsible for co-ordinating the work of the FDC3 Standard Working Group, as well as FDC3-related planning and communications. For more context see the [FDC3 Archive].
47162

48-
## Roadmap
49-
With Productization on track to land at end of Q1, the expectation is that Q2 will be focused on implementations and feedback from those implementations driving further standards.
50-
### Target Items for Q2
51-
#### API
52-
* Expand the broadcast API or introduce a new channels API to support the context setting use case.
53-
* Publish npm package with FDC3 API definitions.
163+
[FDC3 Product Management Committee]: https://github.com/finos/FDC3/issues?q=label%3A%22PMC+Meeting%22
164+
[FDC3 Archive]: https://finosfoundation.atlassian.net/wiki/spaces/FDC3/overview
54165

55-
#### App Directory
56-
* Search capabilities, surfacing other content
57-
* Manifest format detail (describing the content)
58-
* Eventing
166+
### Meetings
167+
The PMC meets every second Friday at 9:30am ET / 2:30pm GMT. Find the next meeting, including meeting details, on the [FINOS Project Meetings Calendar].
59168

60-
#### Context Data
61-
* Pivot to JSON schema for representing type definitions. We have found that TypeScript is too implementation-specific and too restrictive in practice.
62-
* Use https://quicktype.io/ to generate type definitions from JSON schema for multi-language support.
63-
* Formalise current example types into official FDC3 types for contact, organisation, instrument etc in conjunction with/based on the Financial Objects program work.
169+
### Mailing list
170+
You can get in touch with the FDC3 PMC by sending an email to [[email protected]]. Join the PMC Mailing list by sending an email to [[email protected]].
64171

65-
#### Intents
66-
* Add detailed documentation to each intent - linking to use cases
67-
* Align closer with Context Data WG
68-
* Evaluate real use cases, given that we have input from early adapters
69-
* Extend with new intents, based on above + accepted use cases
172+
[[email protected]]: mailto:[email protected]
173+
[[email protected]]: mailto:[email protected]
174+
175+
# Contributing
176+
177+
If you'd like to contribute code to this repository:
178+
179+
1. Fork it (<https://github.com/finos/FDC3/fork>)
180+
2. Create your feature branch (`git checkout -b feature/fooBar`)
181+
3. Read our [contribution guidelines](CONTRIBUTING.md) and [Community Code of Conduct](https://www.finos.org/code-of-conduct)
182+
4. Commit your changes (`git commit -am 'add some fooBar'`)
183+
5. Push to the branch (`git push origin feature/fooBar`)
184+
6. Create a new Pull Request
70185

71-
#### Use Cases
72-
* Continue to process new and existing FDC3 Use Cases
73-
* Assess extending the use cases working group to additional FINOS programs
186+
_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 FINOS Clabot tool. Please note that some CCLAs require individuals/employees to be explicitly named on the CCLA.
74187

75-
### Backlog Beyond Q2
76-
* Define the next set of FDC3 Context Data types in conjunction with/based on Financial Objects working group work.
77-
* Work with Financial Objects and other FINOS programs to reach consensus on how to make standardized taxonomies available for consumption, both for viewing/editing and programmatically e.g. for validation.
78-
* Create comprehensive examples of use cases that show how to use the various FDC3 standards together to enable interoperability.
79-
* App Directory Identity and authentication
188+
*Need an ICLA? Unsure if you are covered under an existing CCLA? Email [[email protected]](mailto:[email protected]).*
80189

81-
## License
190+
# License
82191

83-
Copyright 2017 FDC3
192+
Copyright 2017-2021 FINOS
84193

85194
Distributed under the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0).
86195

87-
SPDX-License-Identifier: [Apache-2.0](https://spdx.org/licenses/Apache-2.0)
196+
SPDX-License-Identifier: [Apache-2.0](https://spdx.org/licenses/Apache-2.0)

0 commit comments

Comments
 (0)