Validation

Validation

Validation checks whether a MatchAPI dictionary is well formed and usable.

There are two different levels of validation:

1. JSON Schema validation
2. MatchAPI consistency validation

Both are important. A dictionary can pass JSON Schema validation and still be unusable because references do not resolve or keys are not unique.

JSON Schema validation

JSON Schema validation checks whether the document follows the structure defined by the MatchAPI schema.

It can check things such as:

• required top-level properties are present;
• required element properties are present;
• property values have the expected JSON type;
• enumerated properties use allowed values;
• unknown properties are not used where the schema disallows them.

For example, a MatchAPI dictionary must have:

{
  "name": "Example API",
  "version": "1.0",
  "content": {}
}

A field definition must have a typeRef:

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

A message child reference must have both refType and refKey:

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

JSON Schema validation is the first validation step. It is not the last one.

MatchAPI consistency validation

MatchAPI consistency validation checks whether the dictionary is coherent as an API model.

It should check things such as:

• all references resolve to existing definitions;
• each reference resolves to exactly one definition;
• primary keys are unique;
• alternate keys are unique;
• references use the correct key properties;
• enum values are unique under their key strategy;
• variants are used consistently;
• complex elements do not contain invalid or ambiguous child references.

These checks require understanding the meaning of MatchAPI keys and references. They cannot be fully performed by generic JSON Schema validation.

Structural error example

This field is structurally invalid because it has no typeRef:

{
  "name": "ClOrdID"
}

A JSON Schema validator should reject it because field definitions require typeRef.

Invalid enum example

This child reference is structurally invalid because presence has an unsupported value:

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

The valid values are:

• optional
• required
• conditionallyRequired
• ignored
• forbidden
• constant

A JSON Schema validator should reject mandatory.

Unresolved reference example

This dictionary can be structurally valid but semantically invalid:

{
  "$schema": "https://matchapi.org/schema/matchapi-core-1.0.0.json",
  "name": "Unresolved Reference Example",
  "version": "1.0",
  "content": {
    "dataTypes": [
      {
        "name": "String",
        "type": "primitive"
      }
    ],
    "fields": [
      {
        "name": "ClOrdID",
        "typeRef": {
          "name": "String"
        }
      }
    ],
    "messages": [
      {
        "name": "Order",
        "content": [
          {
            "refType": "field",
            "refKey": {
              "name": "MissingField"
            }
          }
        ]
      }
    ]
  }
}

The message references MissingField, but no such field is defined.

A generic JSON Schema validator may accept this file because the shape of the reference is valid. A MatchAPI consistency validator should reject it because the reference cannot be resolved.

Duplicate key example

If no explicit key is defined for fields, the default field primary key is:

name + variant

The default variant is:

base

Therefore, this dictionary contains duplicate fields:

{
  "$schema": "https://matchapi.org/schema/matchapi-core-1.0.0.json",
  "name": "Duplicate Field Example",
  "version": "1.0",
  "content": {
    "dataTypes": [
      {
        "name": "String",
        "type": "primitive"
      }
    ],
    "fields": [
      {
        "name": "Symbol",
        "typeRef": {
          "name": "String"
        }
      },
      {
        "name": "Symbol",
        "typeRef": {
          "name": "String"
        }
      }
    ],
    "messages": []
  }
}

Both fields have identity:

name = Symbol
variant = base

A MatchAPI consistency validator should report a duplicate primary key.

Reference/key mismatch example

This dictionary says that fields are identified by id:

{
  "keys": {
    "fields": {
      "primaryKey": ["id"]
    }
  }
}

A field reference should therefore use id:

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

This reference is incomplete under the declared key strategy:

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

A MatchAPI consistency validator should report that the reference does not provide the primary key properties required for field resolution.

Validation order for consumers

A consumer should generally validate in this order:

1. Parse the file as JSON.

2. Validate against the MatchAPI JSON Schema.

3. Load the key strategy.

   • Read the top-level keys section.
   • Apply default keys where a key is omitted.

4. Build indexes for each collection.

   • messages
   • components
   • groups
   • fields
   • dataTypes
   • enum values inside enum data types

5. Validate uniqueness of primary keys.

6. Validate uniqueness of alternate keys.

7. Resolve all references.

8. Validate reference-specific rules.

   • refType: "field" must resolve to a field.
   • refType: "component" must resolve to a component.
   • refType: "group" must resolve to a group.
   • typeRef, baseTypeRef, valuesTypeRef, and elementsTypeRef should resolve to data types.

9. Report all errors with enough path information to locate the issue.

Validation order for publishers

A publisher should check at least the following before releasing a dictionary:

• the file is valid JSON;
• the file passes JSON Schema validation;
• all required metadata is present for publication;
• explicit keys are defined where needed;
• all primary keys are unique;
• all alternate keys are unique;
• all references resolve;
• references use the correct key properties;
• all non-base variants are intentional;
• enum values are unique under the enum value key strategy;
• documentation is present for non-obvious messages, groups, and enum values;
• additionalData does not contain private or tool-internal information that should not be published;
• change logs are present for material changes.

What JSON Schema validation can catch

JSON Schema validation can catch:

• missing required top-level properties;
• invalid property names where additional properties are disallowed;
• invalid enum values;
• invalid JSON types;
• missing typeRef on field definitions;
• missing content on complex elements;
• missing refType or refKey on child references;
• malformed UUID values where UUID format is enforced;
• malformed regular expressions where regex format is enforced.

What JSON Schema validation cannot fully catch

JSON Schema validation cannot fully catch:

• unresolved references;
• references that resolve to multiple targets;
• duplicate primary keys;
• duplicate alternate keys;
• reference/key mismatches;
• inconsistent use of variants;
• invalid business rules described only in documentation;
• incomplete protocol semantics;
• whether a dictionary is complete enough for implementation;
• whether additionalData follows a publisher-specific convention.

Error reporting guidance

Validation errors should be specific.

Poor error:

Invalid reference.

Better error:

messages[0].content[2].refKey references field { "name": "MissingField", "variant": "base" }, but no matching field exists in content.fields.

Poor error:

Duplicate field.

Better error:

content.fields[4] and content.fields[7] have the same primary key for fields: name = Symbol, variant = base.

Good errors should identify:

• the JSON path of the invalid item;
• the applicable key strategy;
• the reference or key values involved;
• the target collection searched;
• the conflicting or missing element.

Warning vs error

Some validation findings should be errors. Others may be warnings.

Likely errors:

• invalid JSON;
• JSON Schema validation failure;
• unresolved reference;
• duplicate primary key;
• reference missing primary key properties;
• reference resolving to more than one target.

Likely warnings:

• missing documentation;
• missing metadata description;
• unused data type;
• unused field;
• unused component;
• unused classifier;
• additionalData role not recognized by the consuming tool;
• non-base variant not listed in classifiers.variants.

A publisher may choose stricter rules for public release.

Related pages

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