Gerador de JSON Schema

Gere um JSON Schema a partir de um payload de exemplo. Draft 2020-12 por padrão, com 2019-09 e draft-07 disponíveis.

Gerar um schema a partir de uma amostra só é inferência, e é na inferência que essas ferramentas mentem baixinho. Todo palpite que esta aqui dá é reportado para você, e o maior deles é tratado de forma diferente da maioria dos geradores.

O problema dos campos obrigatórios

A maioria dos geradores lê o primeiro elemento de um array e toma as chaves dele como o formato. Isso produz um schema que rejeita dados válidos assim que um registro posterior tem um campo opcional que faltava no primeiro.

Este gerador mescla todos os elementos. Uma chave presente em todos entra em required; uma chave presente em alguns aparece em properties mas não em required. Essa única diferença é o motivo de usar um gerador em vez de escrever o schema à mão depois de olhar rapidamente o payload.

As outras inferências, todas reportadas

integer contra number

Um campo só é tipado como integer quando todo valor observado era um. Um único decimal em qualquer lugar torna o campo inteiro um number.

Campos nuláveis

Um campo visto como string e como null vira "type": ["string", "null"], e não um campo descartado nem simplesmente "string".

format

Emitido só quando todo valor observado casa: date-time, date, time, email, uuid, ipv4 ou uri. Um único valor fora do padrão e a anotação cai.

enum

Sugerido em vez de assumido, e só quando um conjunto pequeno de valores se repete. Desligado por padrão, porque um enum inferido de uma amostra é um palpite sobre um domínio que você não viu inteiro.

Inteiros inseguros

Tipados como integer e reportados, porque um validador rodando sobre um parser JavaScript já perdeu o valor antes de a validação começar.

A palavra-chave format não valida

Isso surpreende as pessoas e coloca validação quebrada em produção. Nos drafts 2019-09 e 2020-12, format é por padrão uma ANOTAÇÃO e não uma asserção. A maioria dos validadores aceita numa boa "nao-e-um-email" para um campo marcado como "format": "email", a menos que a asserção de format esteja explicitamente ligada.

Se você precisa que isso valha, acrescente um pattern explícito ao lado do format, ou configure o seu validador para o comportamento de asserção e confira se ele suporta.

Uma ressalva sobre validar o resultado

Se você levar este schema para o Ajv, o validador JavaScript mais comum, preste atenção no ponto de entrada. A exportação ajv padrão suporta só draft-07. O draft 2020-12 precisa de ajv/dist/2020 e o 2019-09 precisa de ajv/dist/2019.

Errar isso faz um schema 2020-12 usando prefixItems ser validado com a semântica do draft-07, onde prefixItems é uma palavra-chave desconhecida e é ignorada. Aí o seu validador reporta "válido" sobre dados que não são. Isso é pior que um erro, e é fácil de fazer sem querer.

How to do this in code

Gerando e validando em código.

// The entry point matters. This is the 2020-12 one.
import Ajv2020 from 'ajv/dist/2020';
import addFormats from 'ajv-formats';

const ajv = new Ajv2020({ allErrors: true });
addFormats(ajv);   // without this, "format" does nothing at all

const validate = ajv.compile(schema);
if (!validate(data)) console.error(validate.errors);

from jsonschema import Draft202012Validator

validator = Draft202012Validator(schema)
for error in sorted(validator.iter_errors(data), key=lambda e: e.path):
    print(list(error.path), error.message)

# Format checking is opt-in here too
from jsonschema import FormatChecker
Draft202012Validator(schema, format_checker=FormatChecker()).validate(data)

import "github.com/santhosh-tekuri/jsonschema/v6"

c := jsonschema.NewCompiler()
sch, err := c.Compile("schema.json")
if err := sch.Validate(data); err != nil {
    fmt.Println(err)
}

Perguntas frequentes

Qual draft devo usar?

Draft 2020-12 para qualquer coisa nova; é o draft publicado atual e o que o OpenAPI 3.1 acompanha. O draft-07 continua sendo o mais suportado em ferramentas antigas. Note que o identificador 2020-12 se refere a quando o draft foi fechado: os documentos naquela URI foram republicados pela última vez em junho de 2022, o que é uma correção e não uma versão nova.

Por que um campo está faltando em required?

Porque ele estava ausente em pelo menos uma amostra. Isso é o gerador te dizendo algo útil. Se o campo for mesmo obrigatório, dê a ele uma amostra em que todo registro o tenha, ou acrescente ao required à mão.

Ele consegue gerar a partir de várias amostras?

Consegue, e você deveria fazer isso. Ponha as suas amostras em um array e cole o array. Mesclar em muitos registros é exatamente o que torna required e a nulabilidade precisos.