Gerador de esquema JSON

Para que serve o JSON Schema

JSON Schema é uma forma declarativa de descrever como deve ser um documento JSON: que propriedades tem, que tipos essas propriedades guardam, o que é obrigatório versus opcional e que valores são válidos. É o equivalente do mundo JSON ao XSD para XML ou a uma definição de tabela de base de dados. O projecto oficial vive em json-schema.org.

Onde o vai encontrar:

• Contratos de API. O OpenAPI 3.1 (lançado em Fevereiro de 2021) embebe directamente o JSON Schema: cada corpo de pedido e corpo de resposta numa spec de API moderna é descrito com um fragmento de JSON Schema.
• Autocompletar e validação no IDE. O settings.json do VS Code, os package.json e tsconfig.json do seu projecto, os ficheiros workflow.yml do GitHub Actions, todos autocompletam e fazem lint contra JSON Schemas publicados.
• Validação do lado do servidor. Express / Fastify / Spring / Flask / FastAPI / Echo, todos integram com validadores de JSON Schema (AJV, jsonschema, fastjsonschema) para rejeitar corpos de pedido malformados antes de chegarem à lógica de negócio.
• Geração de código. Ferramentas como quicktype, json-schema-to-typescript e datamodel-code-generator transformam um schema em structs Go, tipos TypeScript, dataclasses Python, POJOs Java, etc., fornecendo tipos agnósticos da linguagem a partir de uma única fonte.
• Documentação. Um schema serve também como documentação legível por máquina para qualquer dado em forma de JSON que publique.

Os drafts que vai ver por aí

A especificação do JSON Schema foi publicada como uma série de drafts. O draft estável actual é o 2020-12 (segundo a página oficial da spec: «The current version is 2020-12»). Os drafts que pode encontrar:

• Draft 4, antigo mas ainda em uso; o OpenAPI 3.0 usou um subconjunto estendido do JSON Schema Specification Wright Draft 00 (por vezes informalmente chamado Draft 5), próximo mas não idêntico ao Draft 4.
• Draft 6, Draft 7, o Draft 7 (2018) foi o draft de produção dominante durante anos e ainda é muito comum em ferramentas legacy.
• Draft 2019-09, primeiro draft a usar a convenção de identificador ano-mês; introduziu $defs ao lado da palavra-chave legacy definitions.
• Draft 2020-12, o draft estável actual e o que este gerador emite. Alinhado com o OpenAPI 3.1.

Em caso de dúvida, escolha o draft que corresponda ao seu validador. O AJV (o validador JavaScript mais popular) suporta os Drafts 04, 06, 07, 2019-09 e 2020-12 com opt-in explícito. O jsonschema em Python faz o mesmo. Se não sabe o que o seu consumidor a jusante quer, 2020-12 é um padrão seguro para trabalho novo.

Os tipos embutidos

O JSON Schema descreve sete tipos base correspondentes às espécies de valor do JSON:

As palavras-chave de composição permitem-lhe misturar e combinar: oneOf (exactamente um), anyOf (pelo menos um), allOf (todos), not (o inverso). Mais enum para uma lista finita de valores permitidos e const para um único valor fixo.

O que um schema autogerado pode e não pode dizer-lhe

Inferir um schema a partir de um único exemplo JSON é poderoso mas limitado. O gerador consegue detectar:

• O tipo de cada valor folha (string vs number vs boolean vs array vs object).
• A estrutura de objectos e arrays aninhados.
• As chaves que aparecem no exemplo (e marcá-las como required se optar por isso).

Não consegue detectar:

• Campos opcionais. Uma chave no seu exemplo pode ser opcional na spec real, mas um único exemplo não consegue dizer-lhe quais. Tudo parece obrigatório por defeito.
• Pistas de formato. A string "2024-04-12" parece uma data, mas também pode ser uma label de texto livre que por acaso parece uma data. Adicione format: date à mão se o campo for mesmo uma data.
• Restrições de validação. Comprimento máximo, valores enum permitidos, padrões regex: todos precisam de input humano.
• Strings de documentação. title, description e examples em cada campo melhoram a experiência do programador mas precisam de curadoria.
• Variantes. Se um campo pode ser string ou número conforme o contexto, um único exemplo escolhe um e perde o outro. Combine vários exemplos ou use oneOf manualmente.

Trate a saída como um ponto de partida a 70%. As adições valiosas (que campos são realmente obrigatórios, que formatos de string aplicam-se, que intervalos de valor são permitidos, o que cada campo significa) são a fase de curadoria humana.

Duas armadilhas subtis que vale a pena conhecer

• O format é consultivo por defeito em 2020-12. O vocabulário format-annotation marca format: email como uma pista, não como uma regra de validação rígida, a menos que o seu validador opte explicitamente por format-assertion. Por isso uma string que não corresponde à regex de email continua a passar por defeito. O modo strict do AJV e o pacote ajv-formats adicionam validação completa de formato; verifique os defaults do seu validador antes de confiar em verificações de formato para input crítico de segurança.
• additionalProperties: false não coopera bem com allOf. Se compõe schemas com allOf para validação tipo herança, additionalProperties: false num ramo não vê propriedades definidas em ramos irmãos, por isso campos legítimos falham na validação. A correcção em Draft 2019-09+ é unevaluatedProperties: false, que tem consciência da composição.

JSON Schema vs Zod / Joi / Yup vs tipos TypeScript

Várias tecnologias sobrepõem-se ao papel do JSON Schema; cada uma tem um sweet spot diferente:

• JSON Schema. JSON declarativo, validação em runtime, agnóstico da linguagem. Ganha onde os contratos de API atravessam fronteiras linguísticas (p. ex. um servidor Go, um pipeline de dados Python e um frontend TypeScript a consumir todos a mesma API).
• Tipos TypeScript. Apenas em tempo de compilação. Lindos para segurança de tipos in-process dentro de uma codebase TS mas desaparecem em runtime, não fornecendo validação do JSON que entra. Ferramentas como json-schema-to-typescript geram tipos a partir de um schema para o melhor dos dois mundos.
• Zod / Joi / Yup. Validação runtime code-first em JavaScript / TypeScript, com inferência TypeScript embutida. Linguagem única, mas excelente experiência de programador dentro dela. Os schemas são objectos JS, não JSON portátil.
• Pydantic / Marshmallow. Os equivalentes em Python: validação runtime baseada em classes com type hints do Python.

Se o seu schema precisa de ser consumido por várias linguagens ou por ferramentas (IDEs, tooling de OpenAPI, geradores de código), JSON Schema é o lar certo. Se fica dentro de uma só linguagem, a opção nativa dessa linguagem é geralmente mais agradável de escrever.

Casos de uso comuns

• Iniciar uma spec de OpenAPI. Cole uma resposta de API real, gere o schema, coloque-o no seu components.schemas.
• Gerar tipos TypeScript / Go / Python via quicktype ou semelhante, fornecendo tipos agnósticos da linguagem a partir de uma única fonte.
• Validar input não confiável num endpoint de servidor com AJV / jsonschema / Pydantic.
• Escrever autocompletar de IDE para um formato de configuração personalizado. O VS Code, os IDEs JetBrains e outros lêem JSON Schemas para alimentar o autocompletar de ficheiros JSON.
• Documentar a forma de um ficheiro de configuração para consumidores a jusante.
• Migrar entre formatos de dados. Um JSON Schema gerado a partir de uma fonte pode impulsionar validação, transformação ou documentação a jusante.

Erros comuns

1. Tratar o schema autogerado como a spec final. É um ponto de partida. Adicione pistas de formato, marque campos genuinamente opcionais, adicione documentação, defina intervalos de valor.
2. Falhar a declaração $schema. Os validadores usam-na para saber que draft aplicar. Inclua-a sempre no topo do schema.
3. Tratar required como um atributo por propriedade. Ao contrário do XSD ou dos schemas Mongoose, o required do JSON Schema é um array ao nível do objecto pai a listar os nomes das propriedades obrigatórias.
4. Esquecer-se de additionalProperties: false quando quer validação estrita. O default é true, ou seja, chaves desconhecidas são silenciosamente permitidas.
5. Confundir enum com examples. enum = a lista de valores permitidos (validação). examples = valores de amostra apenas para documentação (sem efeito de validação).
6. Assumir que format é aplicado. Por defeito em Draft 2020-12 é uma anotação, não uma asserção; a sua regex de email não corre a menos que opte por isso.
7. Inferir opcionalidade a partir de um único exemplo. Cada chave do seu exemplo torna-se obrigatória por defeito. Specs reais quase sempre têm campos opcionais; remova-os do array required como parte da curadoria.

Mais perguntas frequentes

O schema vai funcionar com OpenAPI 3.1?

Sim. O OpenAPI 3.1 (lançado em Fevereiro de 2021) alinhou completamente a sua linguagem de schema com o JSON Schema Draft 2020-12, que é o que este gerador emite. Coloque o schema em components.schemas no seu documento OpenAPI e referencie-o via $ref. O OpenAPI 3.0 mais antigo usava um subconjunto anterior; pode precisar de ajustar se está a apontar para 3.0.

Posso gerar tipos na minha linguagem a partir deste schema?

Sim. quicktype gera TypeScript, Go, Python, Java, C#, Swift, Kotlin, Rust, Elm e outros a partir de um JSON Schema. json-schema-to-typescript é uma alternativa específica para JS. A maior parte das linguagens modernas tem pelo menos uma ferramenta schema-para-tipos; o schema gerado funciona como input para todas elas.

Qual a diferença entre $defs e definitions?

Ambos são sítios para colocar sub-schemas reutilizáveis que pode $referenciar noutro lado do documento. definitions é o nome legacy, usado nos Drafts 04, 06 e 07. $defs é o nome actual, introduzido no Draft 2019-09 e a continuar em 2020-12. Funcionalmente equivalentes, mas use $defs para trabalho novo.

O meu JSON é enviado para algum sítio?

Não. A geração de schema corre inteiramente no seu navegador. O JSON colado é parsed localmente, percorrido e emitido como um schema na textarea de saída. Nada é enviado para um servidor, registado ou guardado depois de fechar o separador. Isto importa porque os exemplos JSON contêm muitas vezes dados reais (registos de cliente, respostas de API internas, info de funcionários) que não quer que passem por um terceiro.

Por que é que o schema do meu array só descreveu o primeiro elemento?

A inferência a partir de um único exemplo trata os arrays como homogéneos: olha para o primeiro elemento e assume que o resto corresponde. Se o seu array real pode conter formas diferentes, vai precisar de escrever os items como { "oneOf": [...] } à mão. Ou correr o gerador em cada variante separadamente e combinar os schemas.

Devo usar um gerador, ou escrever o schema à mão?

Para um schema pequeno que controla de ponta a ponta, escrever à mão ensina-lhe a spec mais depressa. Para uma resposta de API grande com dezenas de objectos aninhados, gerar leva-o a um rascunho em segundos e gasta o tempo poupado a curar restrições, descrições e arrays required. A maior parte dos programadores em activo faz ambas: gerar, depois curar.