Skip to content

Commit 9151317

Browse files
rikoerikoe
authored
Merge pull request #190 from rikoe/doc-updates
doc updates
2 parents 0c8df4d + 7e6d041 commit 9151317

18 files changed

+266
-34
lines changed

‎docs/appd-discovery.md renamed to ‎docs/app-directory/discovery.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
id: appd-discovery
2+
id: discovery
33
sidebar_label: App Directory Discovery
44
title: App Directory Discovery
55
hide_title: true

‎docs/appd-intro.md renamed to ‎docs/app-directory/overview.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
id: appd-intro
2+
id: overview
33
sidebar_label: App Directory Overview
44
title: App Directory Overview
55
hide_title: true
@@ -17,8 +17,8 @@ The FDC3 App Directory provides trusted identity for financial desktop apps. Thi
1717

1818
## Sections to review
1919

20-
- [Application Directory Discovery](appd-discovery.md) describes how to resolve the location of the Application Directory using an application identifier.
21-
- [Application Directory Use](appd-use.md) provides a simple view on how application directories can be used. This also includes links to a reference implementation.
22-
- [API specification](appd-spec.md) is the interface definition required to support a compatible application directory.
20+
- [Application Directory Discovery](discovery.md) describes how to resolve the location of the Application Directory using an application identifier.
21+
- [Application Directory Usage](usasge.md) provides a simple view on how application directories can be used. This also includes links to a reference implementation.
22+
- [Application Directory specification](spec.md) is the interface definition required to support a compatible application directory.
2323

2424
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14, [RFC 2119](https://tools.ietf.org/id/draft-faltstrom-uri-11.html#RFC2119) [RFC2119].

‎docs/appd-spec.md renamed to ‎docs/app-directory/spec.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
id: appd-spec
2+
id: spec
33
sidebar_label: App Directory Specification
44
title: App Directory Specification
55
---

‎docs/appd-use.md renamed to ‎docs/app-directory/usage.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
---
2-
id: appd-use
3-
sidebar_label: App Directory Use
4-
title: App Directory Use
2+
id: usage
3+
sidebar_label: App Directory Usage
4+
title: App Directory Usage
55
hide_title: true
66
---
77

8-
# App Directory Use
8+
# App Directory Usage
99

1010
An application directory (AppD) provides information about an application's
1111
identifiers, intents that provide contexts, and location of metadata providing

‎docs/apps-and-platforms.md

Lines changed: 0 additions & 6 deletions
This file was deleted.

‎docs/context/ref/Contact.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ https://fdc3.finos.org/schemas/next/contact.schema.json
1818

1919
## Details
2020

21-
| Property | Type | Required | Value |
21+
| Property | Type | Required | Example Value |
2222
|-------------|---------|----------|-------------------|
2323
| `type` | string | Yes | `'fdc3.contact'` |
2424
| `name` | string | No | `'Jane Doe'` |

‎docs/context/ref/ContactList.md

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,12 @@ hide_title: true
88

99
A collection of contacts, e.g. for chatting to or calling multiple contacts.
1010

11+
Notes:
12+
13+
- The contact list schema does not explicitly include identifiers in the `id` section, as there
14+
is not a common standard for such identifiers. Applications can, however, populate
15+
this part of the contract with custom identifiers if so desired.
16+
1117
## Type
1218

1319
`fdc3.contactList`
@@ -18,9 +24,10 @@ https://fdc3.finos.org/schemas/next/contactList.schema.json
1824

1925
## Details
2026

21-
| Property | Type | Required | Value |
27+
| Property | Type | Required | Example Value |
2228
|-------------|-----------|----------|------------------------|
2329
| `type` | string | Yes | `'fdc3.contactList'` |
30+
| `id` | object | No | `{ customId: '5576' }` |
2431
| `name` | string | No | `'My address book'` |
2532
| `contacts` | Contact[] | Yes | `[contact1, contact2]` |
2633

‎docs/context/ref/Context.md

Lines changed: 70 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,73 @@ hide_title: true
66
---
77
# `Context`
88

9-
_TO BE COMPLETED_
9+
The `fdc3.context` type defines the basic contract or "shape" for all data exchanged by FDC3 operations. As such, it is not
10+
really meant to be used on its own, but is imported by more specific type definitions (standardised or custom) to provide
11+
the structure and properties shared by all FDC3 context data types.
12+
13+
The key element of FDC3 context types is their mandatory `type` property, which is used to identify what type of data the
14+
object represents, and what shape it has.
15+
16+
Notes:
17+
18+
- The FDC3 context type, and all derived types, define the minimum set of fields a context data object of a particular type
19+
can be expected to have, but this can always be extended with custom fields as appropriate.
20+
21+
## Type
22+
23+
`fdc3.context`
24+
25+
## Schema
26+
27+
https://fdc3.finos.org/schemas/next/context.schema.json
28+
29+
## Details
30+
31+
| Property | Type | Required | Example Value |
32+
|-------------|---------|----------|----------------------------------|
33+
| `type` | string | Yes | `'fdc3.context'` |
34+
| `name` | string | No | `'Display name'` |
35+
| `id` | object | No | `{ id: 'value', 'id': 'value' }` |
36+
37+
### `type` (required)
38+
39+
The type property is the only _required_ part of the FDC3 context data schema.
40+
The FDC3 [API](../../api/overview) relies on the `type` property being present to route shared context data appropriately.
41+
42+
FDC3 [Intents](../../intents/overview) also register the context data types they support in an FDC3 [App Directory](../..app-directory/overview), used for intent discovery and routing.
43+
44+
Standardised FDC3 context types have well-known `type` properties prefixed with the `fdc3` namespace, e.g. `fdc3.instrument`.
45+
For non-standard types, e.g. those defined and used by a particular organisation, the convention is to prefix them with an
46+
organization-specific namespace, e.g. `blackrock.fund`.
47+
48+
See the [Context Data Specification](../../context/spec) for more information about context data types.
49+
50+
### `name` (optional)
51+
52+
Context data objects may include a name property that can be used for more information, or display purposes. Some
53+
derived types may require the name object as mandatory, depending on use case.
54+
55+
### `id` (optional)
56+
57+
Context data objects may include a set of equivalent key-value pairs that can be used to help applications
58+
identify and look up the context type they receive in their own domain. The idea behind this design is that applications can provide as many equivalent identifiers to a target application as possible, e.g. an instrument may be represented by an ISIN, CUSIP or Bloomberg identifier.
59+
60+
Identifiers do not make sense for all types of data, so the `id` property is therefore optional, but some derived types may choose to require at least one identifier.
61+
62+
## See Also
63+
64+
FDC3 Specifications
65+
- [Context Data](../../context/spec)
66+
- [Intents](../../intents/spec)
67+
- [API](../../api/spec)
68+
- [App Directory](../../app-directory/spec)
69+
70+
FDC3 Context Types
71+
- [Contact](Contact)
72+
- [ContactList](ContactList)
73+
- [Country](Country)
74+
- [Instrument](Instrument)
75+
- [InstrumentList](InstrumentList)
76+
- [Organization](Organization)
77+
- [Position](Position)
78+
- [Portfolio](Portfolio)

‎docs/context/ref/Country.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ https://fdc3.finos.org/schemas/next/country.schema.json
2626

2727
## Details
2828

29-
| Property | Type | Required | Value |
29+
| Property | Type | Required | Example Value |
3030
|------------------|---------|----------|----------------------|
3131
| `type` | string | Yes | `'fdc3.country'` |
3232
| `name` | string | No | `'Sweden'` |

‎docs/context/ref/Instrument.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ https://fdc3.finos.org/schemas/next/instrument.schema.json
3232

3333
## Details
3434

35-
| Property | Type | Required | Value |
35+
| Property | Type | Required | Example Value |
3636
|-------------|---------|----------|---------------------|
3737
| `type` | string | Yes | `'fdc3.instrument'` |
3838
| `name` | string | No | `'Microsoft'` |

‎docs/context/ref/InstrumentList.md

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,12 @@ A collection of instruments. Use this type for use cases that require not just a
1010

1111
When holding information for each instrument is required, it is recommended to use the [Portfolio](Portfolio) type, though.
1212

13+
Notes:
14+
15+
- The instrument list schema does not explicitly include identifiers in the `id` section, as there
16+
is not a common standard for such identifiers. Applications can, however, populate
17+
this part of the contract with custom identifiers if so desired.
18+
1319
## Type
1420

1521
`fdc3.instrumentList`
@@ -20,10 +26,11 @@ https://fdc3.finos.org/schemas/next/instrumentList.schema.json
2026

2127
## Details
2228

23-
| Property | Type | Required | Value |
29+
| Property | Type | Required | Example Value |
2430
|---------------|--------------|----------|--------------------------------|
2531
| `type` | string | Yes | `'fdc3.instrumentList'` |
2632
| `name` | string | No | `'Interesting instruments...'` |
33+
| `id` | object | No | `{ customId: '5464' }` |
2734
| `instruments` | Instrument[] | Yes | `[instrument1, instrument2]` |
2835

2936
## Example

‎docs/context/ref/Organization.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ https://fdc3.finos.org/schemas/next/organization.schema.json
2323

2424
## Details
2525

26-
| Property | Type | Required | Value |
26+
| Property | Type | Required | Example Value |
2727
|-------------|---------|----------|---------------------------|
2828
| `type` | string | Yes | `'fdc3.organization'` |
2929
| `name` | string | No | `'Cargill, Incorporated'` |

‎docs/context/ref/Portfolio.md

Lines changed: 90 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,93 @@ hide_title: true
66
---
77
# `Portfolio`
88

9-
_TO BE COMPLETED_
9+
A financial portfolio made up of muliple positions (holdings) in several instruments. Contrast this
10+
with e.g. the [InstrumentList](InstrumentList) type, which is just a list of instruments.
11+
12+
This is a good example of how types can be composed and extended with extra properties to define more complex types.
13+
14+
The [Portfolio](Portfolio) type consists of an array of [Position](Position) types, each of which
15+
refers to a single [Instrument](Instrument) and a holding amount for that instrument.
16+
17+
Notes:
18+
19+
- Like all other FDC3 context types, extra properties for the portfolio can be added, the schema just
20+
specifies the minimum contract.
21+
22+
- The portfolio schema does not explicitly include identifiers in the `id` section, as there
23+
is not a common standard for such identifiers. Applications can, however, populate
24+
this part of the contract with custom identifiers if so desired.
25+
26+
## Type
27+
28+
`fdc3.portfolio`
29+
30+
## Schema
31+
32+
https://fdc3.finos.org/schemas/next/portfolio.schema.json
33+
34+
## Details
35+
36+
| Property | Type | Required | Example Value |
37+
|--------------|------------|----------|---------------------------|
38+
| `type` | string | Yes | `'fdc3.portfolio'` |
39+
| `id` | object | No | `{ portfolioId: '7381' }` |
40+
| `name` | string | No | `'My share portfolio'` |
41+
| `positions` | Position[] | Yes | `[position1, position2]` |
42+
43+
## Example
44+
45+
```js
46+
const position = {
47+
type: 'fdc3.portfolio',
48+
positions: [
49+
{
50+
type: 'fdc3.position',
51+
instrument: {
52+
type: 'fdc3.instrument'
53+
id: {
54+
ticker: 'AAPL'
55+
}
56+
},
57+
holding: 2000000
58+
},
59+
{
60+
type: 'fdc3.position',
61+
instrument: {
62+
type: 'fdc3.instrument'
63+
id: {
64+
ticker: 'MSFT'
65+
}
66+
},
67+
holding: 1500000
68+
},
69+
{
70+
type: 'fdc3.position',
71+
instrument: {
72+
type: 'fdc3.instrument'
73+
id: {
74+
ticker: 'IBM'
75+
}
76+
},
77+
holding: 3000000
78+
}
79+
]
80+
}
81+
82+
fdc3.raiseIntent('ViewAnalysis', portfolio)
83+
```
84+
85+
## See Also
86+
87+
Other Types
88+
- [Instrument](Instrument)
89+
- [InstrumentList](InstrumentList)
90+
- [Position](Position)
91+
92+
Intents
93+
- [ViewAnalysis](../../intents/ref/ViewAnalysis)
94+
- [ViewChart](../../intents/ref/ViewChart)
95+
- [ViewNews](../../intents/ref/ViewNews)
96+
97+
FINOS Financial Objects
98+
- [Position](https://fo.finos.org/docs/objects/portfolio)

‎docs/context/ref/Position.md

Lines changed: 65 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,68 @@ hide_title: true
66
---
77
# `Position`
88

9-
_TO BE COMPLETED_
9+
A financial position made up of an instrument and a holding in that instrument. This type is a good
10+
example of how new context types can be composed from existing types.
11+
12+
In this case, the instrument and the holding amount for that instrument are required values.
13+
14+
The [Position](Position) type goes hand-in-hand with the [Portfolio](Portfolio) type, which represents
15+
multiple holdings in a combination of instruments.
16+
17+
Notes:
18+
19+
- Like all other FDC3 context types, extra properties for the position can be added, the schema just
20+
specifies the minimum contract.
21+
22+
- The position schema does not explicitly include identifiers in the `id` section, as there
23+
is not a common standard for such identifiers. Applications can, however, populate
24+
this part of the contract with custom identifiers if so desired.
25+
26+
## Type
27+
28+
`fdc3.position`
29+
30+
## Schema
31+
32+
https://fdc3.finos.org/schemas/next/position.schema.json
33+
34+
## Details
35+
36+
| Property | Type | Required | Example Value |
37+
|--------------|------------|----------|------------------------------------|
38+
| `type` | string | Yes | `'fdc3.position'` |
39+
| `id` | object | No | `{ positionId: '6475' }` |
40+
| `name` | string | No | `'My Apple shares'` |
41+
| `holding` | number | Yes | `2000000` |
42+
| `instrument` | Instrument | Yes | `{ type: 'fdc3.instrument', ... }` |
43+
44+
## Example
45+
46+
```js
47+
const position = {
48+
type: 'fdc3.position',
49+
instrument: {
50+
type: 'fdc3.instrument'
51+
id: {
52+
ticker: 'AAPL'
53+
}
54+
},
55+
holding: 2000000
56+
}
57+
58+
fdc3.raiseIntent('ViewChart', position)
59+
```
60+
61+
## See Also
62+
63+
Other Types
64+
- [Instrument](Instrument)
65+
- [Portfolio](Portfolio)
66+
67+
Intents
68+
- [ViewAnalysis](../../intents/ref/ViewAnalysis)
69+
- [ViewChart](../../intents/ref/ViewChart)
70+
- [ViewNews](../../intents/ref/ViewNews)
71+
72+
FINOS Financial Objects
73+
- [Position](https://fo.finos.org/docs/objects/position)

0 commit comments

Comments
 (0)