Gerando tipos TypeScript a partir de JSON: um guia prático

Como funciona a inferência JSON-para-TypeScript

Um gerador percorre a árvore de valores JSON e mapeia cada tipo JavaScript para seu equivalente TypeScript: string continua string, number continua number, boolean continua boolean, null vira null (ou é mesclado numa union), arrays viram T[] onde T é inferido dos elementos, e objetos viram interfaces aninhadas.

{
  "id": 42,
  "email": "ada@example.com",
  "isActive": true,
  "roles": ["admin", "editor"],
  "profile": {
    "displayName": "Ada",
    "avatarUrl": null
  }
}

interface Root {
  id: number;
  email: string;
  isActive: boolean;
  roles: string[];
  profile: {
    displayName: string;
    avatarUrl: string | null;
  };
}

Onde a inferência precisa adivinhar

Campos opcionais vs. sempre presentes: uma única amostra JSON não consegue dizer ao gerador se avatarUrl às vezes está totalmente ausente (o que deveria ser avatarUrl?: string | null) ou sempre presente mas às vezes null. Alimente o gerador com algumas amostras representativas, ou marque manualmente um campo como opcional após a geração, se você sabe que a API o omite em certas condições.

Números que são IDs vs. quantidades: o JSON tem um único tipo numérico, mas o TypeScript não consegue distinguir um ID inteiro de um preço de ponto flutuante sem contexto extra. Alguns geradores oferecem branded types ou unions literais para isso; a maioria apenas emite number e deixa a distinção com você.

Arrays vazios: um array sem elementos ("tags": []) não dá ao gerador nenhuma pista do tipo do elemento, então ele recorre a unknown[] ou any[]. Aponte o gerador para uma amostra em que o array tenha itens, ou anote-o à mão depois.

Unions de literais de string: o gerador vai inferir como string comum um campo status que contém um de "pending" | "active" | "closed", a menos que veja todos os valores possíveis na amostra. Mesmo assim, a maioria dos geradores usa por padrão o tipo string mais amplo, a não ser que você ative a inferência de union literal.

Datas: o JSON não tem tipo de data, então timestamps chegam como strings (ISO 8601) ou números (epoch Unix). Um gerador tipa um campo de data como string ou number, não como Date, e você ainda precisa analisá-lo depois do fetch.

A mesma ideia em outras linguagens

A lógica de inferência (percorrer a árvore, mapear tipos, nomear objetos aninhados) é a mesma para qualquer linguagem-alvo; só a sintaxe de saída muda. Um struct Go recebe o mesmo mapeamento de campos com struct tags para os nomes das chaves JSON; uma dataclass Python recebe type hints e um wrapper Optional[...] quando necessário; uma classe Java ou C# recebe campos tipados e getters/setters ou records. Se seu time trabalha em várias linguagens contra a mesma API, gere os tipos de cada uma a partir da mesma amostra JSON para que fiquem coerentes.

type Root struct {
	ID       int     `json:"id"`
	Email    string  `json:"email"`
	IsActive bool    `json:"isActive"`
	Roles    []string `json:"roles"`
	Profile  struct {
		DisplayName string  `json:"displayName"`
		AvatarURL   *string `json:"avatarUrl"`
	} `json:"profile"`
}

Antes de confiar nos tipos gerados

Trate os tipos gerados como ponto de partida e termine o contrato você mesmo. Antes de fazer commit, confirme os campos opcionais com a documentação da API (uma amostra não basta), troque por unions literais os campos string vagos que guardam enums, verifique se campos de array vazio receberam um tipo de elemento real a partir de uma amostra melhor, e gere de novo sempre que a API upstream adicionar ou renomear um campo, em vez de remendar a interface à mão.