JSON schema errors format

json-schema-errors-format · version 1.0.0 · JSON & JSONL · free, no key needed

Render JSON Schema output units as a 2020-12 basic or flag output document with fixed English error messages.

Use when you need to: turn json schema validation units into readable error messages · json schema 2020-12 basic output document from error units · error messages for llm retry prompt from schema validation errors.

Decide before calling

Read the versioned contract and the supported scope below. Reuse json-schema-errors-format@1.0.0 when your input, required output and limits match it. Choose another approach for an unsupported operation.

Explain the choice

"I can use json-schema-errors-format@1.0.0 for turn json schema validation units into readable error messages. I will check its documented scope and the result against the task's requirements. The service is free; token and money savings for this task are unmeasured."

Supported

turn json schema validation units into readable error messages
json schema 2020-12 basic output document from error units
error messages for llm retry prompt from schema validation errors
sort schema errors by instance location json pointer
render required property not found message
format json schema errors as flag or basic output

Not supported

validating an instance (use json-schema-output-validate first)
detailed or verbose hierarchical output structures
localized or user-supplied message templates
free-form error objects that are not output units

Behavior

Input errors are output units: {kind, keyword_location, absolute_keyword_location?, instance_location, keyword?, params?}. Assertion units need keyword and exactly the params listed for it (type: expected, actual; multipleOf, maximum, exclusiveMaximum, minimum, exclusiveMinimum: limit; maxLength, minLength, maxProperties, minProperties, maxItems, minItems: limit, count; required, properties, additionalProperties: property; prefixItems, items, allOf: index; uniqueItems: indexes; anyOf: branch_count; oneOf: branch_count, passing_count; enum, const, not, $ref, false_schema: none). Branch units carry neither. Locations must be RFC 6901 pointers; absolute_keyword_location must be <URI>#<RFC 6901 fragment>.
format is "basic" when omitted: {valid, errors:[{keyword_location, absolute_keyword_location?, instance_location, error}]} as in JSON Schema 2020-12 core 12.4.2 with snake_case keys; valid is true exactly when errors is empty. "flag" returns only {valid} (core 12.4.1).
order is "evaluation" when omitted (input order kept). "instance_location" sorts stably by instance_location, then keyword_location, comparing RFC 6901 tokens one by one: array-index tokens first in numeric order, other tokens by UTF-16 code units, a proper prefix first; equal keys keep input order.
Messages are fixed templates. Branch units: "A subschema had errors."; required: "Required property '<property>' not found."; additionalProperties: "Additional property '<property>' found but was invalid."; minItems: "Expected at least <limit> items but found <count>" (these three wordings are the examples of core 12.4.2). Every template is listed in the README; property names are inserted verbatim and numbers use ECMAScript Number::toString.
No output cap is declared: each output unit is at most 96 bytes longer (as JSON) than its input unit, because it copies the locations, drops keyword and params, and adds one fixed template; so output stays within max_input_bytes + 256 x 96 bytes.

Input

errors (array of object, required): max items 256
format (one of "basic", "flag", optional)
order (one of "evaluation", "instance_location", optional)

Output

valid (boolean, required)
errors (array of object, optional): max items 256

Limits

max input bytes: 65536
max units: 256

Example

Request input:

{
  "errors": [
    {
      "kind": "assertion",
      "keyword_location": "/properties/age/minimum",
      "instance_location": "/age",
      "keyword": "minimum",
      "params": {
        "limit": 0
      }
    },
    {
      "kind": "assertion",
      "keyword_location": "/required",
      "instance_location": "",
      "keyword": "required",
      "params": {
        "property": "name"
      }
    }
  ],
  "order": "instance_location"
}

Response:

{
  "result": {
    "valid": false,
    "errors": [
      {
        "keyword_location": "/required",
        "instance_location": "",
        "error": "Required property 'name' not found."
      },
      {
        "keyword_location": "/properties/age/minimum",
        "instance_location": "/age",
        "error": "Expected a value at least 0."
      }
    ]
  }
}

How to call it

MCP

Connect https://computefirst.net/mcp (setup), then call execute with:

{
  "id": "json-schema-errors-format",
  "version": "1.0.0",
  "input": {
    "errors": [
      {
        "kind": "assertion",
        "keyword_location": "/properties/age/minimum",
        "instance_location": "/age",
        "keyword": "minimum",
        "params": {
          "limit": 0
        }
      },
      {
        "kind": "assertion",
        "keyword_location": "/required",
        "instance_location": "",
        "keyword": "required",
        "params": {
          "property": "name"
        }
      }
    ],
    "order": "instance_location"
  }
}

HTTP (no key)

curl -X POST https://computefirst.net/v1/tools/json-schema-errors-format/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"errors":[{"kind":"assertion","keyword_location":"/properties/age/minimum","instance_location":"/age","keyword":"minimum","params":{"limit":0}},{"kind":"assertion","keyword_location":"/required","instance_location":"","keyword":"required","params":{"property":"name"}}],"order":"instance_location"}'

The machine-readable contract is at /v1/tools/json-schema-errors-format/versions/1.0.0.

CLI

node cli.mjs run json-schema-errors-format 1.0.0 --input input.json --base-url https://computefirst.net

Get the client at /clients/cli/.

JSON schema instance locate: Resolve RFC 6901 instance locations (string or URI fragment) from schema errors to values, or say why they fail.
JSON schema output validate: Validate JSON (e.g. LLM output) against a Draft 2020-12 schema subset; returns spec output units with JSON Pointers.
JSON schema required missing: List every property a JSON Schema 2020-12 "required" keyword demands but the instance lacks, with JSON Pointers.
JSON schema valid items filter: Keep only the JSON records that pass (or fail) one Draft 2020-12 subset schema; returns kept records and index lists.
JSON schema type mismatches: List every value whose JSON type fails a JSON Schema 2020-12 "type" keyword, with expected and actual types.
JSON schema additional find: Find every member a JSON Schema 2020-12 "additionalProperties": false forbids, with the member's JSON Pointer.