# Da API response a tipi: TS interface, Go struct, PHP class

> Genera tipi TypeScript, Go struct, PHP class da JSON online. Type inference automatica con nested objects, array element, optional/nullable.

Strumento gratuito nel browser (nessun upload): https://www.mauriziofonte.it/strumenti/genera-tipi-da-json

Da un payload JSON di esempio, genera **type definitions** per TypeScript (interface), Go (struct con tag json), PHP (class con typed properties readonly e constructor promotion). Type inference automatica per primitivi, oggetti annidati e array (element type derivato dal primo elemento). Pensato per modellare API response in client tipizzati senza scrivere a mano: incolli il payload reale che ricevi da un'API, scegli il target language e ottieni le definizioni di tipo coerenti.

## Come usare il generator

1. **Incolla il JSON** - Inserisci un payload JSON rappresentativo. Idealmente: la response di un endpoint reale, non un mock-up. Type inference funziona meglio con dati reali (capisce nullability, optional, array element shape).
2. **Imposta il nome del tipo root** - Default 'Root'. Cambialo nel nome semantico (es. 'UserResponse', 'OrderEvent', 'WebhookPayload'). Il nome viene usato come prefix per i tipi annidati (es. UserAddress, UserOrders).
3. **Genera i tipi** - Bottone 'Genera': produce 3 output paralleli (TS interface, Go struct, PHP class) tutti basati sulla stessa type inference. I tab in alto switchano la visualizzazione.
4. **Copia in progetto** - Il bottone Copia copia il codice del tab attivo. Da incollare in un file.ts /.go /.php nel tuo progetto. Eventuali aggiustamenti manuali (jsdoc, validation, default values) vanno aggiunti dopo.

## Perché un type generator multi-target

**Type-first development.** API moderne emettono JSON, ma client moderni (TS, Go, PHP 8+) preferiscono tipi statici. Scrivere a mano interfacce per ogni payload è tedioso e error-prone. Un generator automatico prende un sample JSON e produce tipi pronti, riducendo il time-to-first-call da minuti a secondi.

**Multi-target rationale.** Tre target coprono il 90% dei backend italiani moderni: TypeScript (frontend Vue/React/Angular + Node backend), Go (microservizi cloud-native), PHP 8.x (Laravel/Symfony). Generare tutti e tre da un singolo input è utile in team eterogenei dove la stessa API serve client diversi.

**Type inference euristica.** Tipi inferiti dal primo valore visto. Limitazioni: array misti (es. `[1, "two", true]`) tipizzati come union/any/mixed; null come optional; numeri integer-only diventano `int`/`number`, float-only diventano `float`/`number`; mixed integer+float diventano `float`. Per casi più complessi (oneOf, discriminated union) serve definire i tipi a mano partendo dall'output generato.

## Glossario

- **Type inference**: Processo automatico di derivazione dei tipi da dati di esempio. Distinto da type checking (verifica statica): qui la inference produce un type definition partendo da un sample concreto.
- **Discriminated union**: Pattern dove un tipo ha varianti distinte da un campo discriminator (es. `{type: "a", a_field:...}` vs `{type: "b", b_field:...}`). Non gestito automaticamente da inference da singolo sample (richiede multi-sample analysis).
- **Constructor promotion (PHP 8)**: Sintassi PHP 8.0+ che permette di dichiarare e assegnare proprietà nel constructor con visibility inline: `public function __construct(public string $name, public int $age)`. Usata nei tipi PHP generati per ridurre boilerplate.
- **Struct tag (Go)**: Metadata stringa associato a un field di struct, letto via reflection. `json:"field_name"` serve a encoding/json per mapping field  chiave JSON. Generator emette automaticamente il tag json basato sulla chiave originale.
- **Readonly properties (PHP 8.1+)**: Modificatore `readonly` che rende immutable una property dopo l'init nel constructor. Best practice per DTO/value object derivati da JSON immutabile. Generator emette readonly di default.
- **Optional vs nullable**: TypeScript: `field?: T` (può mancare) vs `field: T | null` (presente ma null). Sono distinti. Generator emette `field?: T | null` quando il sample mostra `null` (entrambe le possibilità).

## Domande frequenti

### Posso usare il generator con qualunque JSON?

Sì, accetta qualunque JSON valido. Limite pratico ~5MB di input (oltre il browser potrebbe diventare lento). Per array al top-level, il generator inferisce il tipo dell'elemento e produce `type Root = ElementType[]`.

### Type inference è deterministica?

Sì. Stesso input JSON produce sempre stesso output. Le scelte sono basate solo sul sample, non su euristiche probabilistiche. Limite: array misti producono union/any/mixed, è la scelta consapevole.

### I nomi dei tipi annidati come vengono generati?

PascalCase del field key, prefix col root name. Esempio: root `User` con field `address.street` -> tipo `UserAddress` con field `street`. Per array di object: `orders[0].items` -> `UserOrdersItems`. Eventuali collisioni (due path producono lo stesso nome) NON vengono risolte automaticamente: rinomina manualmente.

### Genera sempre tipi valid Go?

Sì, i field name vengono PascalCase-d (Go richiede capital per export), tag json mantengono la chiave originale, tipi corrispondono a quelli encoding/json compatibili. Per opzionali Go usa `*T` + tag `omitempty` (idiomatic Go).

### PHP output usa quale versione?

PHP 8.1+ syntax: typed properties, readonly, constructor promotion. Per supportare PHP 7.4 vai sull'output e cambia `public readonly Type $field` in `private Type $field` + getter. PHP 8.0 (no readonly) è un fix banale: rimuovi `readonly`.

### Posso generare anche da YAML?

No, solo JSON. Per YAML converti prima a JSON con il [convertitore YAML/JSON/TOML](/strumenti/yaml-json-converter) di questo sito, poi incolla il JSON qui.

### Genera anche JSON Schema o OpenAPI?

No, lo scope è deliberatamente limitato ai tipi statici di linguaggio. Per JSON Schema o OpenAPI servono tool specializzati che gestiscano i vincoli (required, enum, pattern, format), gli oneOf/anyOf, le references esterne: usa un editor OpenAPI dedicato o un generator multi-target commerciale.

---
Uno strumento di Maurizio Fonte, senior backend engineer. Tutti gli strumenti: https://www.mauriziofonte.it/strumenti/