Validador e embelezador de JSON

O Validador e embelezador de JSON é uma ferramenta gratuita que verifica se o JSON é sintaticamente válido e formata o conteúdo válido para tornar a sua estrutura mais fácil de ler.

Para que servem a validação e o embelezamento de JSON?

A validação confirma que os dados introduzidos respeitam a gramática do JSON, enquanto o embelezamento apresenta objetos e matrizes válidos com espaçamento e indentação consistentes. É útil para depurar respostas de APIs, verificar configurações antes da implementação ou ler dados compactos fornecidos por terceiros.

A sintaxe do JSON é mais rigorosa do que a de um literal de objeto JavaScript. Os nomes das propriedades têm de estar entre aspas duplas, as cadeias de texto não podem usar aspas simples e não pode haver vírgulas finais em objetos nem em matrizes. Os comentários, undefined, NaN e Infinity também não fazem parte da especificação JSON.

Esta ferramenta utiliza a função json_decode do PHP no servidor. Os dados introduzidos são enviados para o servidor através de HTTPS e não são guardados. Como saem do teu dispositivo, remove palavras-passe, tokens de acesso e dados pessoais caso as regras de tratamento de dados da tua organização não permitam o seu envio para um servidor externo.

Como valido e embelezo JSON?

Cola o conteúdo no campo JSON e executa a ferramenta. Para obteres um resultado útil, inclui um valor JSON completo, em vez de parte de um objeto copiada de uma linha de registo.

1. Copia a resposta em bruto, o bloco de configuração ou outro valor JSON sem os rótulos apresentados pela consola.
2. Cola-o no campo JSON, preservando as aspas e os carateres de escape.
3. Executa a validação e verifica o resultado formatado ou o erro apresentado.
4. Se a validação falhar, corrige o primeiro problema de sintaxe aparente e volta a executar a ferramenta. Uma única aspa em falta pode fazer com que vários carateres posteriores sejam interpretados incorretamente.

Os quatro carateres de espaço em branco permitidos entre elementos JSON, espaço (U+0020), tabulação (U+0009), mudança de linha (U+000A) e retorno do carro (U+000D), são irrelevantes, pelo que podem ser adicionados ou removidos sem alterar os dados. O espaço em branco dentro de uma cadeia entre aspas faz parte dos dados e tem de permanecer inalterado. A pontuação dentro das cadeias também é preservada, embora as aspas, as barras invertidas e os carateres de controlo precisem da sequência de escape adequada.

Como interpreto o resultado da validação?

Um resultado bem-sucedido significa que o PHP conseguiu descodificar os dados introduzidos como JSON. Uma falha significa que o analisador não conseguiu interpretá-los como um único valor JSON completo e válido. O embelezamento torna depois visíveis os níveis de aninhamento e os limites dos objetos e matrizes válidos.

As causas mais comuns de falha incluem:

• uma vírgula final antes de } ou ];
• um nome de propriedade sem aspas, como {name: "Ada"};
• cadeias entre aspas simples;
• uma vírgula em falta entre propriedades ou elementos de uma matriz;
• aspas duplas ou uma barra invertida sem escape dentro de uma cadeia;
• um objeto, uma matriz ou uma cadeia incompletos;
• dados UTF-8 inválidos ou um caráter de controlo em bruto dentro de uma cadeia;
• uma parte inteira com zeros iniciais desnecessários, como 01 ou -01, ou valores que não pertencem ao JSON, como NaN.

Um campo vazio não é JSON válido. Em contrapartida, um valor isolado como 42, true, null ou "hello" é JSON válido, mesmo não sendo um objeto nem uma matriz. Um conteúdo com níveis de aninhamento muito profundos também pode ultrapassar o limite do descodificador.

A validação da sintaxe não confirma que os dados cumprem o contrato de uma API. Um documento pode ser JSON válido e conter uma cadeia quando a aplicação espera um número, omitir uma propriedade obrigatória ou usar um formato de data não aceite. Para verificar esses requisitos, utiliza JSON Schema ou validações ao nível da aplicação.

Exemplos práticos de JSON

Dados compactos válidos:

{"name":"Ada","active":true,"roles":["admin","editor"]}

O resultado embelezado apresenta as propriedades e os elementos da matriz em níveis separados e indentados. Os valores continuam a ser, respetivamente, uma cadeia, um booleano e uma matriz. A formatação altera a apresentação, não os tipos de dados subjacentes.

Dados inválidos com uma vírgula final:

{"name":"Ada","active":true,}

A validação falha porque o JSON não permite uma vírgula depois da última propriedade. Remove essa vírgula para tornar o objeto válido.

Os carateres acentuados e o texto em alfabetos não latinos podem aparecer diretamente em cadeias JSON quando os dados estão em UTF-8 válido. Por exemplo, {"city":"Zürich","greeting":"こんにちは"} é válido. A notação de escape JSON, como \u00fc, é outra representação válida de determinados carateres Unicode, embora sejam necessários pares substitutos para carateres fora do Plano Multilingue Básico.

Quando não vale a pena embelezar JSON?

O embelezamento é desnecessário quando apenas uma máquina vai ler o JSON e não está prevista qualquer inspeção humana ou revisão no controlo de versões. A indentação e as mudanças de linha adicionais aumentam o número de bytes transferidos, pelo que as respostas em produção são normalmente enviadas num formato compacto.

Também há pouco benefício em minificar JSON que já está compacto. Repetir a minificação não reduz nomes fixos de propriedades nem valores de cadeias, e alterar esses valores modificaria os dados. Para JavaScript destinado a implementação, em vez de dados JSON, o Minificador de JS é a opção mais adequada.

O embelezamento é especialmente útil para inspecionar estruturas ou valores JSON durante a depuração, a revisão de código e as verificações anteriores à implementação. Torna mais evidente um aninhamento incorreto, facilita a leitura de matrizes grandes e produz diferenças mais claras quando uma configuração é registada no Git. Não repara automaticamente JSON malformado nem determina qual seria o significado pretendido de um fragmento ambíguo.

Perguntas frequentes

O JSON pode ter comentários?

Não. O JSON padrão não tem sintaxe para comentários, pelo que // comment e /* comment */ fazem a validação falhar. Se precisares de comentários num ficheiro de configuração, utiliza um formato que os suporte ou remove-os antes de passares o conteúdo a um analisador JSON rigoroso.

Os nomes de propriedades duplicados são rejeitados?

Não necessariamente. A especificação JSON indica que os nomes dos membros de um objeto devem ser únicos, mas os analisadores nem sempre tratam nomes duplicados como um erro de sintaxe. A descodificação em PHP conserva habitualmente o valor posterior. Se for importante preservar todas as ocorrências, deteta os duplicados antes da validação.

Posso validar um ficheiro JSON Lines?

Não como um único documento JSON. O JSON Lines, também chamado NDJSON, contém um valor JSON separado em cada linha, enquanto um analisador JSON normal espera um único valor de nível superior. Valida cada linha separadamente ou converte os registos numa única matriz JSON.

A ordem das propriedades de um objeto é importante?

As aplicações não devem depender da ordem das propriedades de um objeto JSON. As matrizes são ordenadas, mas os objetos representam coleções de membros com nome, e outro analisador ou serializador pode apresentar esses membros por uma ordem diferente. Se a sequência tiver significado, coloca os valores numa matriz.

Porque pode um ficheiro JSON falhar mesmo parecendo correto?

Uma marca de ordem de bytes invisível, UTF-8 malformado ou um caráter de controlo sem escape pode fazer falhar texto que parece correto. Copiar conteúdo de um terminal também pode introduzir prefixos, como rótulos de estado ou carimbos de data e hora. Examina os bytes em bruto ou abre o ficheiro num editor que consiga mostrar a codificação e os carateres de controlo.

Verificações finais

Antes de implementares o JSON corrigido, compara os tipos de dados, além dos valores visíveis, confirma que as sequências de escape não foram alteradas e executa a aplicação que vai consumir os dados ou a respetiva validação de esquema. Ao diagnosticares dados de terceiros, conserva uma cópia intacta da resposta original para que a formatação não esconda a origem do erro.