> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Structured data and diffs (@json, @diff)

> @json reads JSON and YAML by path, filters arrays, infers a payload's shape and validates with line/column; @diff compares files, text and directories and applies unified patches with dry-run.

Two tools for the data an agent handles between reads and edits. `@json` answers questions about a payload — the 2 MB API response `@http` saved to disk, a Helm values file — without reading it whole. `@diff` shows what changed and applies a patch only when every context line matches.

***

## `@json`

```text theme={"system"}
<tool_call name="@json" args='{"cmd":"schema","args":{"file":"resp.json"}}' />
<tool_call name="@json" args='{"cmd":"get","args":{"file":"resp.json","path":"data.items[3].name"}}' />
<tool_call name="@json" args='{"cmd":"query","args":{"file":"resp.json","path":"data.items","where":"status=failed && name~^web","select":["id","name"],"limit":20}}' />
<tool_call name="@json" args='{"cmd":"validate","args":{"text":"{\"a\": 1,}"}}' />
```

| Verb | Arguments | What it does |
| - | - | - |
| `get` | `file\|text`, `path` | the value at a dotted/bracket path: `a.b[0].c`, `[-1]`, `*` fans out over arrays and objects; a miss names the segment and lists the keys available there |
| `keys` | `file\|text`, `path?` | keys one level down with a type summary (`object{n}`, `array[n]`, `string(len)`) |
| `query` | `file\|text`, `path?`, `where`, `select?`, `limit?` | filters an array of objects: `field=value`, `field!=value`, `field~regex`, several joined with `&&`; dotted fields; `limit` default 20, max 200 |
| `schema` | `file\|text`, `depth?` (3, max 8) | the inferred shape of an unknown payload, with how often each key appears across sampled elements |
| `validate` | `file\|text` | parse errors with 1-based line and column and a snippet; trailing data is an error |
| `pretty` | `file\|text`, `compact?` | re-indents or compacts |

Files up to 20 MB, inside the workspace. **YAML** is accepted for `.yaml`/`.yml` files, or when the text is not JSON but parses as a YAML mapping or list (text that starts with `{`/`[` is judged as JSON only, so a broken JSON document is not silently accepted as YAML flow syntax). Numbers are kept verbatim. Output is capped at 24 000 bytes with a note on how to narrow (deeper path, `select`, `limit`). All verbs are read-only and run in parallel.

***

## `@diff`

```text theme={"system"}
<tool_call name="@diff" args='{"cmd":"files","args":{"a":"config/old.yaml","b":"config/new.yaml","context":3}}' />
<tool_call name="@diff" args='{"cmd":"dirs","args":{"a":"./v1","b":"./v2","glob":"*.go"}}' />
<tool_call name="@diff" args='{"cmd":"apply","args":{"file":"main.go","patch":"@@ -10,3 +10,3 @@\n ...","dry_run":true}}' />
```

| Verb | Arguments | What it does |
| - | - | - |
| `files` | `a`, `b`, `context?` (3, max 50) | unified diff of two files (≤ 4 MB each); identical files say so in one line; binary files are reported, not dumped |
| `text` | `a`, `b`, `context?` | unified diff of two inline strings, with `\ No newline at end of file` markers |
| `dirs` | `a`, `b`, `glob?` | added, removed and changed files between two trees (names only, 2000-entry budget, `.git`/`node_modules`/`vendor` skipped) |
| `apply` | `file`, `patch`, `dry_run?` (**true**) | parses the `@@` hunks, verifies every context and removed line at its stated position, and refuses on the first mismatch naming the hunk, the line and what the patch expected; `dry_run: false` writes `<file>.bak` and then the file |

The diff is a Myers line diff with an edit budget; past it the differing middle is emitted as one block replacement with an explicit note. Output is capped at 30 000 bytes. `files`, `text` and `dirs` are read-only; `apply` with `dry_run: false` is the only mutation.

> [!TIP]
>
> `@diff apply` is the right tool when the model already has a unified patch (from a PR, a mailing list, a previous `@diff files`); for search/replace edits `@coder patch` stays the precise option.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.