# Da JSON di un'API a interface TypeScript in 1 click

> Formatter JSON online: valida, minifica, ordina chiavi e genera interface TypeScript dal JSON. Tutto nel browser, senza upload.

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

Formatta, valida, minifica, ordina le chiavi e genera **interface TypeScript** dal tuo JSON.

## Come usare il formatter

1. **Incolla il JSON** - Copia il payload nell'area sinistra. Funziona con qualsiasi JSON valido: response API, configurazione, dump di database, JSON Lines convertito a array.
2. **Scegli l'indentazione** - 2 spazi (default standard del JavaScript), 4 spazi (PEP-8 style, leggibilità su monitor grandi), tab (preferenza del.editorconfig di molti progetti). L'indentazione è rilevante solo per il pretty-print, non per il minify.
3. **Esegui l'azione** - Formatta per il pretty-print, Minifica per rimuovere ogni whitespace, Valida per il check sintattico puro con stats, Ordina chiavi per output canonico riproducibile, JSON to TypeScript per l'inferenza dei tipi.
4. **Copia o scarica** - Click su Copia per portare il risultato nel clipboard di sistema. Scarica salva un file.json nella cartella download del browser. Niente passa per il server.

## Privacy del payload, error reporting, generazione tipi

**Privacy operativa sul payload.** Il JSON che incolli viene parsificato, validato e renderizzato direttamente nel browser: per chi lavora con payload sensibili (dump di database con email cliente, response API con token di sessione, configurazioni con credenziali, esempi di richieste B2B) il vincolo è non negoziabile. Il contenuto resta nella memoria del tab e non transita per backend di terze parti.

**Error reporting che ti dice dove guardare.** Quando il JSON è malformato, l'engine del browser restituisce un offset di byte oppure una posizione riga/colonna a seconda del motore. Il tool intercetta il messaggio e lo riformula in un indicatore `line N, col M` consistente, da cui puoi saltare direttamente al punto dell'errore nel tuo editor. Niente "Unexpected token" senza contesto.

**JSON to TypeScript integrato.** Convertire un payload JSON in un set di interface TypeScript è un'operazione che la maggior parte degli sviluppatori fa decine di volte a settimana. L'inferenza qui è nativa: il tool analizza ricorsivamente la struttura, rileva campi opzionali (chiavi presenti in alcuni elementi di un array ma non in altri), produce union type per array eterogenei e nomina le interface in PascalCase risolvendo le collisioni con suffisso numerico. Output pronto per essere incollato in un file `types.ts`.

## Glossario

- **Pretty-print**: Formattazione del JSON con indentazione e newline, leggibile per umani. L'opposto del minify.
- **Minify**: Rimozione di tutti i whitespace non significativi (spazi, tab, newline tra token). Tipicamente -20-40% di byte rispetto al pretty-print.
- **JSON canonico**: JSON con chiavi degli oggetti ordinate alfabeticamente, output deterministico utile per diff, hash e firme. RFC 8785 (JCS) definisce uno standard formale.
- **Inferenza di tipo**: Tecnica per dedurre i tipi dei valori a partire da uno o più sample, senza schema esplicito. Approssimativa ma pragmatica per il bootstrap di tipi TypeScript.
- **Optional field**: In TypeScript, un campo dichiarato con `?` dopo il nome (`name?: string`) può essere assente. Diverso da `name: string | undefined` che richiede l'esplicitazione.
- **Union type**: Tipo che ammette più alternative: `string | number`, `'a' | 'b' | 'c'`. Modella array eterogenei e parametri polimorfi.

## Domande frequenti

### Posso incollare un JSON di 10 MB?

Si, finché il tab del browser ha memoria sufficiente. JSON.parse() in V8 gestisce comodamente file da decine di MB; oltre i 100 MB conviene usare uno streaming parser (jq, simdjson) lato CLI. Il tool non ha rate limit né size limit imposti: se il browser regge, il tool processa.

### Il tool supporta JSON5 o JSONC (JSON con commenti)?

No, solo JSON RFC 8259 strict. JSON5 ammette commenti, virgole pendenti, identificatori non quotati: utile per file di config ma non è lo standard wire format. JSON.parse() del browser rifiuta entrambi. Per JSONC consigliamo di rimuovere i commenti via regex prima di incollare.

### Come è calcolata la statistica 'depth' nei messaggi di stato?

È la profondità massima di nested objects/arrays. Un JSON piatto ha depth 1, `{a:{b:1}}` ha depth 2, una struttura tree ricorsiva profonda 10 livelli ha depth 10. Utile per individuare query GraphQL troppo annidate o response API con shape eccessivamente nested.

### L'ordinamento delle chiavi rispetta lo standard JCS (RFC 8785)?

Quasi: ordina le chiavi alfabeticamente come previsto dal JCS, ma non normalizza i numeri (JCS richiede una rappresentazione canonica anche dei numeri, eliminando trailing zero, normalizzando l'esponente, ecc.). Per JCS strict serve una libreria dedicata (`canonicalize` su npm). Per la maggior parte dei use case il sort delle chiavi è sufficiente.

### Le interface TypeScript generate sono utilizzabili in produzione?

Si, ma con caveat. L'inferenza da sample è un punto di partenza, non una specifica formale. Se il sample non è rappresentativo (es. l'API ritorna un campo opzionale che il tuo sample non contiene), l'interface manca quel campo. Best practice: generare un draft, poi raffinare a mano con i campi opzionali, gli union literali (status: 'active' | 'inactive' invece di string), e le date come `string` con un commento ISO 8601.

### Perché il tool segna come errore una stringa con virgolette singole?

Perché lo standard JSON ammette solo le virgolette doppie come delimitatore di stringa. `{'a':1}` è un object literal JavaScript, e come JSON non è valido. Se il payload arriva da JavaScript ed ha virgolette singole, va convertito (e.g. con `JSON.stringify(eval('('+s+')'))` in un contesto controllato) prima del paste.

### Posso usare questo tool offline (PWA)?

Non come PWA installabile, ma una volta caricata la pagina il tool continua a funzionare anche senza connessione: utile in scenari di lavoro su rete instabile, VPN restrittive o ambienti air-gapped.

### Come si comporta con valori molto grandi (BigInt JSON)?

JavaScript JSON.parse non supporta BigInt nativamente: numeri oltre `Number.MAX_SAFE_INTEGER` (2^53 - 1) perdono precisione. Se il payload ha ID interi a 64 bit (snowflake Twitter, ID Discord), arrivano come stringhe già dall'API, oppure perdono precisione silenziosamente. Per questi casi conviene un parser dedicato come `json-bigint` a runtime.

### Funziona su mobile?

Si, layout responsive con dual-pane impilati su schermi sotto 1024px. La textarea ha auto-resize verticale, scroll su entrambi gli assi. Le scorciatoie da tastiera (Tab, Shift+Tab) per indentazione manuale rispettano il behavior del sistema operativo mobile.

### Esiste un'API REST per chiamare le funzionalità di questo tool da uno script?

No, ed è una scelta. Il tool funziona solo nel browser, in modo che il payload non transiti per backend di terze parti. Per workflow scriptabili da terminale: `jq` (formatter, query, transform), `jsonlint` (validator), generator TypeScript da CLI. Se serve un'integrazione self-hosted con frontend custom, è uno dei progetti che faccio in consulenza.

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