JSON schema instance locate

json-schema-instance-locate · version 1.0.0 · JSON & JSONL · free, no key needed

Resolve RFC 6901 instance locations (string or URI fragment) from schema errors to values, or say why they fail.

Use when you need to: show the offending values at json schema error instance locations · resolve instance_location pointers from validation errors · convert json pointer to uri fragment identifier and resolve it.

Decide before calling

Read the versioned contract and the supported scope below. Reuse json-schema-instance-locate@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-instance-locate@1.0.0 for show the offending values at json schema error instance locations. 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

show the offending values at json schema error instance locations
resolve instance_location pointers from validation errors
convert json pointer to uri fragment identifier and resolve it
resolve percent-encoded json pointer uri fragment against a document
why does this json pointer not resolve in the llm output
look up several rfc 6901 pointers without failing on missing paths

Not supported

relative JSON Pointers
JSONPath or JMESPath queries
modifying the instance (patch, add, remove)
resolving pointers inside a schema through $ref

Behavior

Each location is a JSON Pointer in JSON string form ("" or starting with "/", RFC 6901 section 5) or in URI fragment form (starting with "#", section 6). Fragment form is percent-decoded as UTF-8; characters outside the RFC 3986 fragment rule must be percent-encoded. A malformed location (bad ~ escape, missing leading "/", bad percent-encoding, invalid UTF-8) is invalid_input.
Each result has location (as given), pointer (string form), uri_fragment (UTF-8 percent-encoding of every character outside unreserved, sub-delims, ":", "@", "/", "?", uppercase hex) and found. When found, value is a copy of the referenced JSON value (-0 becomes 0).
When not found, reason is one of missing_member, index_out_of_range, invalid_array_index (leading zeros or non-digits on an array), end_of_array_token ("-", which names the nonexistent element after the last per RFC 6901 section 4) or not_a_container, and matched_pointer is the longest prefix that did resolve.
Results keep the order of locations; duplicates are resolved again. Object member names compare by exact code units (no Unicode normalization).
More than 64 locations, input over 65536 bytes, an instance nested deeper than 32 levels, or output over 262144 bytes is limit_exceeded.

Input

instance (any JSON value, required): The JSON value the locations point into (for example the validated LLM output)
locations (array of string, required): max items 64

Output

results (array of object, required): max items 64

Limits

max input bytes: 65536
max locations: 64
max json depth: 32
max output bytes: 262144

Example

Request input:

{
  "instance": {
    "items": [
      {
        "price": "12"
      }
    ],
    "a/b": 1
  },
  "locations": [
    "/items/0/price",
    "#/a~1b",
    "/items/1"
  ]
}

Response:

{
  "result": {
    "results": [
      {
        "location": "/items/0/price",
        "pointer": "/items/0/price",
        "uri_fragment": "#/items/0/price",
        "found": true,
        "value": "12"
      },
      {
        "location": "#/a~1b",
        "pointer": "/a~1b",
        "uri_fragment": "#/a~1b",
        "found": true,
        "value": 1
      },
      {
        "location": "/items/1",
        "pointer": "/items/1",
        "uri_fragment": "#/items/1",
        "found": false,
        "reason": "index_out_of_range",
        "matched_pointer": "/items"
      }
    ]
  }
}

How to call it

MCP

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

{
  "id": "json-schema-instance-locate",
  "version": "1.0.0",
  "input": {
    "instance": {
      "items": [
        {
          "price": "12"
        }
      ],
      "a/b": 1
    },
    "locations": [
      "/items/0/price",
      "#/a~1b",
      "/items/1"
    ]
  }
}

HTTP (no key)

curl -X POST https://computefirst.net/v1/tools/json-schema-instance-locate/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"instance":{"items":[{"price":"12"}],"a/b":1},"locations":["/items/0/price","#/a~1b","/items/1"]}'

The machine-readable contract is at /v1/tools/json-schema-instance-locate/versions/1.0.0.

CLI

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

Get the client at /clients/cli/.

JSON schema errors format: Render JSON Schema output units as a 2020-12 basic or flag output document with fixed English error messages.
JSON schema required missing: List every property a JSON Schema 2020-12 "required" keyword demands but the instance lacks, with JSON Pointers.
JSON schema batch validate: Validate many JSON records against one Draft 2020-12 subset schema; per-record validity, error pointers, counts.
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 candidate list: Find and rank JSON object/array candidates in prose and Markdown fences (quotes and lists too) with exact raw spans.
JSON fence extract: List Markdown fenced code blocks (CommonMark 0.31.2) with exact spans, unwrapped content and an RFC 8259 JSON check.