finos · rikoe · Mar 31, 2020 · Mar 31, 2020 · Mar 31, 2020 · Mar 31, 2020
diff --git a/docs/appd-discovery.md → docs/app-directory/discovery.md b/docs/appd-discovery.md → docs/app-directory/discovery.md
@@ -1,5 +1,5 @@
 ---
-id: appd-discovery
+id: discovery
 sidebar_label: App Directory Discovery
 title: App Directory Discovery
 hide_title: true

diff --git a/docs/appd-intro.md → docs/app-directory/overview.md b/docs/appd-intro.md → docs/app-directory/overview.md
@@ -1,5 +1,5 @@
 ---
-id: appd-intro
+id: overview
 sidebar_label: App Directory Overview
 title: App Directory Overview
 hide_title: true
@@ -17,8 +17,8 @@ The FDC3 App Directory provides trusted identity for financial desktop apps. Thi
 
 ## Sections to review
 
-- [Application Directory Discovery](appd-discovery.md) describes how to resolve the location of the Application Directory using an application identifier.
-- [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.
-- [API specification](appd-spec.md) is the interface definition required to support a compatible application directory.
+- [Application Directory Discovery](discovery.md) describes how to resolve the location of the Application Directory using an application identifier.
+- [Application Directory Usage](usasge.md) provides a simple view on how application directories can be used.  This also includes links to a reference implementation.
+- [Application Directory specification](spec.md) is the interface definition required to support a compatible application directory.
 
 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].
diff --git a/docs/appd-spec.md → docs/app-directory/spec.md b/docs/appd-spec.md → docs/app-directory/spec.md
@@ -1,5 +1,5 @@
 ---
-id: appd-spec
+id: spec
 sidebar_label: App Directory Specification
 title: App Directory Specification
 ---

diff --git a/docs/appd-use.md → docs/app-directory/usage.md b/docs/appd-use.md → docs/app-directory/usage.md
@@ -1,11 +1,11 @@
 ---
-id: appd-use
-sidebar_label: App Directory Use
-title: App Directory Use
+id: usage
+sidebar_label: App Directory Usage
+title: App Directory Usage
 hide_title: true
 ---
 
-# App Directory Use
+# App Directory Usage
 
 An application directory (AppD) provides information about an application's
 identifiers, intents that provide contexts, and location of metadata providing

diff --git a/docs/apps-and-platforms.md b/docs/apps-and-platforms.md
diff --git a/docs/context/ref/Contact.md b/docs/context/ref/Contact.md
@@ -18,7 +18,7 @@ https://fdc3.finos.org/schemas/next/contact.schema.json
 
 ## Details
 
-| Property    | Type    | Required | Value             |
+| Property    | Type    | Required | Example Value     |
 |-------------|---------|----------|-------------------|
 | `type`      | string  | Yes      | `'fdc3.contact'`  |
 | `name`      | string  | No       | `'Jane Doe'`      |

diff --git a/docs/context/ref/ContactList.md b/docs/context/ref/ContactList.md
@@ -8,6 +8,12 @@ hide_title: true
 
 A collection of contacts, e.g. for chatting to or calling multiple contacts.
 
+Notes:
+
+- The contact list schema does not explicitly include identifiers in the `id` section, as there
+is not a common standard for such identifiers. Applications can, however, populate
+this part of the contract with custom identifiers if so desired.
+
 ## Type
 
 `fdc3.contactList`
@@ -18,9 +24,10 @@ https://fdc3.finos.org/schemas/next/contactList.schema.json
 
 ## Details
 
-| Property    | Type      | Required | Value                  |
+| Property    | Type      | Required | Example Value          |
 |-------------|-----------|----------|------------------------|
 | `type`      | string    | Yes      | `'fdc3.contactList'`   |
+| `id`        | object    | No       | `{ customId: '5576' }` |
 | `name`      | string    | No       | `'My address book'`    |
 | `contacts`  | Contact[] | Yes      | `[contact1, contact2]` |
 

diff --git a/docs/context/ref/Context.md b/docs/context/ref/Context.md
@@ -6,4 +6,73 @@ hide_title: true
 ---
 # `Context`
 
-_TO BE COMPLETED_
+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.
+
+The key element of FDC3 context types is their mandatory `type` property, which is used to identify what type of data the
+object represents, and what shape it has.
+
+Notes:
+
+- The FDC3 context type, and all derived types, define the minimum set of fields a context data object of a particular type
+can be expected to have, but this can always be extended with custom fields as appropriate.
+
+## Type
+
+`fdc3.context`
+
+## Schema
+
+https://fdc3.finos.org/schemas/next/context.schema.json
+
+## Details
+
+| Property    | Type    | Required | Example Value                    |
+|-------------|---------|----------|----------------------------------|
+| `type`      | string  | Yes      | `'fdc3.context'`                 |
+| `name`      | string  | No       | `'Display name'`                 |
+| `id`        | object  | No       | `{ id: 'value', 'id': 'value' }` |
+
+### `type` (required)
+
+The type property is the only _required_ part of the FDC3 context data schema. 
+The FDC3 [API](../../api/overview) relies on the `type` property being present to route shared context data appropriately.
+
+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.
+
+Standardised FDC3 context types have well-known `type` properties prefixed with the `fdc3` namespace, e.g. `fdc3.instrument`. 
+For non-standard types, e.g. those defined and used by a particular organisation, the convention is to prefix them with an
+organization-specific namespace, e.g. `blackrock.fund`.
+
+See the [Context Data Specification](../../context/spec) for more information about context data types.
+
+### `name` (optional)
+
+Context data objects may include a name property that can be used for more information, or display purposes. Some
+derived types may require the name object as mandatory, depending on use case.
+
+### `id` (optional)
+
+Context data objects may include a set of equivalent key-value pairs that can be used to help applications
+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.
+
+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.
+
+## See Also
+
+FDC3 Specifications
+- [Context Data](../../context/spec)
+- [Intents](../../intents/spec)
+- [API](../../api/spec)
+- [App Directory](../../app-directory/spec)
+
+FDC3 Context Types
+- [Contact](Contact)
+- [ContactList](ContactList)
+- [Country](Country)
+- [Instrument](Instrument)
+- [InstrumentList](InstrumentList)
+- [Organization](Organization)
+- [Position](Position)
+- [Portfolio](Portfolio)
diff --git a/docs/context/ref/Country.md b/docs/context/ref/Country.md
@@ -26,7 +26,7 @@ https://fdc3.finos.org/schemas/next/country.schema.json
 
 ## Details
 
-| Property         | Type    | Required | Value                |
+| Property         | Type    | Required | Example Value        |
 |------------------|---------|----------|----------------------|
 | `type`           | string  | Yes      | `'fdc3.country'`     |
 | `name`           | string  | No       | `'Sweden'`           |

diff --git a/docs/context/ref/Instrument.md b/docs/context/ref/Instrument.md
@@ -32,7 +32,7 @@ https://fdc3.finos.org/schemas/next/instrument.schema.json
 
 ## Details
 
-| Property    | Type    | Required | Value               |
+| Property    | Type    | Required | Example Value       |
 |-------------|---------|----------|---------------------|
 | `type`      | string  | Yes      | `'fdc3.instrument'` |
 | `name`      | string  | No       | `'Microsoft'`       |

diff --git a/docs/context/ref/InstrumentList.md b/docs/context/ref/InstrumentList.md
@@ -10,6 +10,12 @@ A collection of instruments. Use this type for use cases that require not just a
 
 When holding information for each instrument is required, it is recommended to use the [Portfolio](Portfolio) type, though.
 
+Notes:
+
+- The instrument list schema does not explicitly include identifiers in the `id` section, as there
+is not a common standard for such identifiers. Applications can, however, populate
+this part of the contract with custom identifiers if so desired.
+
 ## Type
 
 `fdc3.instrumentList`
@@ -20,10 +26,11 @@ https://fdc3.finos.org/schemas/next/instrumentList.schema.json
 
 ## Details
 
-| Property      | Type         | Required | Value                          |
+| Property      | Type         | Required | Example Value                  |
 |---------------|--------------|----------|--------------------------------|
 | `type`        | string       | Yes      | `'fdc3.instrumentList'`        |
 | `name`        | string       | No       | `'Interesting instruments...'` |
+| `id`          | object       | No       | `{ customId: '5464' }`         |
 | `instruments` | Instrument[] | Yes      | `[instrument1, instrument2]`   |
 
 ## Example

diff --git a/docs/context/ref/Organization.md b/docs/context/ref/Organization.md
@@ -23,7 +23,7 @@ https://fdc3.finos.org/schemas/next/organization.schema.json
 
 ## Details
 
-| Property    | Type    | Required | Value                     |
+| Property    | Type    | Required | Example Value             |
 |-------------|---------|----------|---------------------------|
 | `type`      | string  | Yes      | `'fdc3.organization'`     |
 | `name`      | string  | No       | `'Cargill, Incorporated'` |

diff --git a/docs/context/ref/Portfolio.md b/docs/context/ref/Portfolio.md
@@ -6,4 +6,93 @@ hide_title: true
 ---
 # `Portfolio`
 
-_TO BE COMPLETED_
+A financial portfolio made up of muliple positions (holdings) in several instruments. Contrast this
+with e.g. the [InstrumentList](InstrumentList) type, which is just a list of instruments.
+
+This is a good example of how types can be composed and extended with extra properties to define more complex types.
+
+The [Portfolio](Portfolio) type consists of an array of [Position](Position) types, each of which
+refers to a single [Instrument](Instrument) and a holding amount for that instrument.
+
+Notes:
+
+- Like all other FDC3 context types, extra properties for the portfolio can be added, the schema just 
+specifies the minimum contract.
+
+- The portfolio schema does not explicitly include identifiers in the `id` section, as there
+is not a common standard for such identifiers. Applications can, however, populate
+this part of the contract with custom identifiers if so desired.
+
+## Type
+
+`fdc3.portfolio`
+
+## Schema
+
+https://fdc3.finos.org/schemas/next/portfolio.schema.json
+
+## Details
+
+| Property     | Type       | Required | Example Value             |
+|--------------|------------|----------|---------------------------|
+| `type`       | string     | Yes      | `'fdc3.portfolio'`        |
+| `id`         | object     | No       | `{ portfolioId: '7381' }` |
+| `name`       | string     | No       | `'My share portfolio'`    |
+| `positions`  | Position[] | Yes      | `[position1, position2]`  |
+
+## Example
+
+```js
+const position = {
+    type: 'fdc3.portfolio',
+    positions: [
+        {
+            type: 'fdc3.position',
+            instrument: {
+                type: 'fdc3.instrument'
+                id: {
+                    ticker: 'AAPL'
+                }
+            },
+            holding: 2000000
+        },
+        {
+            type: 'fdc3.position',
+            instrument: {
+                type: 'fdc3.instrument'
+                id: {
+                    ticker: 'MSFT'
+                }
+            },
+            holding: 1500000
+        },
+        {
+            type: 'fdc3.position',
+            instrument: {
+                type: 'fdc3.instrument'
+                id: {
+                    ticker: 'IBM'
+                }
+            },
+            holding: 3000000
+        }
+    ]
+}
+
+fdc3.raiseIntent('ViewAnalysis', portfolio)
+```
+
+## See Also
+
+Other Types
+- [Instrument](Instrument)
+- [InstrumentList](InstrumentList)
+- [Position](Position)
+
+Intents
+- [ViewAnalysis](../../intents/ref/ViewAnalysis)
+- [ViewChart](../../intents/ref/ViewChart)
+- [ViewNews](../../intents/ref/ViewNews)
+
+FINOS Financial Objects
+- [Position](https://fo.finos.org/docs/objects/portfolio)
diff --git a/docs/context/ref/Position.md b/docs/context/ref/Position.md
@@ -6,4 +6,68 @@ hide_title: true
 ---
 # `Position`
 
-_TO BE COMPLETED_
+A financial position made up of an instrument and a holding in that instrument. This type is a good
+example of how new context types can be composed from existing types.
+
+In this case, the instrument and the holding amount for that instrument are required values.
+
+The [Position](Position) type goes hand-in-hand with the [Portfolio](Portfolio) type, which represents
+multiple holdings in a combination of instruments.
+
+Notes:
+
+- Like all other FDC3 context types, extra properties for the position can be added, the schema just 
+specifies the minimum contract.
+
+- The position schema does not explicitly include identifiers in the `id` section, as there
+is not a common standard for such identifiers. Applications can, however, populate
+this part of the contract with custom identifiers if so desired.
+
+## Type
+
+`fdc3.position`
+
+## Schema
+
+https://fdc3.finos.org/schemas/next/position.schema.json
+
+## Details
+
+| Property     | Type       | Required | Example Value                      |
+|--------------|------------|----------|------------------------------------|
+| `type`       | string     | Yes      | `'fdc3.position'`                  |
+| `id`         | object     | No       | `{ positionId: '6475' }`           |
+| `name`       | string     | No       | `'My Apple shares'`                |
+| `holding`    | number     | Yes      | `2000000`                          |
+| `instrument` | Instrument | Yes      | `{ type: 'fdc3.instrument', ... }` |
+
+## Example
+
+```js
+const position = {
+    type: 'fdc3.position',
+    instrument: {
+        type: 'fdc3.instrument'
+        id: {
+            ticker: 'AAPL'
+        }
+    },
+    holding: 2000000
+}
+
+fdc3.raiseIntent('ViewChart', position)
+```
+
+## See Also
+
+Other Types
+- [Instrument](Instrument)
+- [Portfolio](Portfolio)
+
+Intents
+- [ViewAnalysis](../../intents/ref/ViewAnalysis)
+- [ViewChart](../../intents/ref/ViewChart)
+- [ViewNews](../../intents/ref/ViewNews)
+
+FINOS Financial Objects
+- [Position](https://fo.finos.org/docs/objects/position)