MatchAPI is a schema designed for defining financial messaging APIs across a variety of protocol encodings. It provides a structured and extensible model for describing message formats, fields, data types, and hierarchical relationships between message elements. The specification aims to support interoperability, extensibility, and tooling across different environments where financial messaging is critical.
This document defines the structure and semantics of all elements available in the MatchAPI schema. It is intended to be a comprehensive reference for users who wish to define, consume, or transform API message definitions using MatchAPI.
name: Name of the API.id: Identifier (UUID or URL).url: External reference for further info.version: API version.protocolVersion: Underlying protocol version.endianness: Either big or little (for binary encodings).{
"name": "Example Trading API",
"id": "123e4567-e89b-12d3-a456-426614174000",
"version": "1.0.0",
"protocolVersion": "FIX.4.4",
"endianness": "big"
}
message)Messages represent API operations (requests, responses, events). Defined as complex elements containing fields, groups, or components.
msgType: Application-level type.msgCategory: Logical grouping (session, application, etc.).direction: in, out, or both.content: List of child elements (fieldRef, groupRef, componentRef).contentComposition: allOf or oneOf.contentOrdering: ordered or unordered.{
"name": "Logon",
"msgType": "A",
"msgCategory": "session",
"direction": "in",
"content": [
{ "refType": "field", "refKey": { "name": "EncryptMethod" } },
{ "refType": "field", "refKey": { "name": "HeartBtInt" } }
]
}
component)Reusable groups of fields or other elements.
msgType, etc.){
"name": "StandardHeader",
"content": [
{ "refType": "field", "refKey": { "name": "BeginString" } },
{ "refType": "field", "refKey": { "name": "BodyLength" } }
]
}
group)Defines a repeating structure.
complexElementheaderRef: Points to the field/component that indicates group repetition count.minInstances, maxInstances{
"name": "NoPartyIDs",
"headerRef": { "name": "NoPartyIDs" },
"content": [
{ "refType": "field", "refKey": { "name": "PartyID" } },
{ "refType": "field", "refKey": { "name": "PartyRole" } }
]
}
field)Basic atomic values, typically associated with a dataType.
typeRef: Required reference to a dataType.allowOtherValues: Boolean.valuePattern: Regex.terminatingChar, paddingChar, paddingSideminValue, maxValue, minLength, maxLengthcharSet, lengthHeaderRef, byteLengthvalue: Default or constant.{
"name": "ClOrdID",
"typeRef": { "name": "String" },
"minLength": 1,
"maxLength": 20
}
Data types describe the format and constraints for field values.
dataType (Primitive){
"name": "String",
"type": "primitive",
"charSet": "ASCII"
}
derivedDataType{
"name": "UserID",
"type": "derived",
"baseTypeRef": { "name": "String" },
"maxLength": 64
}
enumDataType{
"name": "Side",
"type": "enum",
"baseTypeRef": { "name": "char" },
"values": [
{ "name": "Buy", "value": "1" },
{ "name": "Sell", "value": "2" }
]
}
arrayDataType{
"name": "StringList",
"type": "array",
"baseTypeRef": { "name": "String" },
"elementsOrdered": true,
"elementsUnique": false
}
compositeDataType{
"name": "SessionInfo",
"type": "composite",
"content": [
{
"name": "SessionID",
"typeRef": { "name": "String" },
"presence": "required"
},
{
"name": "Timeout",
"typeRef": { "name": "int" },
"presence": "optional"
}
]
}
bitsetDataType{
"name": "Flags",
"type": "bitset",
"bitLength": 8,
"content": [
{
"name": "UrgentFlag",
"bitOffset": 0,
"bitLength": 1,
"presence": "required"
},
{
"name": "RetryCount",
"bitOffset": 1,
"bitLength": 3,
"presence": "optional"
}
]
}
Used to define variations of an element (e.g. for different environments).
{
"name": "NewOrder",
"variant": "production"
}
Group elements logically under a common domain.
{
"name": "OrderEntry",
"componentType": "message",
"includeFile": "components"
}
Group categories into documentation or logical blocks.
{
"name": "Trading",
"description": "Messages related to trade entry and execution."
}
{
"fields": {
"primaryKey": ["name"],
"alternateKeys": [["id"]]
},
"dataTypes": {
"primaryKey": ["name"],
"alternateKeys": [["id"]]
}
}
{
"documentation": [
{
"role": "summary",
"text": "This message initiates the session."
}
]
}
{
"additionalData": [
{
"role": "implementationNote",
"data": "Used only by internal systems."
}
]
}
{
"changeLog": [
{
"changeType": "added",
"version": "1.1.0",
"description": "Initial release of the NewOrder message"
}
]
}
MatchAPI does not prescribe a runtime behavior but rather focuses on:
MatchAPI is designed to evolve. Future versions may introduce:
This specification is open for community feedback and contribution.