Esquema JSON a JSON: da carga útil da amostra ao contrato

Que inferência pode e não pode ver

A partir de um único documento, um bom conversor deriva tipos, aninhamentos, formas de itens de array e nomes de propriedades com precisão. O que não pode derivar é a intenção. Ele não sabe que um campo é opcional porque esse registro específico o incluiu, que uma string é um endereço de e-mail, que um número é um número inteiro positivo ou que um valor vem de um conjunto fixo. Tudo o que é derivado é, portanto, marcado com `required`, que é o padrão correto para uma minuta de contrato e a coisa errada para enviar sem ser examinada.

Protegendo o esquema gerado

1. Compare duas ou três amostras reais: as chaves que faltam em qualquer amostra devem cair em `required`.
2. Adicione `format` onde o significado é conhecido – `date-time`, `email`, `uri`, `uuid`, `ipv4`.
3. Transforme conjuntos abertos em valores `enum` quando o campo realmente tiver um vocabulário fixo, como um status ou região.
4. Aperte os números com `minimum`, `maximum` e `multipleOf` para que uma quantidade negativa não possa ser validada.
5. Adicione `additionalProperties: false` somente quando chaves desconhecidas precisarem ser rejeitadas — caso contrário, deixe o esquema aberto para compatibilidade futura.

Obrigatório é uma promessa, não uma observação. Marcar um campo como obrigatório porque sua única amostra o continha é a maneira mais comum de um esquema inferido quebrar uma integração real.

Onde o esquema ganha seu sustento

O valor prático aparece nos limites: validar uma carga útil de webhook antes de confiar nela, verificar arquivos de fixture no CI para que os testes falhem em dados malformados em vez de confundir erros nulos, documentar uma resposta API para pessoas que nunca lerão o código do servidor e gerar clientes digitados. Um esquema JSON também é a maneira mais barata de impedir que uma mudança de configuração altere silenciosamente uma resposta pública, porque o validador a detecta em tempo de construção e não em produção.

                {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "email"],
  "properties": {
    "id": { "type": "string", "format": "uuid" },
    "email": { "type": "string", "format": "email" },
    "plan": { "type": "string", "enum": ["free", "pro", "team"] }
  }
}
              

Mantenha-o no controle de versão

Os esquemas gerados mudam no momento em que ninguém os possui. Confirme o arquivo protegido próximo ao código que produz os dados, faça referência a ele a partir do validador no CI e gere novamente somente quando o contrato realmente mudar — tratando o esquema como a fonte da verdade para a forma e a amostra como evidência, e não o contrário.

Inferência no navegador

Cargas reais estão cheias de identificadores, e-mails e tokens, portanto, uma conversão de esquema de JSON para JSON que carrega a amostra está entregando dados de produção para uma operação puramente mecânica. A inferência local mantém a carga útil na guia, permite colar um registro de cliente sem pensar duas vezes e funciona com a rede cortada.