Nesta página
A sintaxe indica se um texto pode ser lido como JSON; o JSON Schema verifica requisitos explícitos sobre os valores. Por isso, uma API pode rejeitar um documento que passa na validação de sintaxe. Confira primeiro a sintaxe e depois valide o documento com seu esquema. Um resultado válido comprova apenas as regras presentes nesse esquema e aceitas pelo validador.
| Verificação | Pergunta que responde | O que revisar se falhar |
|---|---|---|
| Sintaxe | Os dois textos podem ser analisados como JSON? | A entrada indicada: documento ou esquema. |
| Esquema aceito | O validador entende o esquema e suas regras? | O draft, as keywords e a forma como foram declaradas. |
| Conformidade | Os valores atendem ao esquema? | O campo e a regra indicados no diagnóstico. |
| Regras de negócio externas | O pedido existe e está autorizado? | A fonte dos dados e as verificações da aplicação. O esquema deste exemplo não responde a essas perguntas. |
Um pedido com sintaxe válida que não atende ao contrato
Este pedido fictício tem sintaxe JSON correta:
{
"id": "00123",
"quantity": "2",
"active": true
}Suponha que o contrato exija uma quantidade inteira de pelo menos uma unidade. Este é o esquema completo para conferir essa exigência:
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"id": { "type": "string", "minLength": 1 },
"quantity": { "type": "integer", "minimum": 1 },
"active": { "type": "boolean" }
},
"required": ["id", "quantity"],
"additionalProperties": false
}A raiz deve ser um objeto. properties descreve os campos: id é uma string não vazia, quantity é um inteiro maior ou igual a 1 e active, quando presente, é um booleano. required torna id e quantity obrigatórios; declarar active em properties não o torna obrigatório. additionalProperties: false proíbe campos fora dessa lista.
A distinção entre tipos e o mínimo inclusivo seguem o JSON Schema draft-07, seções 6.1.1 e 6.2.4. Aqui, "2" é texto. Conter um dígito não faz desse valor um inteiro.
Localize o erro e decida o que corrigir
- Abra o validador de JSON Schema. Cole o esquema completo em Esquema JSON e o pedido original em Documento JSON.
- Escolha Validar. Se alguma entrada não puder ser analisada, resolva primeiro seus erros de sintaxe JSON.
- Com essas entradas, o resultado esperado é uma incompatibilidade de
typeem/quantity, com a regra em/properties/quantity/type. - Confirme no contrato e na fonte que o valor representa uma quantidade. Nesse caso, troque
"2"por2e escolha Validar novamente.
As localizações do diagnóstico são JSON Pointers, não consultas JSONPath. /quantity aponta para o dado; /properties/quantity/type, para a regra do esquema. A tradução da mensagem pode variar, mas essas localizações e a keyword permitem entender o problema.
O documento corrigido fica assim:
{
"id": "00123",
"quantity": 2,
"active": true
}O resultado esperado é válido de acordo com este esquema. id continua sendo uma string e mantém os zeros à esquerda. Não remova as aspas de todo valor que pareça numérico: um identificador não precisa ser uma quantidade. O validador não converte "2" em 2; cabe a você decidir se a alteração faz sentido.
Casos independentes: tipo, mínimo e campo extra
Comece pelo documento corrigido em cada linha, mantendo o mesmo esquema. Desfaça a alteração anterior antes de passar para o próximo caso.
| Alteração única | Resultado esperado | Como agir |
|---|---|---|
Trocar "quantity": 2 por "quantity": "2" |
type em /quantity. |
O texto não atende ao tipo inteiro. Confirme o contrato antes de alterar o dado. |
Trocar "quantity": 2 por "quantity": 0 |
minimum em /quantity. |
O tipo está correto, mas o mínimo é 1. Confira a quantidade na fonte; não invente outra só para passar na validação. |
Adicionar "currency": "MXN" |
additionalProperties, propriedade currency, instância raiz. |
O contrato não aceita esse campo. Verifique se ele está sobrando ou se o esquema precisa mudar; não o apague sem conferir. |
| Manter o documento corrigido | Válido de acordo com o esquema. | As regras declaradas são atendidas, mas a existência e a autorização do pedido não foram verificadas. |
A raiz é representada pelo JSON Pointer vazio (""). São casos separados, não uma saída com vários erros: a ferramenta mostra apenas a primeira incompatibilidade. Ao corrigi-la e validar novamente, você pode encontrar outra.
Quando o problema está no esquema
Um esquema pode ter JSON correto e usar uma keyword que esta ferramenta não aceita. Para observar a diferença, mantenha o pedido corrigido e substitua o esquema por este exemplo propositalmente não aceito:
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"format": "email"
}O resultado esperado é esquema não aceito, por causa de format, antes da avaliação dos dados. Isso não significa que o pedido descumpra o contrato nem que seu identificador deva ser um endereço de e-mail. Restaure o esquema do pedido para continuar.
Esta ferramenta implementa um subconjunto do draft-07. Exige um objeto na raiz do esquema e o URI exato de $schema mostrado acima. Rejeita keywords desconhecidas ou não aceitas, incluindo $ref, format, combinadores e condicionais. Não oferece suporte completo ao draft-07 nem às versões 2019-09 ou 2020-12.
O que um resultado válido comprova
O pedido corrigido atende a este contrato. Isso não comprova que "00123" existe, que há estoque suficiente ou que a pessoa que enviou o pedido tem permissão. Também não confirma que a quantidade copiada corresponde à fonte. Essas verificações continuam sendo responsabilidade da aplicação e da revisão dos dados de origem.
A validação não corrige sintaxe, remove propriedades nem altera a entrada. Além disso, um cancelamento ou um limite atingido deixa a verificação incompleta: não comprova conformidade nem descumprimento do contrato. A página do validador de JSON Schema detalha os limites de tamanho, profundidade e operação, além da rejeição de números que a ferramenta não consegue representar com segurança.