Version: Next

Context Data (next)

To interoperate, apps need to exchange commonly recognized context structures that can indicate topic with any number of identifiers or mappings to different systems. FDC3 Context Data defines a standard for passing common identifiers and data, encoded in JSON, between apps to create a seamless workflow. FDC3 Context Data is not a symbology solution and is not specifically focused on modeling financial objects. The focus is on providing a standard JSON payload structure that can be used to establish a lowest common denominator for interoperability.

Context objects are used when raising intents and when broadcasting context to other applications.

There are two main use cases for exchanging context data:

Transmitting reference data between applications. The source application will send as many known identifiers as possible, and the target application will try to match the entity based on the identifiers. It may then choose to map to its own internal domain representation for rendering purposes.

An example of this is sending an instrument or contact, when only an ISIN or email is required to reference the same data in another application.
Transferring information between applications. The source application may have data required to compose a workflow with another application, e.g. a list of contacts that have been selected, or a complex object representing an RFQ request.

In many such cases there aren't any sensible reference identifiers that can be shared, it is instead the data itself being transferred.

Assumptions

Context data objects are identified and routed according to their type, which is unique.
Any names, identifiers or extra properties are optional.
More complex objects can be composed from simpler objects by defining a new type, e.g a position from an instrument and a holding amount.
If multiple pieces of data need to be sent, an embedded array can be used, identified as a collection type, e.g. "contactList" or "portfolio". This allows for additional metadata and data relationships to be expressed.
There needs to be a way to reference or look up the structure of well-known context types, e.g. from a directory.

Other Standards

FDC3 recognizes that there are other object definitions for providing context between applications. Most, if not all of these definitions though are platform-specific. FDC3, as a rule, sets out to be platform-agnostic and focused on creating bridges between the various walled gardens on the financial desktop.

Context Schemas

FDC3 Context data is primarily defined in JSON, using JSON Schema to provide formal definitions for each standardized context type. The JSON Schema definitions should be considered the source of truth for the structure and fields of each context type.

However, FDC3 also provides language-specific type definitions (API bindings) that translate the JSON definitions into idiomatic types for each supported language. These bindings may differ from the raw JSON representation in order to provide a more natural developer experience in that language. Applications interacting with FDC3 APIs in a particular language should use the appropriate language binding, while the JSON Schema remains the canonical definition of the wire format exchanged between applications and Desktop Agents.

JSON as the Wire Format

The Desktop Agent Communication Protocol (DACP) specifies that context objects are exchanged as JSON-compatible structures. When context is transmitted between applications and Desktop Agents (e.g. via postMessage on a MessagePort), the data is subject to the browser's Structured Clone algorithm, which handles serialisation and deserialisation transparently. Applications and Desktop Agent implementations SHOULD pass context objects directly to postMessage without additional serialisation (e.g. without calling JSON.stringify()).

note

The Convert classes generated by quicktype from the JSON Schema files are provided as a convenience for validation and type-safe parsing of JSON strings (e.g. when reading context from a file or REST API). They are not intended for use when sending or receiving DACP messages over MessagePort, where the Structured Clone algorithm handles serialisation.

Language-Specific Bindings

Each language binding translates JSON Schema types into idiomatic equivalents for that language. The following table summarises key differences:

JSON Schema Type	TypeScript/JavaScript	.NET	Go
`string` (ISO 8601 date-time)	`string`	`string`	`string`
`string`	`string`	`string`	`string`
`number`	`number`	`double`	`float64`
`integer`	`number`	`int`	`int`
`boolean`	`boolean`	`bool`	`bool`
`object` (map)	`Record<string, T>`	`IDictionary<string, T>`	`map[string]T`
`array`	`Array<T>`	`IEnumerable<T>`	`[]T`

note

Date and time fields in context objects are always string-encoded in both the JSON wire format and in language bindings. They are not converted to native Date objects (in JavaScript) or DateTime (in .NET) at the context type level. Applications may parse these strings into native date types if needed, but the context objects themselves carry string values conforming to ISO 8601-1:2019. See Other Field Type Conventions for details.

Packages and Source Code

Language-specific context type definitions are available in the following packages:

Language	Package	Source
TypeScript/JavaScript	`@finos/fdc3-context`	`packages/fdc3-context`
.NET	Included in the .NET FDC3 implementation	See .NET language binding
Go	Not yet available	—

The TypeScript definitions distributed in the @finos/fdc3-context NPM module are generated from the JSON Schema files using quicktype. Both documentation for fields defined (in the form of a title and description entry for each field) and examples SHOULD be included in JSON Schema definitions for Context types to ensure that the schema file can serve as a single source of truth, and that code generated from the schema files can also include that documentation.

The Context Interface

The Context interface defines the basic contract or "shape" for all data exchanged by FDC3 operations. As such, it is not meant to be used on its own, but is imported by more specific type definitions (standardized or custom) to provide the structure and properties shared by all FDC3 context data types.

The Context interface can be summarized as:

Having a unique type identifier, used for routing.
Optionally providing a name.
Optionally providing a map of equivalent identifiers.
Any other properties or metadata.

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. 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.

Hence, the Context interface can be represented in TypeScript as:

interface Context {
    type: string;
    name?: string;
    id?: {
        [x:string]: string;
    },
    [x: string]: any;
}

or in JSON Schema as:

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id": "https://fdc3.finos.org/schemas/next/context/context.schema.json",
    "type": "object",
    "title": "Context",
    "description": "The `fdc3.context` type defines the basic contract for all data exchanged by FDC3 operations.",
    "properties": {
        "type": {
            "type": "string"
        },
        "name": {
            "type": "string"
        },
        "id": {
            "type": "object",
            "unevaluatedProperties": {
                "type": "string"
            }
        }
    },
    "additionalProperties": true,
    "required": [
        "type"
    ]
}

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: https://fdc3.finos.org/schemas/next/context/context.schema.json.

`type`

The type property is the only required part of the FDC3 context data schema. The FDC3 API relies on the type property being present to route shared context data appropriately.

FDC3 Intents also register the context data types they support in an FDC3 App Directory, used for intent discovery and routing.

Standardized 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 organization, the convention is to prefix them with an organization-specific namespace, e.g. blackrock.fund.

Namespacing

All well-known types at FDC3 level are prefixed with fdc3. For private type definitions, or type definitions issued by other organizations, different namespaces MUST be used, e.g. blackrock.fund, etc.

`name`

Context data objects may include an optional 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`

Context data objects may include a set of equivalent key-value pairs in the id property 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 choose to require at least one identifier.

Where an identifier is the name of an existing standard, external to FDC3, it is represented in all caps. For example: FIGI, PERMID, CUSIP, ISO-2. When an identifier is a more general concept, it is represented in all lower case. For example: ticker, name, geocode, email.

Identifier values SHOULD always be of type string.

All standard identifier names are reserved names. Applications may use their own identifiers ad hoc. For example:

"id": {
    "CUSIP":"037833100",
    "foo":"bar"
}

The identifier "foo" is proprietary, an application that can use it is free to do so. However, since multiple applications may want to use the "foo" name and may use it to mean different things, there is a need for applications to ensure that their identifiers use naming conventions that will avoid collision. The recommended approach here is to prefix the identifier name with a namespace. For example:

"id": {
    "CUSIP":"037833100",
    "com.company.foo": "000C7F-E"
}

Avoid union types / composition of primitive types

Both Typescript and JSON Schema allow for a type of polymorphism in types and interfaces that is hard to represent in other languages: allowing the type of a variable to be a 'union' of other, unrelated types. E.g.: in TypeScript

type Example = SomeOtherType | YetAnotherType;

Similar constructs are allowed in JSON Schema by combining or composing schemas using the anyOf or oneOf keywords to specify that a value can take the form defined in one-or-more or one-of-several sub-schemas.

"recipients": {
    "title": "Email Recipients",
    "description": "One or more recipients for the email.",
    "oneOf": [
        {
            "$ref": "contact.schema.json#"
        },
        {
            "$ref": "contactList.schema.json#"
        }
    ]
}

However, other languages can be less flexible. In most languages, polymorphism of object types is possible via the implementation and/or extension of an interface (for example all context types are derived from the Context schema, which can be modelled as an interface). However, this approach is not possible if one of the types in the union is a primitive, meaning it's not a class and can't be modified to implement an interface, e.g.:

type Example2 = SomeOtherType | number;

Hence, to ensure that FDC3 context objects are implementable in other languages context schemas MUST NOT use anyOf/oneOf compositions of primitive types in JSON schema (and, hence, unions of primitive types in TypeScript) and SHOULD avoid compositions of Object types unless a concept that can be defined as an interface (such as Context) is available.

Other Field Type Conventions

This Standard defines a number of conventions for the fields of context types that all context objects SHOULD adhere to in order to reduce or prevent competing conventions from being established in both standardized types and proprietary types created by app developers.

Times

Fields representing a point in time SHOULD be string encoded according to ISO 8601-1:2019 with a timezone indicator included, e.g.:

Time in UTC: "2022-03-30T15:44:44Z"
Also time in UTC: "2022-03-30T15:44:44+00:00"
Same time in EDT: "2022-03-30T11:44:44-04:00"

Times MAY be expressed with millisecond precision, e.g.:

"2022-03-30T11:44:44.123-04:00"
"2022-03-30T11:44:44.123Z"

Parsing in JavaScript:

let aDate = new Date("2022-03-30T11:44:44.123-04:00")

Dates

Fields representing a point in time SHOULD be string encoded using the YYYY-MM-DD date format from ISO 8601-1:2019.

E.g. "2022-03-30"

Parsing in JavaScript:

let aDate = new Date("2022-03-30")

Country codes

Fields representing a country SHOULD be string encoded using the Alpha-2-codes from ISO 3166-1 and field name COUNTRY_ISOALPHA2. The Alpha-3-codes from ISO 3166-1 MAY be used in addition to the Alpha-2-code with the field name COUNTRY_ISOALPHA3.

E.g. "COUNTRY_ISOALPHA2": "GB"

Currency codes

Fields representing a currency SHOULD be string encoded using the Alphabetic code from ISO 4217 with the field name CURRENCY_ISOCODE.

E.g. "CURRENCY_ISOCODE": "GBP"

note

ISO 4217 only includes major currency codes, conversions to minor currencies is the responsibility of the consuming system (where required).

Context Metadata

FDC3 Context is intended to provide a common data format that is used for messaging between applications. Context object definitions should avoid including fields that represent metadata.

Metadata such as the originating application, timestamps, digital signatures, or trace identifiers are important for routing, auditing, and linking related interactions, but they do not form part of the business data that the Context represents. Mixing metadata with core data can lead to ambiguity, increase complexity for developers, and reduce interoperability between implementations.

To maintain clarity and consistency, FDC3 separates metadata from Context objects. This ensures that:

Context remains focused on the business data being shared, making it easier to define, validate, and reuse across different workflows.
Metadata can evolve independently to support advanced features such as provenance, security, and correlation without impacting the core data model.
Handlers receive both Context and ContextMetadata explicitly, allowing applications to process data and metadata according to their respective concerns.

This separation provides a cleaner architecture, improves interoperability, and supports future enhancements without breaking existing Context definitions.

For more details on ContextMetadata please see the FDC3 API overview and ContextMetadata reference.

Context Data Standard Compliance

An FDC3 Standard compliant application that supports the use of context data MUST:

Ensure that any FDC3-defined standard context types used meet the interface defined for that type of context data.
Where an app is intended to receive context from fdc3.open calls, use the fdc3.addContextListener API call to set up appropriate handlers.
Where App or Private channels are supported, use the Channel.addContextListener API call to set up appropriate handlers.

An FDC3 Standard compliant application that supports the use of context data SHOULD:

Prefer FDC3-defined standard context types over proprietary contexts, where a suitable FDC3-defined standard context type is available.
Ensure that any proprietary context data types defined follow any the recommended namespacing and field type conventions in the specification.
Where an app is intended to receive context from fdc3.open calls, use the fdc3.addContextListener API call to set up appropriate handlers within 15 seconds of the application launch (the minimum timeout Desktop Agents are required to provide) in order to be widely compatible with Desktop Agent implementations.

An FDC3 Standard compliant application that supports the use of context data MAY:

Define proprietary context data types to support use cases not currently supported via FDC3-defined standard context types.

For more details on FDC3 Standards compliance (including the versioning, deprecation and experimental features policies) please see the FDC3 Compliance page.

Standard Context Types

The following are standard FDC3 context types:

The following are @experimental types, which are in the process of being defined:

Examples

The below examples show how the base context data interface can be used to define specific context data objects.

Contact

{
    "type": "fdc3.contact",
    "name": "John Smith",
    "id":{
        "email": "john.smith@company.com",
    }
}

Email

{
  "type": "fdc3.email",
  "recipients": {
    "type": "fdc3.contact",
    "name": "Jane Doe",
    "id": {
      "email": "jane.doe@example.com"
    }
  },
  "subject": "The information you requested",
  "textBody": "Blah, blah, blah ..."
}

Instrument

{
    "type" : "fdc3.instrument",
    "name" : "Apple",
    "id" :
    {
        "ticker" : "aapl",
        "ISIN" : "US0378331005",
        "CUSIP" : "037833100",
        "FIGI" : "BBG000B9XRY4",
    }
}

TypeScript definition

The Instrument type is derived from the Context type (note that the name becomes a required field, the type is fixed and optional id subfields are defined):

interface Instrument extends Context {
    type: 'fdc3.instrument',
    name: string;
    id: {
        ticker?: string;
        ISIN?: string;
        CUSIP?: string;
    }
}

e.g. as a JSON payload:

{
    "type" : "fdc3.instrument",
    "name" : "Apple",
    "id" :
    {
        "ticker" : "aapl",
        "ISIN" : "US0378331005",
        "CUSIP" : "037833100"
    },
}

Assumptions​

Other Standards​

Context Schemas​

JSON as the Wire Format​

Language-Specific Bindings​

Packages and Source Code​

The Context Interface​

type​

Namespacing​

name​

id​

Avoid union types / composition of primitive types​

Other Field Type Conventions​

Times​

Dates​

Country codes​

Currency codes​

Context Metadata​

Context Data Standard Compliance​

Standard Context Types​

Examples​

Contact​

Email​

Instrument​

TypeScript definition​

Assumptions

Other Standards

Context Schemas

JSON as the Wire Format

Language-Specific Bindings

Packages and Source Code

The Context Interface

`type`

Namespacing

`name`

`id`

Avoid union types / composition of primitive types

Other Field Type Conventions

Times

Dates

Country codes

Currency codes

Context Metadata

Context Data Standard Compliance

Standard Context Types

Examples

Contact

Email

Instrument

TypeScript definition