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

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

Response:

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

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

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

### CLI

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

## Related tools

- [JSON schema errors format](/tools/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](/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 batch validate](/tools/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](/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 candidate list](/tools/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](/tools/json-fence-extract): List Markdown fenced code blocks (CommonMark 0.31.2) with exact spans, unwrapped content and an RFC 8259 JSON check.