FAQ

FAQ

What is MatchAPI?

MatchAPI is a JSON Schema-based format for describing financial messaging APIs in a structured, machine-readable way.

A MatchAPI dictionary can describe messages, fields, data types, components, repeating groups, references between those elements, documentation, variants, categories, and version/change information.

Is MatchAPI tied to one protocol?

No. MatchAPI is intended to be protocol-neutral.

It can describe FIX-style protocols, proprietary binary protocols, JSON-based APIs, and other financial messaging interfaces.

Some properties are useful for FIX-like APIs, such as msgType or field id, but the model is not limited to FIX.

Is a MatchAPI dictionary a replacement for human API documentation?

Not necessarily.

A MatchAPI dictionary is a structured description of the API. It can support documentation generation and automated tooling, but publishers may still provide human API guides, business rules, onboarding notes, certification scripts, or release notes.

The best use is to make the API structure machine-readable while keeping explanatory documentation available where needed.

Where are the messages?

Messages are listed under:

content.messages

Each message may contain:

• name;
• msgType;
• msgCategory;
• direction;
• content.

The message content contains references to fields, components, and groups.

Where are the fields?

Field definitions are listed under:

content.fields

A field definition describes the field itself and must reference a data type using typeRef.

A message does not usually redefine the full field. Instead, it contains a field reference in its content.

What is the difference between a field definition and a field reference?

A field definition describes the field once.

Example:

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

A field reference places that field inside a message, component, or group.

Example:

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

The definition says what the field is. The reference says how the field is used in that parent context.

How do I find all fields used by a message?

1. Find the message in content.messages.
2. Read its content array.
3. For each child reference:
   • if refType is field, resolve refKey against content.fields;
   • if refType is component, resolve the component and read its content;
   • if refType is group, resolve the group and read its content.
4. Apply the applicable key rules when resolving each reference.

Do not assume a field reference always uses name. It must use the primary key configured for fields.

How do I know whether a field is required?

Look at the field reference in the parent message, component, or group.

The relevant property is:

"presence"

For child references, allowed values are:

optional, required, conditionallyRequired, ignored, forbidden, constant

If presence is omitted, it defaults to optional.

A field can be required in one message and optional in another because presence is contextual.

How do I know the data type of a field?

Read the field definition in content.fields, then resolve its typeRef against content.dataTypes.

Example:

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

Under the default data type key strategy, this means the Symbol field uses the data type with:

name=String; variant=base

What is a component?

A component is a reusable complex element.

It contains child references to fields, groups, or other components. Components are used when the same structure appears in multiple messages or other structures.

What is a group?

A group is a repeating structure.

A group may have a headerRef, instance constraints such as minInstances and maxInstances, and child references in content.

A group definition describes the repeating structure. A group reference places the group inside a message, component, or another group.

What is an enum data type?

An enum data type defines a set of allowed values.

Example:

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

By default, enum values are identified by name, and value is an alternate uniqueness constraint.

What does allowOtherValues mean?

If a field uses an enum data type, allowOtherValues indicates whether values outside the listed enum values may be accepted.

If omitted, the default is false.

Use this carefully. If a publisher allows non-enumerated values, the dictionary should explain when and why.

What are keys?

Keys define how elements are uniquely identified and referenced.

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

For example, if fields are keyed by id, a field reference should use id:

{
  "refType": "field",
  "refKey": { "id": "55" }
}

If fields use the default key strategy, a field reference usually uses name and, if needed, variant:

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

What happens if the keys section is missing?

Default key rules still apply.

For messages, components, groups, fields, and data types, the default primary key is:

["name", "variant"]

For enum values, the default primary key is:

["name"]

and the default alternate key is:

["value"]

A missing keys section does not mean the dictionary has no identity rules.

Should I use name, id, or uuid as a key?

Use name when names are stable and unique.

Use id when the protocol has stable identifiers, such as FIX tags, message codes, or venue-defined field identifiers.

Use uuid when the publisher needs a stable identity independent of both name and protocol id.

Use variant together with another property when the same logical element can have different forms.

Can two fields have the same name?

It depends on the field key strategy.

Under the default key strategy, fields are keyed by name + variant. This means two fields can have the same name only if they have different variant values.

Example:

{ "name": "Price", "variant": "equities", "typeRef": { "name": "Decimal" } }

{ "name": "Price", "variant": "derivatives", "typeRef": { "name": "Decimal" } }

If the field primary key is id, two fields cannot have the same id, even if their names differ.

What does variant do?

variant distinguishes different forms of the same logical element.

If omitted, it defaults to:

"base"

Under the default key strategy, name + variant identifies most elements. This means variant is part of identity, not just a label.

What is the difference between category, classifiers.categories, and classifiers.sections?

An element's category property assigns that element to a category.

classifiers.categories can define those categories more formally.

classifiers.sections can group categories into broader sections.

These properties are mainly for navigation, documentation, and user interfaces. They do not replace keys or references.

What is additionalData for?

additionalData is a schema-defined extension mechanism for publisher-specific or implementation-specific information.

It should be used for controlled extra data, such as external mappings or tool-specific values.

It should not be used to add arbitrary undocumented structure where normal MatchAPI properties should be used instead.

Can I add custom properties directly to objects?

Usually no.

Most schema-defined objects do not allow arbitrary additional properties. Use additionalData, where available, for implementation-specific information.

Is JSON Schema validation enough?

No.

JSON Schema validation checks document structure. Production use should also check semantic consistency, including:

• reference resolution;
• primary key uniqueness;
• alternate key uniqueness;
• enum value consistency;
• variant consistency;
• group cardinality;
• publisher-specific rules.

Why does JSON Schema validation not catch unresolved references?

JSON Schema checks the shape of the JSON document. It does not build MatchAPI-specific indexes or know whether a reference object points to an existing element under the configured key strategy.

For example, JSON Schema can check that refKey is an object. It does not prove that refKey resolves to an existing field.

Can MatchAPI describe JSON APIs?

Yes. MatchAPI is protocol-neutral and can describe JSON-based financial messaging APIs.

The appropriate modeling approach depends on the API. For example, messages may represent request/response payloads or event types, fields may represent payload properties, and data types may describe primitive, enum, array, or composite structures.

Can MatchAPI describe binary APIs?

Yes. MatchAPI includes properties useful for binary protocols, such as byte length, padding, byte offsets, bitsets, and endianness.

Whether the dictionary is sufficient for complete binary encoding or decoding depends on how fully the publisher models the protocol.

Can MatchAPI describe FIX APIs?

Yes. MatchAPI can describe FIX-style APIs.

Common mappings include:

• field tag -> field id;
• message type -> msgType;
• FIX component -> component;
• repeating group -> group;
• enum values -> enum data type values.

The publisher should still define the key strategy clearly. For example, fields may be keyed by tag id rather than by name.

How should I compare two versions of a dictionary?

Compare using the effective key strategy, not array positions.

At minimum, compare:

• key definitions;
• data types;
• fields;
• messages, components, and groups;
• child references;
• presence values;
• enum values;
• group cardinality;
• variants;
• change logs.

See Versioning and Compatibility.

Where are older docs?

The Wiki shows the latest synced documentation. Older documentation is available in repository tags under:

docs/wiki/

For an older schema release, use the documentation from the corresponding repository tag rather than assuming the latest wiki applies.

Related pages

• Getting Started
• User Guide
• References and Keys
• Validation
• Examples