Artigos

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.

Por Equipe Wortic 7 min de leitura

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.

  1. Escreva o schema do dado de entrada, com os campos que o sistema realmente usa.
  2. Use $defs para os tipos repetidos, como endereço e CNPJ.
  3. Valide o dado antes de gravar, com uma biblioteca que declare o rascunho 2020-12.
  4. 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

Conheça: Use a Wortic dentro do Claude e do ChatGPT.

Quer isso funcionando na sua empresa?

Um consultor da Wortic olha o seu caso e mostra o caminho, sem compromisso.

Falar com um consultor

Equipe editorial

Equipe editorial da Wortic especializada em automacao, IA, ERP, CRM e crescimento operacional.

  • Automacao com IA
  • Gestao empresarial
  • CRM
  • ERP
  • Marketing digital

Isso funcionando no seu negócio.

Um consultor mostra o sistema do seu ramo, com a IA dentro.