Converter JSON para Python — Gerador de classes

De JSON a classes Python tipadas

Trabalhar com dicionários puros é rápido, até que um erro de digitação no nome de uma chave causa um KeyError três camadas abaixo. Este conversor de JSON para Python gera classes tipadas a partir de um exemplo de JSON, para que seu editor, o verificador de tipos e seus colegas saibam exatamente o que cada payload contém. Cada objeto vira uma classe com atributos anotados, objetos aninhados viram classes próprias, listas são tipadas pelo tipo do elemento e valores que às vezes estão ausentes são tipados como opcionais. As chaves JSON são convertidas para atributos em snake_case, enquanto o código de serialização gerado mantém as chaves originais na comunicação.

A geração é feita pelo quicktype, que mescla todos os elementos de cada array antes de inferir os tipos. Assim, um campo que só aparece em alguns itens ainda é capturado e marcado como opcional, em vez de ser descartado silenciosamente.

Dataclasses, Pydantic e versões do Python

Por padrão, a saída usa classes @dataclass da biblioteca padrão, além de funções from_dict e to_dict que validam e convertem cada campo, então você não precisa de dependências de terceiros. Se seu projeto já usa Pydantic — para corpos de requisição do FastAPI, configurações ou validação — marque Pydantic BaseModel e as classes passam a herdar de BaseModel. O seletor de versão do Python controla a sintaxe de tipos: 3.10+ gera anotações modernas como list[int] e str | None, enquanto alvos mais antigos recorrem ao módulo typing. Marque Classes only para dispensar totalmente os auxiliares de conversão.

Dicas práticas

Use um exemplo que explore os campos opcionais e contenha vários elementos no array, já que a inferência só consegue descrever o que enxerga. Dê à classe raiz o nome do seu domínio — Invoice é mais legível que Root — e o download usará esse nome. Depois de gerar, execute seu formatador e verificador de tipos (Black, Ruff, mypy ou Pyright) e refine o que o exemplo não pôde revelar, como strings que na verdade são enums ou números que deveriam ser Decimal. Toda a análise e geração de código acontece localmente, então você pode colar com segurança respostas que contenham dados de clientes.