Validador JSON gratuito

Validação JSON: duas camadas, duas perguntas diferentes

Um validador JSON responde a uma pergunta binária, este documento JSON está bem formado?, entregando a entrada ao mesmo parser que o navegador usa internamente e reportando se aceita a sintaxe. Esta ferramenta faz isso e só isso. Não verifica se os dados dentro do documento significam o que você pretendia. Essa segunda pergunta, o documento tem a forma, os tipos e as restrições que sua aplicação espera?, é a validação de esquema, o território de ferramentas como Ajv (abordada abaixo). As duas atividades se complementam e respondem a perguntas diferentes; usar uma quando se queria a outra é um erro de categoria. Uma analogia útil é a distinção corretor-ortográfico / corretor-gramatical em processadores de texto: o ortográfico (sintaxe) diz se cada palavra é uma palavra real; o gramatical (esquema) diz se a frase faz sentido; ambos são úteis, nenhum substitui o outro, e nenhum diz se o ensaio é bom. {"phoneNumber": 12345} é JSON bem formado, mas se sua aplicação esperava uma string formatada como "+1-555-555-1234", está errado, e um validador de sintaxe não consegue dizer.

Além da verificação sintática, esta ferramenta também oferece uma passagem de «Corrigir problemas comuns» no melhor esforço que reescreve as quatro formas mais frequentes pelas quais desenvolvedores escrevem JSON inválido sem querer: vírgulas finais, strings entre aspas simples, chaves sem aspas e literais undefined (reescritos como null). É uma heurística, não um parser, então sempre revise a saída corrigida antes de adotar.

Uma breve história do JSON

JSON tem uma biografia notavelmente curta. O acrônimo foi cunhado na State Software, Inc., uma pequena consultoria que Douglas Crockford e Chip Morningstar cofundaram em março de 2001 para construir o que mais tarde seria chamado de aplicações web Ajax. A primeira mensagem JSON foi enviada em abril de 2001 de um computador na garagem de Morningstar na Bay Area. Crockford não reivindica ter inventado JSON, o formato já existia dentro da linguagem JavaScript como subconjunto de objeto-literal; sua contribuição foi descolá-lo, dar-lhe um nome, montar um site (json.org apareceu em 2002 com uma descrição da gramática em três notações e um parser de referência em JavaScript) e fazer lobby pela adoção. Dezembro de 2005 é o momento que a maioria dos historiadores aponta como a entrada de JSON no mainstream: naquele mês, o Yahoo! começou a oferecer alguns dos seus serviços web em JSON. A IETF pegou em seguida: RFC 4627 («The application/json Media Type for JSON»), da pena do próprio Crockford, foi publicada em julho de 2006 como documento informacional, não Standards Track. Os órgãos de padronização se atualizaram em 2013-2014: ECMA-404 1.ª edição em outubro de 2013 (deliberadamente mínima, seis páginas de conteúdo substantivo), RFC 7159 em março de 2014 (afrouxou a restrição de nível superior para que qualquer valor JSON, não só objetos e arrays, pudesse ser documento completo), e o par atual em dezembro de 2017: RFC 8259 (agora Internet Standard STD 90) e ECMA-404 2.ª edição normativamente alinhada com ela. As duas formam par: cada uma referencia normativamente a outra e contém um compromisso de mantê-las consistentes. Também publicada como ISO/IEC 21778:2017.

A gramática JSON em 200 palavras

Um documento JSON é um único valor, opcionalmente cercado por espaços em branco. Existem exatamente seis tipos de valores: objeto, uma coleção não ordenada de zero ou mais pares nome/valor, escrita {"k": v, "k2": v2}; array, uma sequência ordenada, [v, v2, v3] (arrays preservam ordem por spec); string, uma sequência de caracteres Unicode envolta em aspas duplas (aspas simples não permitidas; escapes com barra invertida \", \\, \/, \b, \f, \n, \r, \t mais \uXXXX; caracteres de controle U+0000 a U+001F devem ser escapados); número, uma forma ASCII estrita (sinal de menos opcional, parte inteira sem zeros à esquerda, parte fracionária opcional, expoente opcional com e ou E); true / false, os booleanos JSON, apenas minúsculas; null, a ausência de valor, apenas minúsculas. Espaços entre tokens são permitidos e ignorados. Sem comentários. Sem vírgulas finais. Chaves de objeto devem ser strings entre aspas duplas. A gramática cabe em uma página. A forma estrita do número proíbe hex (0xFF), octal (0777), sinal +, Infinity, NaN, e pontos decimais finais como 1.; isso pega quem escreve JSON à mão em ambientes que aceitam as formas numéricas ECMAScript mais frouxas, mais comumente, quem já colou um código de cor hex em um arquivo JSON.

Por que a gramática é tão estrita, as escolhas de design de Crockford

Duas omissões deliberadas explicam a maior parte da fricção que usuários sentem ao escrever JSON à mão. Sem comentários. JavaScript tem // e /* */; JSON, subconjunto de JavaScript, não tem nenhum. A razão declarada de Crockford, postada no Google+ em 2012, foi citada milhares de vezes desde então: «Eu removi os comentários do JSON porque vi pessoas usando-os para guardar diretrizes de parsing, prática que teria destruído a interoperabilidade. Sei que a falta de comentários deixa algumas pessoas tristes, mas não deveria.» O argumento é que comentários convidam à extensão, se // @schema foo.json está em sua config e sua ferramenta lê isso, então seu arquivo de config já não é JSON. Sem vírgulas finais. Uma vírgula é um separador, não um terminador. [1, 2, 3] é legal mas [1, 2, 3,] não é. A razão é a mesma dos comentários: simplicidade da gramática e uniformidade entre parsers. O custo é que quem edita um objeto JSON multilinha, adicionar uma propriedade, reorganizar propriedades, remover a última, tem que pensar na vírgula. Sem undefined. JavaScript tem undefined; JSON não. Use null ou omita a propriedade por completo. BOM na entrada. Um byte-order mark (U+FEFF) no início de um documento JSON é proibido em JSON transmitido, mas parsers PODEM ignorar um se aparecer. Na prática, arquivos salvos como «UTF-8 with BOM» por editores Windows mais antigos silenciosamente quebram alguns parsers e silenciosamente funcionam em outros.

Erros JSON comuns :

• Vírgulas finais : o último elemento de um objeto ou array não pode ter vírgula
• Apóstrofos em vez de aspas duplas : o JSON só permite aspas duplas para as strings
• Chaves sem aspas : as chaves de objetos devem sempre estar entre aspas duplas
• Comentários : o JSON não suporta comentários (embora algumas ferramentas os aceitem)
• Barra invertida não escapada. Dentro de uma string JSON, \ é o caractere de escape. "C:\Users\Alice" falha porque \U e \A não são escapes reconhecidos. A cura é duplicar cada barra invertida: "C:\\Users\\Alice".
• Caracteres de controle não escapados. Uma quebra de linha, tabulação ou outro caractere literal em U+0000-U+001F dentro de uma string JSON é proibido. A maioria dos usuários esbarra nisso ao colar uma string multilinha em um valor JSON sem escapar as quebras como \n.
• NaN e Infinity. Fora da gramática JSON. O JSON.parse do navegador rejeita-os. JSON.stringify produz null quando solicitado a serializar NaN ou Infinity, então o ida-e-volta perde informação silenciosamente.
• Entrada vazia. Lança «Unexpected end of JSON input». A pegadinha é que uma resposta HTTP que voltou com Content-Type: application/json mas corpo vazio produz esse erro em cadeias fetch().then(r => r.json()).

JSON Schema, o padrão para validar a forma

JSON Schema é um vocabulário baseado em JSON para descrever a estrutura e restrições de documentos JSON. A primeira proposta foi submetida por Kris Zyp em outubro de 2007; a série de Internet-Drafts da IETF começou com draft-zyp-json-schema-00 em 5 de dezembro de 2009. Os drafts sucessivos evoluíram através de meia dúzia de autores e editores na década e meia seguinte. A versão estável atual é o draft 2020-12 (o nome «2020-12» refere-se ao snapshot de desenvolvimento do qual derivou; o lançamento formal de fato foi em 16 de junho de 2022). As quatro palavras-chave de asserção mais usadas carregam a maior parte do trabalho diário: type (restringe um valor a um dos seis tipos JSON ou a uma lista de tipos aceitáveis), required (lista de nomes de propriedades que um objeto deve conter), properties (mapa de nome de propriedade para sub-esquema para o valor), e items (um esquema aplicado a cada elemento de um array). Combinadas com minimum, maximum, minLength, maxLength, pattern (regex), format (date-time, email, IPv4, etc.) e as palavras-chave compostas (allOf, anyOf, oneOf, not), JSON Schema pode expressar quase qualquer restrição de «forma» que seus dados precisem satisfazer. O esquema é em si um documento JSON, o que é recursivo de uma forma que alguns acham elegante e outros tonto.

Ajv, o validador de esquema JavaScript dominante

Se você quer fazer validação de esquema em JavaScript, a resposta canônica é Ajv (Another JSON Schema Validator) de Evgeny Poberezkin. Seu truque é compilar o esquema em JavaScript otimizado: em vez de percorrer o esquema e a árvore de dados em tempo de execução, gera uma função que codifica em duro cada verificação e roda em velocidade nativa. Isso o torna dramaticamente mais rápido que validadores ingênuos em documentos grandes e em caminhos de validação quentes. Ajv suporta os drafts JSON Schema 04, 06, 07, 2019-09 e 2020-12; é o validador integrado no express-validator, na validação de requisições do AWS API Gateway e em muitos dos principais frameworks Node.js. Para Python, a escolha canônica é jsonschema de Julian Berman; para Java, o json-schema-validator da Networknt. O ponto é que a validação de esquema é um problema resolvido, maduro e bem instrumentado, mas é um problema no qual você tem que entrar opt-in: escrever o esquema. Esta ferramenta não escreve o esquema por você; faz só validação sintática.

JSON5 e JSONC, os superconjuntos relaxados

JSON5 é um superconjunto formal de JSON especificado em json5.org, originalmente projetado por Aseem Kishore em 2012 e agora mantido por Jordan Tucker. Permite tudo o que o JSON estrito proíbe: comentários (// e /* */), vírgulas finais, strings entre aspas simples, chaves de objeto sem aspas (quando são identificadores ECMAScript válidos), números hexadecimais, pontos decimais iniciais/finais (.5 ou 5.), Infinity e NaN, e números com sinal. Documentos JSON5 normalmente usam a extensão .json5 e são parseados por bibliotecas como o pacote npm json5. JSONC é o modo informal «JSON with Comments» da Microsoft, usado nos arquivos de configurações do VS Code (settings.json, launch.json, tasks.json). Comentários são permitidos por spec; vírgulas finais são toleradas pelo parser de referência mas marcadas com avisos. As formas relaxadas são para arquivos de configuração editados à mão onde a disciplina do JSON estrito atrapalha; para troca máquina-a-máquina, JSON estrito continua a escolha certa. Esta ferramenta usa o JSON.parse estrito do navegador e portanto rejeitará ambos, remova comentários e vírgulas finais antes de colar, ou use um parser JSON5/JSONC para converter primeiro para JSON estrito.

Validadores em streaming para entradas muito grandes

O JSON.parse do navegador carrega o documento inteiro na memória como uma única árvore de objetos. Para a maioria das entradas isso está bem; para arquivos de log, exports de API de vários gigabytes ou dumps de dados de sensores, não está. A abordagem de streaming é consumir o documento como um fluxo de tokens e emitir eventos («início de array», «valor de string», «chave de objeto») sem nunca segurar a estrutura inteira na memória. clarinet de Marak Squires é o parser JSON streaming Node.js canônico, modelado sobre o padrão do parser SAX XML. Oboe.js de Jim Higson (originado em sua tese de 2013) é o equivalente compatível com navegador, projetado para consumir JSON sobre fetch enquanto flui e emitir eventos para cada JSONPath correspondente; já não é mantido ativamente mas a técnica que pioneirizou continua útil. JSONStream no npm envolve clarinet para uso Node compatível com pipes. Uma ferramenta puramente de navegador como esta é limitada pela memória disponível; se você valida JSON em escala de gigabytes, rode um parser de streaming no Node ou use jq --stream na linha de comando.

Onde a validação JSON importa em fluxos de trabalho reais

Arquivos de configuração são o caso de maior alavancagem: tsconfig.json, package.json, configs de ESLint e Prettier, Docker Compose, políticas AWS IAM. Um único caractere inválido pode quebrar o build; um validador sintático o pega antes do build. Respostas de API vêm a seguir: desenvolver contra uma API externa muitas vezes significa olhar para um payload e perguntar «isto é realmente JSON válido?» antes de caçar um bug de parsing mais fundo. Cargas úteis de webhooks, eventos do Stripe, gatilhos do GitHub Actions, webhooks de entrada do Slack, são JSON; um colar-e-validar rápido pega os casos em que uma assinatura malformada ou um byte errante corrompeu o corpo. Entradas de log (logs estruturados do Splunk, Datadog, Loki) são JSON linha-a-linha; uma linha ruim quebra todo o pipeline de ingestão. Arquivos JSON gerados (lockfiles, manifestos de build, fixtures de teste) às vezes derivam de forma barulhenta durante desenvolvimento normal; um validador sintático pega os casos em que o próprio passo de geração falhou.

Os limites honestos de um validador só-sintaxe

Um validador sintático não pode pegar erros de lógica. Não pode te dizer que um campo «phone number» contém um inteiro em vez de uma string; que uma string «date» está malformada mas por acaso é uma string válida; que falta um campo obrigatório; que um número que deveria ser positivo é negativo; que dois campos que deveriam coincidir não coincidem. Tudo isso são problemas de validação de esquema. O pipeline correto para um sistema em produção é: (1) validação sintática como primeira barreira, isto parseia como JSON sequer? (2) validação de esquema como segunda barreira, tem a forma esperada? (3) validação de lógica de negócio como terceira barreira, os dados fazem sentido dado outro estado? Existem ferramentas para as três camadas; esta só lida com a primeira. A vantagem de colar um payload primeiro em um validador sintático é que isola o modo de falha mais barato e mais comum (uma vírgula errante, uma chave faltante) dos erros de esquema mais caros que de outra forma os afogariam.

Privacidade: por que só-navegador importa aqui

Validar JSON em um servidor exige enviar o documento. Para exemplos comuns de dados públicos, é inofensivo. Para respostas de API que contêm tokens de autenticação, PII de clientes, registros internos de funcionários, segredos de configuração ou dados de produto não lançados, não é. Mesmo com a política de exclusão mais escrupulosa, o upload fica em logs do servidor, possivelmente em um cache CDN, possivelmente em um pipeline de analytics, possivelmente em um backup. Esta ferramenta executa JSON.parse no seu navegador via JavaScript. O documento colado nunca cruza a rede, verifique na aba Network do DevTools ao clicar em um botão, ou coloque a página offline (modo avião) após carregar e confirme que o validador continua funcionando. Seguro para validar payloads de webhook com segredos, respostas de API com cabeçalhos de autenticação, arquivos de config com credenciais de banco, ou qualquer outro JSON que você não queira ver copiado no disco rígido de um desconhecido.

Perguntas frequentes

O que é um JSON válido ?

Um JSON válido deve ser um destes tipos : objeto ({}), array ([]), string (""), número, booleano (true/false) ou null. Todas as strings e chaves de objetos devem usar aspas duplas. Os números não podem ter zeros à esquerda. Os espaços são permitidos entre os elementos.

O que faz « Corrigir problemas comuns » ?

A correção tenta consertar automaticamente erros frequentes : vírgulas finais, apóstrofos convertidos em aspas duplas, chaves sem aspas e valores undefined convertidos em null. É uma ferramenta heurística que pode não corrigir tudo, revise o resultado com atenção.

Como validar JSON no meu aplicativo ?

Em JavaScript : use JSON.parse() e capture os erros. No Node.js : fs.readFileSync() + JSON.parse(). Em Python : json.loads() ou json.load(). A maioria das linguagens dispõe de bibliotecas JSON integradas.

Posso validar JSON5 ou JSONC (JSON com comentários)?

Não diretamente. Esta ferramenta usa o JSON.parse estrito do navegador, que segue a RFC 8259, comentários, vírgulas finais, aspas simples e chaves sem aspas são erros de sintaxe. Se sua entrada é JSON5 (json5.org, Aseem Kishore 2012, mantido por Jordan Tucker) ou JSONC do VS Code, instale o pacote npm json5 ou o pacote jsonc-parser, converta para JSON estrito e depois valide. A passagem «Corrigir problemas comuns» lida com um subconjunto das diferenças mas não é um parser JSON5 / JSONC completo.

Existe um limite de tamanho?

Sem limite rígido, mas o JSON.parse do navegador carrega o documento inteiro na memória como uma única árvore de objetos. Dezenas de milhares de linhas funcionam confortavelmente; dumps de log de vários gigabytes vão esgotar a memória. Para JSON muito grande, rode um parser de streaming como clarinet (Marak Squires) ou Oboe.js (Jim Higson, 2013), ou use jq --stream na linha de comando, que pode processar documentos de tamanho arbitrário sem nunca carregar todo o conteúdo.

Meus documentos JSON são enviados?

Não. JSON.parse roda no seu navegador via JavaScript. O documento colado nunca cruza a rede, verifique na aba Network do DevTools ao clicar Validate, ou coloque a página offline após carregar e confirme que a ferramenta continua funcionando. Seguro para validar payloads de webhook com segredos, respostas de API com cabeçalhos de autenticação, ou arquivos de config com credenciais de banco.