Neste artigo
O que e JSON Schema?
JSON Schema e um vocabulario que permite descrever a estrutura e regras de validacao 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 restricoes se aplicam -- transformando contratos de dados informais em especificacoes legiveis por maquinas.
A versao mais utilizada e Draft-07, embora versoes mais recentes (2019-09, 2020-12) adicionem funcionalidades como esquemas condicionais e referencias 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 geracao de esquemas
Um gerador de esquemas examina seu JSON de exemplo e produz um esquema que o validaria. O processo envolve inferencia de tipos, analise de estrutura e detecao de restricoes.
- Inferencia 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
- Detecao 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.
- Validacao de requisicoes API -- valide payloads recebidos contra um esquema antes do processamento, rejeitando requisicoes mal formadas cedo e fornecendo mensagens de erro claras aos consumidores da API
- Geracao de formularios -- bibliotecas UI como react-jsonschema-form e vue-form-generator podem renderizar formularios automaticamente a partir de um JSON Schema, mantendo a validacao 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 integracao, capturando mudancas incompativeis antes de chegarem a producao
Perguntas frequentes
Qual versao draft do JSON Schema devo usar?
Draft-07 e a opcao mais segura para ampla compatibilidade -- a maioria dos validadores, geradores de formularios e geradores de codigo o suportam totalmente. Use 2020-12 se precisar de recursos avancados como $dynamicRef, prefixItems ou unevaluatedProperties. Sempre verifique se sua biblioteca de validacao suporta o draft escolhido.
Como combinar multiplos esquemas?
JSON Schema fornece palavras-chave de composicao: 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 definicoes de esquema reutilizaveis. Por exemplo, um esquema User poderia usar allOf para combinar um PersonSchema base com campos de autenticacao 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 permanecam sincronizados com os contratos do backend. Isto e especialmente util em monorepos onde o esquema serve como a unica fonte de verdade tanto para validacao de API quanto para verificacao de tipos do lado do cliente.