CDRN

Validar a sintaxe de um JSON

  • Painel
  • Documentação
  • API
verifica a sintaxe de uma cadeia JSON e indica a linha e a coluna do menor erro

Para que serve um validador JSON?

Um validador JSON tem um papel mais modesto, mas mais preciso, do que um formatador: não reescreve nada. Recebe uma cadeia e responde a uma pergunta binária: este texto é JSON conforme à RFC 8259? Se sim, a ferramenta cede o controlo. Se não, indica exatamente a linha, a coluna e um extrato do JSON em torno do problema, para ajudar o programador a corrigir imediatamente.

Na prática, é a ferramenta que se utiliza assim que um parser algures devolve uma mensagem de erro críptica do género SyntaxError: Unexpected token } in JSON at position 217. Em vez de contar caracteres à mão num editor, cola-se a cadeia completa, lê-se a posição e vê-se o extrato em falta.

Validação, formatação: duas operações distintas

Confundem-se muitas vezes as duas. O nosso formatador JSON recebe JSON válido e reescreve-o com uma indentação legível. O validador, esse, limita-se a um veredito sintático. Não efetua validação semântica: não sabe se o valor de um campo email se parece com um email, nem se a estrutura corresponde a um JSON Schema. Para isso, utilizam-se ferramentas dedicadas (ajv em Node, justinrainbow/json-schema em PHP).

O encadeamento clássico em debug é: validar primeiro (a ferramenta indica o erro de sintaxe), formatar depois (o payload agora válido torna-se legível), comparar por fim com outro payload de referência através do nosso comparador JSON.

Os erros JSON mais frequentes

  • Vírgula final (trailing comma): {"a": 1, "b": 2,}. Tolerada pelo JavaScript, ECMAScript e JSON5; recusada pelo JSON puro. É o erro número um quando se copia e cola a partir de um editor de código.
  • Apóstrofos em vez de aspas duplas: {'a': 1} é inválido. O JSON só aceita aspas duplas, em torno das chaves como dos valores string.
  • Chaves não citadas: {a: 1}, sintaxe JavaScript válida mas JSON inválida.
  • Caracteres de controlo não escapados numa string: uma quebra de linha bruta, uma tabulação. O JSON exige \n, \t, \r.
  • Comentários: // comentário ou /* */. Aceites em JSONC (config VS Code) ou JSON5, recusados em JSON puro.
  • Codificação incorreta: um BOM UTF-8 no início de ficheiro, conteúdo em latin-1 mal convertido. O validador devolve muitas vezes uma mensagem genérica para estes casos.
  • Estrutura não terminada: um { ou [ sem fechamento, frequente quando se trunca um payload no copiar-colar.

Como o validador localiza o erro

A ferramenta utiliza json_decode() do PHP com a flag JSON_THROW_ON_ERROR. O PHP devolve uma mensagem que contém uma posição em octetos (position 217), que convertemos num par linha/coluna contando as quebras de linha antes do offset. Um extrato de cerca de 80 caracteres é depois recortado em torno da posição para dar contexto. Costuma ser suficiente para localizar o erro: aspas mal colocadas, vírgula a mais, parênteses retos em falta.

Atenção: a posição reportada pelo PHP nem sempre é exatamente o caractere em falta. É frequentemente depois do erro, no momento em que o parser desistiu. Se o extrato mostra "name": "Alice", }, o erro real é a vírgula, não a chaveta.

Casos de uso típicos

  • Configuração corrompida: composer.json, package.json, tsconfig.json que impedem o arranque de um build. Cola-se, vê-se a linha, corrige-se.
  • Resposta de API truncada: um proxy cortou o payload. A estrutura não está terminada, o validador sinaliza-o.
  • Payload de webhook: um serviço de terceiros envia JSON mal formado. O validador permite constatar o problema no lado do emissor sem mergulhar no código aplicacional.
  • JSON construído por concatenação: prática a evitar mas comum, sobretudo em bash ou em SQL. O validador revela as aspas duplas não escapadas.

Limites da ferramenta

O validador não efetua validação contra um esquema. Não diz que falta o campo email, que o valor não é um inteiro ou que o array esperado não tem o comprimento certo. Para estas verificações estruturais, utiliza-se o JSON Schema. O validador também não corrige o JSON: não tenta acrescentar uma chaveta em falta, nem retirar uma vírgula a mais. É uma escolha: a correção automática mascara muitas vezes erros reais.

Perguntas frequentes

Qual a diferença com um linter?

Um linter vai mais longe: verifica também regras de estilo (alfabética, convenções de nomenclatura), deteta valores em duplicado, sugere melhorias. O validador mantém-se na conformidade sintática.

O meu JSON é válido, mas a minha aplicação rejeita-o?

Verifique a codificação (UTF-8 sem BOM), o limite de tamanho no servidor, os tipos esperados. Um JSON sintaticamente correto pode ainda assim não corresponder ao esquema aplicacional.

O validador conserva o meu JSON?

Não. O tratamento é síncrono no lado do servidor, sem persistência. Para dados muito sensíveis, prefira ainda assim uma validação local através de jq ou de um script PHP.

Exemplo de pedido

curl -X POST https://cdrn.fr/api/v1/tools/json-validator/execute \
  -H "Content-Type: application/json" \
  -d '{"input":"..."}'

Esquema de entrada

Campo Tipo Obrigatório Predefinição
input text ✓ –

Pontos de acesso

  • GET https://cdrn.fr/api/v1/tools - lista todas as ferramentas disponíveis
  • GET https://cdrn.fr/api/v1/tools/json-validator - obtém o esquema desta ferramenta
  • POST https://cdrn.fr/api/v1/tools/json-validator/execute - executa esta ferramenta com um payload JSON