Skip to content

Getting Started

Jump to bottom
Francesco Lo Conte edited this page May 31, 2026 · 2 revisions

Getting Started

This page explains how to read a MatchAPI dictionary for the first time.

It is written for users who have received a MatchAPI file from an exchange, trading venue, broker, bank, vendor, or internal API team and need to understand what it describes.

What a MatchAPI dictionary is

A MatchAPI dictionary is a machine-readable description of a messaging API.

It describes:

  • messages that can be sent or received;
  • fields used by those messages;
  • data types used by fields;
  • reusable components;
  • repeating groups;
  • enum/code values;
  • variants of messages or elements;
  • documentation, classification, and change history.

A MatchAPI dictionary is not just a list of messages. It is a structured model. Definitions are usually declared once and then referenced from other definitions.

For example:

data type -> field -> message

A message does not normally repeat the full definition of every field. Instead, it references field definitions.

The top-level structure

A typical MatchAPI dictionary has this shape:

{
  "$schema": "https://matchapi.org/schema/matchapi-core-1.0.0.json",
  "name": "Example API",
  "version": "1.0",
  "protocolVersion": "1.0",
  "metadata": {
    "publisher": "Example Exchange",
    "description": "Example trading API dictionary"
  },
  "keys": {
  },
  "content": {
    "dataTypes": [],
    "fields": [],
    "components": [],
    "groups": [],
    "messages": []
  },
  "classifiers": {
    "variants": [],
    "categories": [],
    "sections": []
  }
}

Only some properties are mandatory. A small dictionary may omit metadata, keys, and classifiers.

The most important section is content.

Where to start

When opening a dictionary, read it in this order:

  1. Top-level name and version

    • name
    • version
    • protocolVersion
    • metadata.publisher
    • metadata.description

  2. Keys

    • Check whether the dictionary defines explicit identity rules in keys.
    • If keys is omitted, default keys apply.

  3. Data types

    • These describe primitive, derived, enum, array, composite, or bitset types.

  4. Fields

    • These define named API fields and refer to data types.

  5. Components and groups

    • These define reusable structures.

  6. Messages

    • These define the actual messages exposed by the API.

A minimal example

This is a very small MatchAPI dictionary:

{
  "$schema": "https://matchapi.org/schema/matchapi-core-1.0.0.json",
  "name": "Simple Order API",
  "version": "1.0",
  "content": {
    "dataTypes": [
      {
        "name": "String",
        "type": "primitive"
      }
    ],
    "fields": [
      {
        "name": "ClOrdID",
        "typeRef": {
          "name": "String"
        }
      }
    ],
    "messages": [
      {
        "name": "NewOrderSingle",
        "msgType": "D",
        "direction": "in",
        "content": [
          {
            "refType": "field",
            "refKey": {
              "name": "ClOrdID"
            },
            "presence": "required"
          }
        ]
      }
    ]
  }
}

This dictionary says:

  • the API is called Simple Order API;
  • it contains a primitive data type called String;
  • it contains a field called ClOrdID;
  • ClOrdID uses the String data type;
  • the API contains an inbound message called NewOrderSingle;
  • NewOrderSingle has message type D;
  • NewOrderSingle requires the ClOrdID field.

Following a field from a message

Suppose you see this inside a message:

{
  "refType": "field",
  "refKey": {
    "name": "ClOrdID"
  },
  "presence": "required"
}

Read it as:

This message contains a required field called ClOrdID.

Then find the field definition in content.fields:

{
  "name": "ClOrdID",
  "typeRef": {
    "name": "String"
  }
}

Read it as:

ClOrdID is a field whose data type is String.

Then find the data type definition in content.dataTypes:

{
  "name": "String",
  "type": "primitive"
}

Read it as:

String is a primitive data type.

The complete interpretation is:

NewOrderSingle contains a required ClOrdID field, and ClOrdID is a String.

Definitions and references

A key concept in MatchAPI is the difference between a definition and a reference.

A definition declares an API element.

Example field definition:

{
  "name": "Symbol",
  "typeRef": {
    "name": "String"
  }
}

A reference places an existing definition inside another element.

Example field reference inside a message:

{
  "refType": "field",
  "refKey": {
    "name": "Symbol"
  },
  "presence": "required"
}

The field definition says what Symbol is.

The field reference says how Symbol is used in this specific message.

This matters because the same field can appear in multiple messages with different presence rules.

Required and optional fields

In messages, components, and groups, child elements have a presence property.

Common values include:

Presence Meaning
required The child element must be present.
optional The child element may be present.
conditionallyRequired The child element is required only under specific conditions described elsewhere.
forbidden The child element must not be present in this context.
ignored The child element may appear but is not semantically processed in this context.
constant The child element has a fixed value.

If presence is omitted on a child reference, it defaults to optional.

Message direction

A message can have a direction property:

Direction Meaning from the API's point of view
in Message sent by the client to the API.
out Message sent by the API to the client.
both Message may be used in both directions.

Example:

{
  "name": "NewOrderSingle",
  "msgType": "D",
  "direction": "in",
  "content": []
}

This describes a message sent into the API.

Components

A component is a reusable set of child elements.

Example:

{
  "name": "Instrument",
  "content": [
    {
      "refType": "field",
      "refKey": {
        "name": "Symbol"
      },
      "presence": "required"
    },
    {
      "refType": "field",
      "refKey": {
        "name": "SecurityID"
      },
      "presence": "optional"
    }
  ]
}

A message can include the component:

{
  "refType": "component",
  "refKey": {
    "name": "Instrument"
  },
  "presence": "required"
}

Read this as:

The message contains the Instrument component.

Then read the component definition to understand which fields the component contains.

Groups

A group describes a repeating structure.

Example:

{
  "name": "PartyGroup",
  "headerRef": {
    "name": "NoPartyIDs"
  },
  "minInstances": 0,
  "content": [
    {
      "refType": "field",
      "refKey": {
        "name": "PartyID"
      },
      "presence": "required"
    },
    {
      "refType": "field",
      "refKey": {
        "name": "PartyRole"
      },
      "presence": "required"
    }
  ]
}

Read it as:

PartyGroup is a repeating group. The number of entries is indicated by NoPartyIDs. Each group instance contains PartyID and PartyRole.

A message can reference the group:

{
  "refType": "group",
  "refKey": {
    "name": "PartyGroup"
  },
  "presence": "optional",
  "minInstances": 0
}

Data types

Data types define how field values are represented.

MatchAPI supports these data type categories:

Type Meaning
primitive Basic type, such as string, integer, decimal, Boolean, or timestamp.
derived Type derived from another data type.
enum Type with an explicit list of allowed values.
array Ordered or unordered collection of values of another type.
composite Structured type with member elements.
bitset Type encoded as individual bits or bit ranges.

Example enum data type:

{
  "name": "Side",
  "type": "enum",
  "valuesTypeRef": {
    "name": "String"
  },
  "values": [
    {
      "name": "Buy",
      "value": "1"
    },
    {
      "name": "Sell",
      "value": "2"
    }
  ]
}

This says that Side is an enum encoded as a string, with values Buy and Sell.

Keys and identity

A MatchAPI dictionary must let consumers uniquely identify elements.

If the dictionary does not define explicit keys, the default primary key for most element collections is:

name + variant

If variant is omitted, it defaults to:

base

Therefore this field:

{
  "name": "Symbol",
  "typeRef": {
    "name": "String"
  }
}

has identity:

name = Symbol
variant = base

A reference to this field can be written as:

{
  "name": "Symbol"
}

because variant defaults to base.

If the dictionary explicitly says that fields use id as their primary key, then field references should use id instead.

See References and Keys for the detailed rules.

Variants

A variant represents a different form of the same named element for a particular use case.

Example:

{
  "name": "Price",
  "variant": "base",
  "typeRef": {
    "name": "Decimal"
  }
}
{
  "name": "Price",
  "variant": "display",
  "typeRef": {
    "name": "String"
  }
}

These are two distinct field definitions under the default key rule because their variants differ.

If a reference omits variant, it points to the base variant.

Validation

There are two levels of validation:

  1. JSON Schema validation

    • checks that the file has the correct structure;
    • checks required properties such as name, version, content, and typeRef;
    • checks enumerated property values.

  2. MatchAPI consistency validation

    • checks that references resolve;
    • checks that primary keys are unique;
    • checks that alternate keys are unique;
    • checks that references use the correct key properties.

A dictionary can pass JSON Schema validation and still contain unresolved references or duplicate keys.

See Validation for details.

Practical reading checklist

When reviewing a MatchAPI dictionary, answer these questions:

  • What API does the dictionary describe?
  • Which version of the API does it describe?
  • Who published it?
  • Does it define explicit keys?
  • Where are the messages?
  • Which messages are inbound, outbound, or both?
  • What fields does each message contain?
  • Which fields are required?
  • Which reusable components or groups are referenced?
  • Which data types do fields use?
  • Are enum values documented?
  • Are variants used?
  • Are classifiers used to organize the dictionary?
  • Does the dictionary contain change logs or documentation entries?

Related pages

MatchAPI

Guides

Project

Clone this wiki locally