Neste artigo
O que e JSON Schema?
JSON Schema e um vocabulario que permite descrever a estrutura e regras de validação para dados JSON. Escrito em JSON, um esquema define quais propriedades um objeto pode ter, quais tipos sao permitidos, quais campos sao obrigatorios e quais restrições se aplicam -- transformando contratos de dados informais em especificações legiveis por maquinas.
A versão mais utilizada e Draft-07, embora versões mais recentes (2019-09, 2020-12) adicionem funcionalidades como esquemas condicionais e referências dinamicas. Um gerador de JSON Schema automatiza o processo tedioso de escrever esquemas manualmente -- analisa dados JSON de exemplo e infere automaticamente os tipos, estrutura e campos obrigatorios.
Como funciona a geração de esquemas
Um gerador de esquemas examina seu JSON de exemplo e produz um esquema que o validaria. O processo envolve inferência de tipos, analise de estrutura e deteção de restrições.
- Inferência de tipos -- cada valor e inspecionado para determinar seu tipo JSON (string, number, integer, boolean, null, array, object) e o esquema atribui a palavra-chave de tipo correspondente
- Analise de estrutura aninhada -- objetos sao analisados recursivamente para gerar subesquemas para cada propriedade, e arrays sao inspecionados para inferir o esquema de itens a partir de seus elementos
- Deteção de campos obrigatorios -- todas as propriedades presentes no exemplo sao tipicamente marcadas como obrigatorias, ja que o gerador assume que o exemplo representa uma instancia valida completa
Experimente gratuitamente — sem cadastro
Gerar um JSON Schema →Quando usar JSON Schema
JSON Schema e uma ferramenta fundamental para qualquer projeto que envia ou recebe dados JSON.
- Validação de requisições API -- valide payloads recebidos contra um esquema antes do processamento, rejeitando requisições mal formadas cedo e fornecendo mensagens de erro claras aos consumidores da API
- Geração de formularios -- bibliotecas UI como react-jsonschema-form e vue-form-generator podem renderizar formularios automaticamente a partir de um JSON Schema, mantendo a validação do backend e a interface do frontend sincronizadas
- Testes de contrato em CI/CD -- verifique que as respostas da API correspondam ao esquema esperado em testes de integração, capturando mudanças incompativeis antes de chegarem a produção
Perguntas frequentes
Qual versão draft do JSON Schema devo usar?
Draft-07 e a opção mais segura para ampla compatibilidade -- a maioria dos validadores, geradores de formularios e geradores de código o suportam totalmente. Use 2020-12 se precisar de recursos avançados como $dynamicRef, prefixItems ou unevaluatedProperties. Sempre verifique se sua biblioteca de validação suporta o draft escolhido.
Como combinar multiplos esquemas?
JSON Schema fornece palavras-chave de composição: allOf requer que todos os subesquemas correspondam, anyOf requer que pelo menos um corresponda, e oneOf requer que exatamente um corresponda. Use $ref para referenciar definições de esquema reutilizaveis. Por exemplo, um esquema User poderia usar allOf para combinar um PersonSchema base com campos de autenticação adicionais.
E possivel gerar tipos TypeScript a partir de um JSON Schema?
Sim. Ferramentas como json-schema-to-typescript e quicktype convertem JSON Schemas em interfaces TypeScript, garantindo que os tipos do frontend permaneçam sincronizados com os contratos do backend. Isto e especialmente util em monorepos onde o esquema serve como a unica fonte de verdade tanto para validação de API quanto para verificação de tipos do lado do cliente.