# 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](/v1/tools/json-schema-errors-format/versions/1.0.0) 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:

```json
{
  "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:

```json
{
  "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](/docs#connect)), then call `execute` with:

```json
{
  "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)

```sh
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](/v1/tools/json-schema-errors-format/versions/1.0.0).

### CLI

```sh
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/](/clients/cli/).

## Related tools

- [JSON schema instance locate](/tools/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](/tools/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](/tools/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](/tools/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](/tools/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](/tools/json-schema-additional-find): Find every member a JSON Schema 2020-12 "additionalProperties": false forbids, with the member's JSON Pointer.