JSON Schema 2020-12: validar o dado antes de ele entrar no sistema
O que é o JSON Schema Draft 2020-12, o que mudou em relação ao 2019-09, como reaproveitar tipos e onde a validação entra no fluxo da empresa.

JSON Schema é um vocabulário para descrever a forma de um documento JSON. O rascunho 2020-12 está no site oficial do JSON Schema, e a página dessa versão traz a data de publicação de 16 de junho de 2022. Os autores listados são Austin Wright, Henry Andrews, Ben Hutton e Greg Dennis.
Para uma empresa, o ganho é prático: o sistema consegue recusar um dado mal formado antes de ele entrar no cadastro, no pedido ou na fila. Este texto mostra o que muda no rascunho 2020-12, como organizar tipos repetidos e onde a validação entra no fluxo. Também diz o que a Wortic publica hoje e o que o post não pode afirmar.
O que o rascunho 2020-12 mudou em relação ao 2019-09?
Segundo a página do rascunho, o 2020-12 é uma atualização abrangente do 2019-09. Ele trata de retornos da comunidade e da experiência de quem implementa, e traz recursos que simplificam a criação de schemas.
A mudança que mais pede atenção é a das listas. A página informa que as palavras items e additionalItems foram substituídas por prefixItems e items. Quem tem um schema antigo com a forma de lista em items precisa reescrever essa parte antes de migrar.
O rascunho também traz referências dinâmicas, com a palavra $dynamicRef, e vocabulários, declarados com $vocabulary. Essas partes servem para quem monta schemas em camadas, e uma equipe pequena pode começar sem elas.
Como organizar tipos repetidos num schema?
Quando o mesmo tipo aparece em vários pontos, como endereço, CNPJ ou valor em dinheiro, o schema ganha com a reutilização. A especificação trata esse caso na seção de reutilização com a palavra $defs. A ideia é definir o tipo uma vez e referenciá-lo onde ele é necessário, em vez de copiar o mesmo bloco em três lugares.
Isso também facilita a manutenção. Quando uma regra muda, a alteração fica num lugar só, e o pedido, o cadastro e a fila passam a seguir a mesma definição.
Onde a validação entra no fluxo da empresa?
A validação deve acontecer na entrada, antes de qualquer gravação. Um agente de IA que envia um pedido, um formulário ou uma chamada de API traz o mesmo risco: o dado chega com um campo errado e alguém precisa corrigi-lo depois. Um schema validado na entrada transfere essa conferência para o começo.
- Escreva o schema do dado de entrada, com os campos que o sistema realmente usa.
- Use $defs para os tipos repetidos, como endereço e CNPJ.
- Valide o dado antes de gravar, com uma biblioteca que declare o rascunho 2020-12.
- Registre o erro com o nome do campo, para que o agente ou a pessoa corrijam a mesma coisa.
Um exemplo: o cadastro de empresa recebe um CNPJ do agente. O schema recusa um CNPJ com formato errado antes da consulta e antes da gravação. A consulta de CNPJ da Wortic também recusa dígitos verificadores que não conferem, com o código cnpj_invalido, e o índice para agentes documenta esse erro. A checagem de formato no schema e a checagem de dígitos na API se somam.
A Wortic usa JSON Schema?
Nas páginas conferidas, o protocolo não aparece com esse nome. O perfil de compras da Wortic, em app.wortic.com/.well-known/ucp, aponta para arquivos de schema do protocolo UCP, hospedados no ucp.dev. A página não diz qual rascunho do JSON Schema esses arquivos usam, então este texto não afirma que é o 2020-12.
O que o post pode dizer sobre a Wortic é isto: a consulta de CNPJ responde com códigos de erro fixos, como cnpj_invalido e termo_curto, e documenta cada um no índice para agentes. Esse contrato de erro é o tipo de regra que um schema descreve do lado de quem integra.
Quais limites o schema não resolve sozinho?
Um schema confere a forma do dado, e não a verdade dele. Um CNPJ pode ter o formato certo e mesmo assim não estar na base. O índice da consulta de CNPJ documenta o código 404 nao_encontrado para um CNPJ válido que não está na base. Por isso, a validação de formato não substitui a consulta à fonte.
Também é preciso separar o que o schema valida do que a regra de negócio decide. Um valor pode ter o tipo certo e ainda estar fora da política da empresa, como um desconto acima do permitido. Essa regra fica no sistema, e o schema cuida apenas da forma.
Há ainda o que a base não traz. A consulta de CNPJ da Wortic diz que faturamento, número de funcionários e dívidas não estão na base. Um schema de cadastro deve deixar esses campos de fora ou marcá-los como indisponíveis, para que ninguém preencha com estimativa.
Por fim, um schema que ninguém atualiza vira documentação antiga. Quando o campo muda, o schema muda junto, na mesma revisão do código que altera o campo.
Como começar sem travar a equipe?
Comece pelo dado que mais causa retrabalho, como o cadastro de empresa ou o endereço. Escreva o schema desse dado e rode a validação em modo de registro por um período, anotando quantos dados chegariam errados. Só depois passe a recusar.
Essa ordem reduz o susto. A equipe vê o número de dados que seriam recusados antes de qualquer recusa de fato, e decide com número na mão. Quando a regra estiver estável, a recusa entra no lugar do registro, e o erro deixa de chegar à gravação.
Vale ainda guardar, junto do schema, um exemplo de dado válido e um de dado recusado. Quem chega ao time depois entende a regra sem ler o código inteiro, e o teste de regressão fica mais simples de escrever. Assim, a equipe revisa a regra pelos exemplos, e não por suposição.
Por onde começar?
A página conectar-ia, em wortic.com.br/conectar-ia, mostra como ligar a conta Wortic a um assistente de IA por um conector. A página de sistemas, em wortic.com.br/sistemas, reúne os sistemas prontos por tipo de negócio. A newsroom, em wortic.com.br/newsroom, reúne os textos sobre protocolos e dados.
Perguntas frequentes
O que muda nas listas do 2019-09 para o 2020-12?
Segundo a página do rascunho, as palavras items e additionalItems foram substituídas por prefixItems e items. Quem tem um schema antigo com a forma de lista precisa reescrever essa parte antes de migrar.
A Wortic publica schemas em JSON Schema 2020-12?
Nas páginas conferidas, a Wortic não diz isso. O perfil UCP aponta para arquivos de schema, mas sem dizer o rascunho usado, então o post não afirma que é o 2020-12.
Preciso validar todo dado que chega de um agente?
Vale validar todo dado que vira gravação, porque é ali que um campo errado causa retrabalho. Quais campos validar é decisão da empresa, e o schema é a forma de deixar essa regra escrita e revisável.
Fontes
Quer isso funcionando na sua empresa?
Um consultor da Wortic olha o seu caso e mostra o caminho, sem compromisso.
Falar com um consultorEquipe editorial
Equipe editorial da Wortic especializada em automacao, IA, ERP, CRM e crescimento operacional.
- Automacao com IA
- Gestao empresarial
- CRM
- ERP
- Marketing digital
