> ## 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.

# Dados estruturados e diffs (@json, @diff)

> @json lê JSON e YAML por caminho, filtra arrays, infere o formato de um payload e valida com linha/coluna; @diff compara arquivos, texto e diretórios e aplica patches unificados com dry-run.

Duas tools para os dados que um agente manuseia entre leituras e edições. `@json` responde perguntas sobre um payload — a resposta de API de 2 MB que o `@http` salvou em disco, um values do Helm — sem lê-lo inteiro. `@diff` mostra o que mudou e aplica um patch só quando toda linha de contexto bate.

***

## `@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,}"}}' />
```

| Verbo | Argumentos | O que faz |
| - | - | - |
| `get` | `file\|text`, `path` | o valor num caminho pontuado/com colchetes: `a.b[0].c`, `[-1]`, `*` abre em leque sobre arrays e objetos; um erro nomeia o segmento e lista as chaves disponíveis ali |
| `keys` | `file\|text`, `path?` | chaves um nível abaixo com resumo de tipo (`object{n}`, `array[n]`, `string(len)`) |
| `query` | `file\|text`, `path?`, `where`, `select?`, `limit?` | filtra um array de objetos: `campo=valor`, `campo!=valor`, `campo~regex`, vários unidos por `&&`; campos pontuados; `limit` padrão 20, máximo 200 |
| `schema` | `file\|text`, `depth?` (3, máx. 8) | o formato inferido de um payload desconhecido, com a frequência de cada chave nos elementos amostrados |
| `validate` | `file\|text` | erros de parse com linha e coluna 1-based e um trecho; dados após o fim são erro |
| `pretty` | `file\|text`, `compact?` | reindenta ou compacta |

Arquivos até 20 MB, dentro do workspace. **YAML** é aceito para arquivos `.yaml`/`.yml`, ou quando o texto não é JSON mas parseia como mapping ou lista YAML (texto que começa com `{`/`[` é julgado só como JSON, então um documento JSON quebrado não é aceito em silêncio como sintaxe flow do YAML). Números são preservados como vieram. A saída é limitada a 24 000 bytes com aviso de como estreitar (caminho mais fundo, `select`, `limit`). Todos os verbos são somente leitura e rodam em paralelo.

***

## `@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}}' />
```

| Verbo | Argumentos | O que faz |
| - | - | - |
| `files` | `a`, `b`, `context?` (3, máx. 50) | diff unificado de dois arquivos (≤ 4 MB cada); arquivos idênticos dizem isso numa linha; binários são reportados, não despejados |
| `text` | `a`, `b`, `context?` | diff unificado de duas strings inline, com marcadores `\ No newline at end of file` |
| `dirs` | `a`, `b`, `glob?` | arquivos adicionados, removidos e alterados entre duas árvores (só nomes, orçamento de 2000 entradas, `.git`/`node_modules`/`vendor` pulados) |
| `apply` | `file`, `patch`, `dry_run?` (**true**) | parseia os hunks `@@`, verifica cada linha de contexto e removida na posição declarada, e recusa no primeiro descasamento nomeando o hunk, a linha e o que o patch esperava; `dry_run: false` grava `<file>.bak` e depois o arquivo |

O diff é um Myers por linha com orçamento de edição; além dele o miolo diferente sai como uma substituição em bloco com aviso explícito. A saída é limitada a 30 000 bytes. `files`, `text` e `dirs` são somente leitura; `apply` com `dry_run: false` é a única mutação.

> [!TIP]
>
> `@diff apply` é a tool certa quando o modelo já tem um patch unificado (de um PR, de uma lista de e-mail, de um `@diff files` anterior); para edições search/replace o `@coder patch` continua sendo a opção precisa.


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