Home

MatchAPI Documentation

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

A MatchAPI dictionary describes API messages, fields, data types, components, repeating groups, references, variants, documentation, and change information so that people and tools can understand an API consistently.

This Wiki reflects the latest documentation synced from the main branch of the MatchAPI schema repository. For documentation matching an older schema release, browse the corresponding repository tag and read:

docs/wiki/

The Wiki is explanatory documentation. The official JSON Schema remains the normative source for schema validation.

Recommended reading paths

If you received a MatchAPI dictionary

Start here:

1. Getting Started
2. User Guide
3. References and Keys
4. Examples
5. Validation

This path explains how to read a dictionary, find messages, follow references, and understand fields and data types.

If you are building a tool that reads MatchAPI

Start here:

1. Consumer Guide
2. References and Keys
3. Validation
4. Core Concepts
5. Examples

This path focuses on parsing, indexing, key handling, reference resolution, semantic validation, and round-tripping.

If you are publishing a MatchAPI dictionary

Start here:

1. Publisher Guide
2. Validation
3. References and Keys
4. Versioning and Compatibility
5. Licensing and Attribution

This path focuses on producing dictionaries that are valid, consistent, safe to publish, and easy for consumers to use.

Start here

• Getting Started – first steps for developers receiving a MatchAPI dictionary.
• User Guide – practical tour of the document structure and main modeling patterns.
• Core Concepts – concise explanation of the main concepts in MatchAPI Core.
• References and Keys – how identity, uniqueness, defaults, and reference resolution work.
• Examples – small valid examples showing common modeling patterns.

Implementation guidance

• Consumer Guide – guidance for tools that read MatchAPI dictionaries.
• Publisher Guide – guidance for organisations publishing dictionaries.
• Validation – schema validation and semantic consistency checks.

Project guidance

• Versioning and Compatibility – schema versions, dictionary versions, protocol versions, and compatibility impact.
• Licensing and Attribution – licensing, attribution, branding, and compliance language.
• FAQ – common questions from prospective adopters and implementers.

What MatchAPI describes

A MatchAPI dictionary can describe:

• messages;
• fields;
• data types;
• components;
• repeating groups;
• enum values;
• message direction;
• field presence in each context;
• content ordering and alternatives;
• variants;
• categories and sections;
• documentation;
• additional data;
• change logs.

The format is intended to be protocol-neutral. It can be used for FIX-style APIs, proprietary protocols, JSON-based APIs, binary APIs, and other financial messaging interfaces.

What to validate

A dictionary should first validate against the official JSON Schema. Production use should also apply semantic checks, including:

• primary key uniqueness;
• alternate key uniqueness;
• reference resolution;
• enum value consistency;
• variant consistency;
• group cardinality;
• change log and compatibility review.

See Validation for details.

Key point for new users

MatchAPI separates definitions from references.

For example, a field is defined once in content.fields. A message then references that field from its content and specifies how the field is used in that message.

This separation allows a dictionary to describe reusable API elements without duplicating the same definitions across every message.