Ferramentas para desenvolvedores · Formatador e validador JSON
JSON válido versus válido em relação a um esquema: dois significados de 'válido'
· Fundo
JSON padrões validação
Um validador dizendo que seu JSON é válido significa apenas que ele analisa. Este post explica os níveis de validade (sintaxe, estrutura, semântica) e porque o esquema JSON existe para tudo além da gramática.
Válido e ainda rejeitado
Uma solicitação pode ser JSON impecável e ainda assim ser inaceitável para um API. `{"username":"nori","plan":"gold"}` possui delimitadores equilibrados, nomes entre aspas e valores legais, mas um serviço pode exigir um e-mail, rejeitar o nome do plano ou proibir a criação de conta no estado atual. O analisador e o aplicativo respondem a perguntas diferentes, portanto ambos os resultados podem estar corretos.
ToolAcre responde apenas à primeira pergunta: este texto pode ser analisado como JSON estrito dentro de seus limites de entrada? Ele não carrega um esquema, verifica propriedades necessárias, verifica formatos, contata um banco de dados ou avalia regras de negócios. Quando a ferramenta disser Válido, leia isso como “sintaxe JSON bem formada”, não como aprovação do sistema que consumirá o valor.
Nível um: sintaxe bem formada
A validação de sintaxe verifica a gramática JSON: um valor de nível superior, contêineres emparelhados corretamente, nomes de objetos entre aspas, vírgulas e dois pontos válidos, strings legais, números legais e literais exatos. Ele rejeita `NaN` e `Infinity`, comentários, vírgulas finais e strings entre aspas simples. Ele aceita qualquer formato gramaticalmente válido, incluindo um número isolado ou um objeto com campos desconhecidos.
A fonte malformada tem um ponto de falha textual, então ToolAcre pode relatar uma linha e coluna para o primeiro caractere impossível. A falta de uma vírgula pode fazer com que a próxima cotação seja relatada; uma vírgula final pode fazer com que o delimitador de fechamento seja relatado. A correção da sintaxe cria um valor analisável, mas não estabelece que o valor tenha a forma ou o significado esperado por outro programa.
Nível dois: a forma
A validação de forma pergunta se o valor analisado corresponde a um contrato declarado. Um esquema de usuário pode exigir `email`, restringir `age` a um número inteiro de pelo menos 18, limitar `tier` a `free` ou `pro` e proibir propriedades desconhecidas. `{"email":false,"tier":"gold"}` é uma sintaxe JSON válida, mas falha nessas regras estruturais porque os tipos de valor e as escolhas permitidas estão errados.
JSON O esquema é uma forma de expressar tais restrições, mas ToolAcre não o executa. Um validador de esquema geralmente relata um caminho de instância como `/tier`, uma palavra-chave como `enum` e uma mensagem explicativa em vez de um acento circunflexo do analisador. Mantenha a versão do esquema e o contrato API ao lado da carga útil ao diagnosticar este nível; alterar a pontuação não reparará um valor analisado corretamente com a forma errada.
Nível três: significado
O significado depende de fatos e regras que vão além da forma estática do documento. Um `accountId` pode ter o padrão de string correto sem nomear nenhuma conta. Uma data de início pode corresponder a um formato estilo ISO, embora seja posterior à data de término. Uma quantidade pode ser positiva, mas exceder o estoque atual. Estas falhas requerem contexto de aplicação, estado armazenado ou relacionamentos entre campos.
Algumas restrições semânticas podem ser aproximadas em um esquema, mas muitas pertencem à lógica de serviço, onde dados oficiais e estado de transação estão disponíveis. As respostas de erro neste nível devem identificar o campo ou regra relevante sem fingir que o texto JSON estava malformado. ToolAcre não pode reproduzir essas decisões porque não conhece o contrato nem envia a entrada para o aplicativo que possui a regra de negócio.
Exemplo resolvido: uma carga útil por meio de três verificações
Comece com `{"sku":"A-19","quantity":3,"warehouse":"north"}`. ToolAcre aceita: todos os nomes e valores seguem a gramática JSON. Um esquema pode então exigir um objeto, uma string não vazia SKU, uma quantidade inteira positiva e um dos códigos de armazém documentados. Suponha que essa carga útil também passe por essas restrições. Nenhuma das verificações confirmou que SKU A-19 existe ou que o norte contém três unidades.
O serviço de inventário realiza a terceira verificação nos registros atuais e pode rejeitar a solicitação como indisponível. Alterar o recuo não pode alterar esse resultado. Se `quantity` fosse escrito como `03`, a sintaxe falharia primeiro; se fosse `"3"`, a análise seria aprovada, mas a verificação do tipo de esquema falharia; com o numérico `3`, apenas a regra de estoque ativo permanece. O mesmo campo pode, portanto, falhar em três camadas distintas por três razões distintas.
Onde cada cheque pertence
Execute a validação de sintaxe o mais cedo possível durante a edição, porque as verificações posteriores não podem operar de forma confiável em texto que não é analisado. Imponha a forma declarada em cada limite de aplicativo não confiável, em vez de assumir que um cliente já o fez. Avalie invariantes de negócios no componente que possui o estado necessário, especialmente quando a resposta pode mudar entre as solicitações.
As verificações do lado do cliente melhoram o feedback, mas não substituem a aplicação do lado do servidor. Por outro lado, uma resposta do servidor dizendo “JSON inválido” deve ser reservada para falha de análise em vez de usada para cada solicitação rejeitada. A separação clara produz diagnósticos úteis: linha e coluna para sintaxe, caminhos de instância para restrições estruturais e códigos ou mensagens específicos de domínio para conflitos semânticos. ToolAcre fornece apenas a primeira categoria.
O que isso não cobre
Este formatador não cria ou avalia o esquema JSON, seleciona um rascunho de esquema, resolve referências de esquema, insere padrões ou força strings em números. Ele também não conhece o documento OpenAPI de API ou convenções de validação personalizadas. Fornecer um esquema junto com a entrada não alteraria o resultado de ToolAcre porque não há etapa de processamento de esquema nesta ferramenta.
A validação de sintaxe também não detecta nomes de objetos duplicados aqui; `JSON.parse` mantém a última ocorrência antes da formatação. Nem garante precisão numérica, bytes canônicos, renderização segura ou autorização. Cada uma dessas preocupações precisa do seu próprio contrato e implementação. Evite compactá-los em um único crachá verde “válido”, pois isso oculta quais evidências foram coletadas e quais perguntas nunca foram feitas.
Conclusão: 'válido' precisa de um qualificador
Qualifique cada reivindicação de validação. “Válido JSON” significa que o texto segue a gramática. “Válido para este esquema” significa que o valor analisado satisfaz um contrato estrutural nomeado. “Aceito pelo serviço” significa que as regras de aplicação atuais permitem a operação. A passagem de uma camada é necessária para a próxima em muitos fluxos de trabalho, mas nunca há evidência de que todas as camadas posteriores foram aprovadas.
Use ToolAcre para formatar e verificar a sintaxe estrita, incluindo a rejeição de literais não JSON, como `NaN` e `Infinity`. Em seguida, use o esquema e o aplicativo que realmente controlam a carga útil. Quando uma solicitação ainda falhar, leia o erro em sua própria camada em vez de reformatar repetidamente o JSON correto. A ferramenta não possui verificações de esquema e esse limite explícito é mais útil do que uma promessa excessivamente ampla de validade.