# JSON candidate list

`json-candidate-list` · version 1.0.0 · JSON & JSONL · free, no key needed

Find and rank JSON object/array candidates in prose and Markdown fences (quotes and lists too) with exact raw spans.

**Use when you need to: find json objects embedded in an llm answer · pick the best json candidate from model output · locate json snippets in markdown and prose with offsets.**

## Decide before calling

Read the [versioned contract](/v1/tools/json-candidate-list/versions/1.0.0) and the supported scope below. Reuse `json-candidate-list@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-candidate-list@1.0.0` for find json objects embedded in an llm answer. 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

- find json objects embedded in an llm answer
- pick the best json candidate from model output
- locate json snippets in markdown and prose with offsets
- rank possible json payloads in a chat reply
- which part of this text is the json
- find truncated json in a response
- scan text for curly brace or square bracket json blocks

## Not supported

- returning scalar JSON values (strings, numbers, true/false/null) as candidates
- scanning code fences tagged with a non-JSON language such as python
- guessing intent or semantic correctness of the JSON (only syntax validity is checked)
- non-conservative repairs such as quoting keys or converting single quotes

## Behavior

- The text is parsed as CommonMark 0.31.2 blocks (same rules as json-fence-extract). Scanned regions: fenced code whose language is json/jsonc/json5 (source json_fence), fenced code without a language (untagged_fence), indented code (indented_code), and paragraphs, headings and HTML blocks (prose). Fences with any other language are skipped. Each region is its leaf text with container markers (block quote markers, list item indentation) removed and lines joined by \n.
- Within a region, a single left-to-right pass starts a candidate at each '{' or '[' not already consumed and matches brackets with JSON string awareness. It is complete when the first bracket closes. It is incomplete with incomplete_reason mismatched_closer (a closer that does not match), unterminated_string (a line ends inside a string, or the text ends inside one) or unclosed (the text ends); incomplete text drops trailing JSON whitespace. Scanning resumes after the candidate, after the mismatched closer or after the line ending.
- start and end are raw UTF-16 offsets in the input of the first and one-past-last character of text; start_line and end_line are 1-based. contiguous is true when the raw slice [start, end) equals text (false when container markers or indentation were removed inside it).
- valid_json applies RFC 8259 strictly to text; json_error is null or {code, offset} into text. repair (optional, default false) adds a repair object per candidate: all three json-candidate-repair rules applied to text, with the repaired text, its RFC 8259 validity and the rules that changed it; otherwise repair is null.
- Ranking (fixed, total): tier 0 valid_json, tier 1 valid only after repair (repair true), tier 2 the rest; then source json_fence, untagged_fence, indented_code, prose; then complete before incomplete; then longer text (UTF-16 units) first; then smaller start first. rank is 1-based.
- max_results (optional, default 10, 1 to 100) caps the returned candidates; candidate_count is the number found and truncated is true when candidates were cut.

## Input

- `text` (string, required): max length 131072
- `repair` (boolean, optional)
- `max_results` (integer, optional): min 1; max 100

## Output

- `candidate_count` (integer, required): min 0
- `truncated` (boolean, required)
- `candidates` (array of object, required): max items 100

## Limits

- max text bytes: 131072
- max results: 100
- max container depth: 64

## Example

Request input:

```json
{
  "text": "Sure! {\"a\": 1} is what you need."
}
```

Response:

```json
{
  "result": {
    "candidates": [
      {
        "rank": 1,
        "source": "prose",
        "fence_index": null,
        "start": 6,
        "end": 14,
        "start_line": 1,
        "end_line": 1,
        "text": "{\"a\": 1}",
        "contiguous": true,
        "top_level": "object",
        "complete": true,
        "incomplete_reason": null,
        "valid_json": true,
        "json_error": null,
        "repair": null
      }
    ],
    "candidate_count": 1,
    "truncated": false
  }
}
```

## How to call it

### MCP

Connect `https://computefirst.net/mcp` ([setup](/docs#connect)), then call `execute` with:

```json
{
  "id": "json-candidate-list",
  "version": "1.0.0",
  "input": {
    "text": "Sure! {\"a\": 1} is what you need."
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/json-candidate-list/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"text":"Sure! {\"a\": 1} is what you need."}'
```

The machine-readable contract is at [/v1/tools/json-candidate-list/versions/1.0.0](/v1/tools/json-candidate-list/versions/1.0.0).

### CLI

```sh
node cli.mjs run json-candidate-list 1.0.0 --input input.json --base-url https://computefirst.net
```

Get the client at [/clients/cli/](/clients/cli/).

## Related tools

- [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.
- [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 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 repair diagnose](/tools/json-repair-diagnose): Classify JSON text as valid, repairable or unrepairable and locate each lexical defect and refusal by line and column.
- [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.