Como gerar um schema JSON a partir de um exemplo

Quando usar o gerador de schema JSON

Um schema JSON descreve a estrutura esperada para dados JSON. Esta ferramenta cria uma representação em JSON Schema a partir de um exemplo fornecido, o que é útil quando precisa de documentar rapidamente a forma de um objeto, de uma lista ou de um valor simples. O ponto de partida é sempre um exemplo JSON bem formado, não uma descrição escrita das regras do seu sistema.

Pode fornecer um objeto com propriedades, uma lista ou um valor primitivo. Se incluir um título, este será usado no resultado; se deixar o título vazio, é aplicado o título predefinido “Generated Schema”. Quando o campo principal do exemplo está em branco, também pode ser considerada a primeira entrada adequada entre json, data, text, input, value ou sample, caso essa entrada esteja disponível.

Passos para gerar o schema

Prepare uma amostra JSON válida. Para um objeto, coloque as propriedades e os respetivos valores entre chavetas, com nomes e textos entre aspas. Para uma lista, use parênteses retos e separe os elementos por vírgulas. Não introduza comentários nem vírgulas depois do último elemento.
Abra o gerador e cole a amostra no campo destinado aos dados. O valor principal é recebido como texto. Se o campo estiver vazio, confirme se existe uma entrada alternativa adequada com um dos nomes aceites: json, data, text, input, value ou sample. Sem uma amostra utilizável, a operação falha.
Se quiser identificar o resultado, preencha o campo de título. Um título vazio não produz um campo vazio: é substituído por “Generated Schema”. Se não precisar de um nome específico, pode deixar esse campo sem conteúdo.
Execute a geração. A ferramenta analisa o texto como JSON e cria uma representação JSON Schema do valor analisado. Se o texto estiver malformado, é rejeitado em vez de ser convertido.
Leia e copie o schema apresentado. Verifique se a estrutura inferida corresponde ao uso que pretende documentar antes de a integrar noutro fluxo. Para entradas grandes, tenha em conta que a ferramenta rejeita dados cuja codificação UTF-8 exceda 1 000 000 de bytes.

Como interpretar o resultado

Num objeto JSON, cada membro observado origina um schema de propriedade. Os nomes observados são incluídos como obrigatórios e as propriedades adicionais são impedidas no schema gerado. Isto descreve a amostra fornecida, por isso deve incluir nela os campos que quer ver representados.

Numa lista, o resultado é um schema de array. Uma lista vazia fica com um schema de itens sem restrições específicas; quando existem elementos com estruturas diferentes, essas estruturas são combinadas com anyOf, depois de removidos schemas duplicados. Valores nulos, booleanos, inteiros e números com casas decimais são inferidos, respetivamente, como null, boolean, integer e number.

Os textos são inferidos como strings e podem receber os formatos email, uuid, uri, ipv4, date-time, date ou time quando correspondem aos padrões reconhecidos pela ferramenta. O resultado inclui o identificador do JSON Schema draft-07. Ainda assim, um exemplo não expressa necessariamente todas as regras que deseja impor; reveja o resultado e acrescente ou ajuste restrições quando o seu caso exigir mais do que a estrutura observada.

Exemplo prático

Uma pessoa quer documentar a estrutura mínima observada num registo simples de nome e idade.

Cole a amostra {"nome":"Ana","idade":30} no campo de dados, deixe o título vazio e execute a geração.

O resultado tem a forma de um schema de objeto, com schemas para nome e idade; os dois nomes observados aparecem como obrigatórios e as propriedades adicionais ficam impedidas.

Limitações

O resultado é inferido a partir da amostra fornecida. Pode não representar regras que não estejam visíveis nessa amostra, como condições adicionais ou variações ainda não observadas.

Erros comuns

O texto é rejeitado: a amostra contém JSON malformado, por exemplo, uma chave sem aspas ou uma vírgula a mais. Corrija a sintaxe e volte a executar a geração.

Perguntas frequentes

Posso gerar um schema a partir de qualquer texto?

Sim, desde que o texto fornecido seja JSON válido e possa ser analisado. JSON malformado é rejeitado, e uma entrada sem dados utilizáveis também faz a operação falhar.

O que acontece se não preencher o título?

Pode deixar o título vazio. Nesse caso, o resultado usa “Generated Schema” como título predefinido.

Como são tratadas as listas JSON?

A ferramenta infere a estrutura a partir dos elementos observados. Uma lista vazia fica com um schema de itens sem restrições específicas, enquanto elementos com schemas diferentes podem ser combinados com anyOf.