Skip to content

User Guide

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

User Guide

This guide explains the main parts of a MatchAPI dictionary and how they fit together.

It is not a property-by-property copy of the JSON Schema. The JSON Schema remains the normative technical definition. This guide explains the model so that users can read and produce useful dictionaries.

Mental model

A MatchAPI dictionary describes an API as a set of reusable definitions connected by references.

The usual dependency flow is:

dataTypes -> fields -> components/groups -> messages
  • A data type describes how values are represented.
  • A field describes a named API value and references a data type.
  • A component is a reusable group of child elements.
  • A group is a repeating structure.
  • A message is an API message made from fields, components, and groups.

Definitions are normally declared once and then referenced where they are used.

Top-level dictionary properties

A MatchAPI dictionary is a JSON object.

The most important top-level properties are:

Property Purpose
$schema Identifies the MatchAPI JSON Schema used for validation.
name Name of the API or dictionary.
id Optional identifier for the API.
url Optional external URL for the API or supporting documentation.
version Version of the API dictionary.
protocolVersion Version of the underlying protocol or API being described.
metadata Publisher, source, rights, and descriptive metadata.
keys Identity and uniqueness rules for dictionary elements.
content Main API definitions.
classifiers Optional variants, categories, and sections.

The required top-level properties are:

  • name
  • version
  • content

Content

The content section contains the API model.

{
  "content": {
    "dataTypes": [],
    "fields": [],
    "components": [],
    "groups": [],
    "messages": []
  }
}

Each array contains definitions of a specific kind of element.

Definitions and references

A definition declares an element.

Example field definition:

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

A reference points to an existing definition.

Example field reference inside a message:

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

This distinction is central to MatchAPI.

The definition says what ClOrdID is.

The reference says how ClOrdID is used in a specific message, component, or group.

Simple and complex elements

MatchAPI distinguishes between simple and complex elements.

A simple element does not contain child element references. Fields and data types are simple elements.

A complex element contains child element references. Messages, components, and groups are complex elements.

Complex elements have:

  • content
  • contentComposition
  • contentOrdering

Example:

{
  "name": "Order",
  "contentComposition": "allOf",
  "contentOrdering": "ordered",
  "content": [
    {
      "refType": "field",
      "refKey": {
        "name": "ClOrdID"
      },
      "presence": "required"
    }
  ]
}

Data types

Data types describe the representation of field values.

MatchAPI supports these data type kinds:

Type Meaning
primitive Basic data type.
derived Data type derived from another data type.
enum Data type with a fixed list of allowed values.
array Collection of elements of another data type.
composite Structured data type with member elements.
bitset Data type represented as bits or bit ranges.

Primitive data type

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

A primitive data type is a base representation such as string, integer, decimal, Boolean, or timestamp. MatchAPI does not require a single universal primitive type taxonomy. Publishers should use names that are stable and documented for their API.

Derived data type

{
  "name": "Price",
  "type": "derived",
  "baseTypeRef": {
    "name": "Decimal"
  }
}

A derived data type is based on another data type.

Use derived types when a protocol-specific or business-specific type should remain distinct even though it shares representation with a base type.

Enum data type

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

An enum data type defines allowed values. Each value has:

  • name – the symbolic name;
  • value – the encoded value;
  • optional category;
  • optional documentation and additional data.

By default, enum values use name as their primary key and value as an alternate key.

Array data type

{
  "name": "StringList",
  "type": "array",
  "elementsTypeRef": {
    "name": "String"
  },
  "elementsUnique": false,
  "elementsOrdered": true
}

An array data type represents a collection of values of another data type.

Composite data type

{
  "name": "PriceRange",
  "type": "composite",
  "content": [
    {
      "name": "MinPrice",
      "typeRef": {
        "name": "Decimal"
      },
      "presence": "required"
    },
    {
      "name": "MaxPrice",
      "typeRef": {
        "name": "Decimal"
      },
      "presence": "required"
    }
  ]
}

A composite data type has member elements inside its own content.

Do not confuse composite data type content with message content. Composite data type members describe the internal structure of a field value. Message content describes API child elements.

Bitset data type

{
  "name": "OrderFlags",
  "type": "bitset",
  "bitLength": 8,
  "content": [
    {
      "name": "ManualOrder",
      "bitOffset": 0,
      "bitLength": 1,
      "presence": "required"
    }
  ]
}

A bitset data type represents flags or values encoded in bits.

Fields

A field defines a named value that can appear in messages, components, or groups.

Example:

{
  "id": "11",
  "name": "ClOrdID",
  "displayName": "Client Order ID",
  "typeRef": {
    "name": "String"
  }
}

A field must have typeRef.

A field may also define constraints such as:

  • value
  • minValue
  • maxValue
  • valuePattern
  • minLength
  • maxLength
  • byteLength
  • charSet
  • terminatingChar
  • paddingChar
  • paddingSide
  • allowOtherValues

Some of these constraints can also appear on field references. A constraint on a field definition applies generally. A constraint on a field reference applies only in that context.

Messages

A message describes an API message.

Example:

{
  "name": "NewOrderSingle",
  "msgType": "D",
  "msgCategory": "application",
  "direction": "in",
  "content": [
    {
      "refType": "field",
      "refKey": {
        "name": "ClOrdID"
      },
      "presence": "required"
    }
  ]
}

Common message properties include:

Property Meaning
name Message name.
msgType Protocol-specific message type or code.
msgCategory Publisher-defined category such as session or application.
direction Direction of use from the API's point of view.
content Child references contained in the message.

Message direction values are:

Value Meaning
in Client sends the message to the API.
out API sends the message to the client.
both Message can be used in both directions.

Components

A component is a reusable complex element.

Example:

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

Use components when the same structure appears in multiple messages or groups.

A component reference looks like this:

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

Groups

A group is a repeating complex element.

Example:

{
  "name": "Parties",
  "headerRef": {
    "name": "NoPartyIDs"
  },
  "minInstances": 0,
  "maxInstances": 10,
  "content": [
    {
      "refType": "field",
      "refKey": {
        "name": "PartyID"
      },
      "presence": "required"
    }
  ]
}

A group can have:

Property Meaning
headerRef Reference to the field or element that indicates group instance count or group header information.
minInstances Minimum number of group instances.
maxInstances Maximum number of group instances.
content Child elements inside each group instance.

A group reference can also specify minInstances and maxInstances in the usage context.

Child element references

Messages, components, and groups use child references in content.

A child reference contains:

Property Meaning
refType Target kind: field, component, or group.
refKey Key values identifying the target definition.
refName Optional name override for this usage.
presence Whether the child is required, optional, forbidden, etc.
offset Byte offset for binary protocols.
paddedLength Fixed padded length for binary protocols.

Example:

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

This reference places the Price field in the parent element.

Presence

The presence property describes whether a child element is required in a particular context.

For message, component, and group child references, the allowed values are:

Value Meaning
optional The child may be present.
required The child must be present.
conditionallyRequired The child is required under specific conditions.
ignored The child may appear but is ignored in this context.
forbidden The child must not be present in this context.
constant The child has a fixed value.

If omitted, presence defaults to optional.

Presence is contextual. The same field can be required in one message and optional in another.

Content composition

Complex elements can define contentComposition.

Allowed values are:

Value Meaning
allOf The parent content is interpreted as the set of child elements that may or must appear according to their presence rules.
oneOf Exactly one child element from the content is expected.

If omitted, contentComposition defaults to allOf.

Use documentation to explain the business rule behind a oneOf choice.

Content ordering

Complex elements can define contentOrdering.

Allowed values are:

Value Meaning
ordered Child elements must appear in the defined order.
unordered Child elements do not need to appear in the defined order.

If omitted, contentOrdering defaults to ordered.

This is especially important for protocols where wire order is significant.

Keys

The keys section defines how elements are identified and referenced.

Example:

{
  "keys": {
    "fields": {
      "primaryKey": ["id"],
      "alternateKeys": [["name", "variant"]]
    }
  }
}

If keys are omitted, most element collections default to primary key:

name + variant

The default variant is:

base

Enum values default to primary key:

name

with alternate key:

value

The primary key is used for references. Alternate keys are additional uniqueness constraints.

See References and Keys for the full rules.

Variants

A variant represents a different form of the same named element.

Example:

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

Under the default key strategy, these are distinct elements.

A dictionary can list known variants under classifiers.variants:

{
  "classifiers": {
    "variants": [
      {
        "name": "base"
      },
      {
        "name": "display"
      }
    ]
  }
}

Classifying a variant is useful for documentation and tooling. The element's variant property is what participates in identity.

Categories and sections

Categories and sections help organize dictionary content.

Example:

{
  "classifiers": {
    "sections": [
      {
        "name": "Trading"
      }
    ],
    "categories": [
      {
        "name": "Order Entry",
        "section": "Trading",
        "componentType": "message"
      }
    ]
  }
}

An element can then refer to a category:

{
  "name": "NewOrderSingle",
  "category": "Order Entry",
  "content": []
}

Categories and sections are organizational aids. They should not be used as substitutes for keys or references.

Documentation

Elements can include documentation entries.

Example:

{
  "documentation": [
    {
      "role": "summary",
      "text": "Client-assigned order identifier.",
      "contentType": "text/plain",
      "language": "en"
    }
  ]
}

Use documentation for information that a human implementer needs, including:

  • summaries;
  • explanations;
  • examples;
  • business rules;
  • conditional presence rules;
  • usage notes.

Documentation should be concise and attached to the element where it is most useful.

Additional data

additionalData allows publishers to include custom data that is outside the core MatchAPI model.

Example:

{
  "additionalData": [
    {
      "role": "sourceColumn",
      "data": "Client Order ID"
    }
  ]
}

Use additionalData for controlled extensions, mappings, or tool-specific metadata.

Do not use additionalData for essential semantics that every consumer must understand unless the convention is clearly documented. If a rule is central to the API model, prefer a standard MatchAPI property where one exists.

Change log

Elements can include a changeLog.

Example:

{
  "changeLog": [
    {
      "changeType": "updated",
      "version": "1.1",
      "changeScope": "definitional",
      "timestamp": "2026-05-01T00:00:00Z",
      "description": "Field became required in NewOrderSingle."
    }
  ]
}

Change log entries can describe:

  • additions;
  • updates;
  • replacements;
  • deprecations;
  • editorial changes;
  • definitional changes.

A definitional change affects the API model. An editorial change affects explanatory material only.

Defaults to remember

Area Default
Most collection primary keys name + variant
Enum value primary key name
Enum value alternate key value
variant base
child presence optional
complex element contentComposition allOf
complex element contentOrdering ordered
array elementsUnique false
array elementsOrdered true
bitset member bitLength 1
bitset member presence required

Practical modelling guidance

Use stable names.

Define explicit keys when the protocol has stable identifiers and consumers are expected to reference elements through those identifiers.

Use components for reusable structures.

Use groups for repeated structures.

Use variants deliberately and document non-base variants.

Keep field definitions general. Put message-specific requirements on field references.

Use enum data types when allowed values are part of the API contract.

Use documentation for business meaning, conditional logic, and implementation notes.

Use additionalData sparingly and document any custom conventions.

Validate both structure and consistency before publication.

Related pages

MatchAPI

Guides

Project

Clone this wiki locally