Como descobrir porque é que o JSON não passa no schema

Para que serve a validação de JSON com um schema

O JSON Schema Validator serve para verificar se um texto JSON corresponde às regras de um JSON Schema. Pode utilizá-lo antes de integrar dados numa API, rever um payload recebido ou perceber por que motivo uma estrutura não é aceite. A ferramenta recebe o JSON e o schema em campos separados e apresenta se os dados são válidos, juntamente com detalhes de validação aplicáveis.

Como validar os dados e localizar a falha

1. Prepare dois textos: no primeiro, coloque os dados JSON que pretende verificar; no segundo, coloque o JSON Schema que descreve a estrutura esperada. Os dois campos são opcionais e começam como texto vazio, mas a validação não pode confirmar dados quando um deles fica vazio ou contém apenas espaços.

2. Confirme a sintaxe dos dois documentos. A ferramenta tenta interpretar primeiro o JSON dos dados e depois o schema. Se um dos textos não for JSON válido, o resultado indica que os dados não são válidos e inclui uma descrição do erro de interpretação.

3. Execute a operação de validação. O resultado separa o estado da operação da validade dos dados: uma operação pode terminar com sucesso técnico mesmo quando o JSON não corresponde ao schema. Por isso, leia o indicador de validade e os detalhes apresentados, em vez de considerar apenas o estado da operação.

4. Se houver falhas, compare cada indicação com o texto de entrada. Reveja os tipos declarados, incluindo texto, número, inteiro, booleano, objeto e matriz, também quando aparecem em valores aninhados. Depois confirme as regras de propriedades, como campos obrigatórios e a rejeição de propriedades não declaradas quando essa opção estiver definida no schema.

5. Verifique também as restrições de valores. O schema pode exigir um elemento de uma enumeração, impor valores numéricos mínimos ou máximos e limitar o comprimento mínimo ou máximo de texto. Para matrizes, confirme a regra dos elementos: os itens são validados recursivamente quando existe uma regra de itens adequada.

6. Corrija uma causa de cada vez e execute novamente. Mantenha o schema separado dos dados durante a revisão, para não corrigir acidentalmente o documento errado. Se a indicação mencionar um campo em falta, adicione-o aos dados ou reveja a declaração de obrigatoriedade; se mencionar um tipo, ajuste o valor ou o schema conforme a intenção do contrato.

Como ler o resultado e conhecer os limites

Um resultado válido significa que os dados passaram pelas verificações implementadas para as regras presentes no schema. Um resultado não válido pode resultar de texto JSON mal formado, de um campo obrigatório ausente, de uma propriedade não permitida, de um tipo incompatível ou de uma restrição de valor que não foi cumprida. Se um campo estiver vazio por engano, a ferramenta trata essa situação como dados ou schema em falta, não como uma validação bem-sucedida.

Interprete os detalhes no contexto da estrutura que forneceu. Por exemplo, uma matriz pode falhar porque um dos seus elementos não corresponde à regra aplicada aos itens; um número negativo pode falhar quando existe um limite mínimo; e uma propriedade de texto pode falhar por comprimento ou por não pertencer à enumeração definida.

Esta verificação não deve ser tratada como prova de compatibilidade com todas as funcionalidades do JSON Schema. As capacidades revistas abrangem as regras descritas acima, mas não permitem concluir que referências, composição, formatos ou regras de padrão sejam aplicados.

Exemplo prático

Está a rever um payload de encomenda antes de o enviar para um serviço que exige um identificador inteiro não negativo.

Uma pessoa cola um objeto JSON com um campo numérico negativo no campo dos dados e um schema que declara esse campo como inteiro com valor mínimo igual a zero. Depois executa a validação e consulta os detalhes apresentados.

O resultado apresenta a validade dos dados e detalhes de validação; se houver falha, pode indicar um erro de interpretação, um tipo incompatível, uma propriedade em falta ou uma restrição não cumprida.

Limitações

• As verificações revistas não permitem afirmar cobertura de referências, composição, formatos ou regras de padrão do JSON Schema.

Erros comuns

• Erro: colar o schema no campo dos dados, ou deixar um dos campos vazio. Correção: confirme a separação entre JSON de entrada e JSON Schema e remova espaços sem conteúdo antes de executar a validação.

Perguntas frequentes

É possível validar sem preencher um dos campos?

Sim, desde que os dois campos contenham textos JSON válidos. Se o JSON ou o schema estiver vazio, ou contiver apenas espaços, o resultado indica que o elemento em falta torna os dados não válidos.

Um estado de operação bem-sucedido significa que o JSON é válido?

Não necessariamente. Uma operação pode terminar com estado técnico bem-sucedido mesmo quando os dados falham na validação; leia separadamente o indicador de validade e os detalhes.

Que regras posso verificar no schema?

A ferramenta aplica regras de enumeração, limites numéricos e limites de comprimento de texto quando estão presentes, além das verificações de tipo. Também pode validar propriedades aninhadas e itens de matrizes segundo as regras fornecidas.

A validação cobre todas as funcionalidades do JSON Schema?

Não é possível concluir isso apenas com esta validação. As capacidades revistas não comprovam a aplicação de referências, composição, formatos ou regras de padrão, por isso deve confirmar essas necessidades noutra etapa do seu processo.