JSON vs YAML vs CSV: quale formato di dati dovresti usare?

Se hai distribuito software per più di un paio d'anni, hai quasi certamente digitato ognuno di questi tre formati in un file a un certo punto. JSON sgorga da ogni endpoint REST. YAML è la lingua franca dei manifest Kubernetes, dei workflow di GitHub Actions e di metà delle CLI che installi. CSV è ciò che il marketing ti invia via email quando vuole "i dati grezzi". Sembrano intercambiabili, e strumenti come Multilities rendono triviale la conversione tra di essi, ma il fatto che tu possa convertire non significa che dovresti scegliere a caso.

Questo articolo spiega come funziona realmente ciascun formato, dove brilla, dove fallisce e le regole pratiche che i team esperti usano per sceglierne uno. Vedremo lo stesso dataset reso in tre modi così che i compromessi siano concreti invece che astratti.

Un rapido modello mentale

Prima di annegare nella sintassi, tieni i formati in mente in questo modo:

• JSON è un formato di serializzazione per oggetti strutturati. È quello a cui ricorri quando una macchina deve parlare con un'altra macchina e gli umani leggono l'output solo occasionalmente.
• YAML è quasi un superset di JSON ottimizzato per gli umani che modificano file di configurazione a mano. Presume che una persona scorrerà, farà diff e revisionerà il file.
• CSV è un formato tabellare. Presume che ogni riga abbia la stessa forma, e che il consumatore sia probabilmente un foglio di calcolo, un comando COPY di un database o una rapida chiamata pandas read_csv.

JSON: il default per API e JS

JSON, JavaScript Object Notation, è stato estratto da JavaScript nei primi anni 2000 e standardizzato come RFC 8259. Ha sei tipi primitivi: oggetto, array, stringa, numero, booleano e null. Questo è l'intero vocabolario. Non ci sono date, né commenti, né virgole finali, né riferimenti. Il minimalismo è il punto: qualsiasi linguaggio può analizzare JSON in poche centinaia di righe di codice, ed è per questo che ogni API HTTP del pianeta finisce per adottarlo.

I browser analizzano JSON nativamente con JSON.parse, ogni stdlib backend ha un modulo JSON, e varianti binary-friendly come MessagePack e CBOR esistono quando superi la rappresentazione testuale. Per payload request/response, log shipping, stato JS persistito e database documentali, JSON è quasi sempre il default corretto.

YAML: il punto ottimale per la configurazione

YAML, originariamente Yet Another Markup Language e poi ricorsivamente rinominato YAML Ain't Markup Language, è un superset rigoroso di JSON nella versione 1.2. Tutto ciò che è legale in JSON è legale YAML, ma YAML aggiunge commenti, stringhe multilinea, anchor e alias per il riuso, tag di tipo espliciti e soprattutto una sintassi basata sull'indentazione che elimina la maggior parte del rumore di punteggiatura.

Quella leggibilità è il motivo per cui YAML domina la configurazione. I manifest Kubernetes, i chart Helm, i playbook Ansible, GitHub Actions, GitLab CI, Docker Compose, le specifiche OpenAPI, i progetti dbt e la maggior parte delle CLI moderne leggono YAML. Quando un umano sta per modificare un file in un editor e revisionarlo in una pull request, YAML vince.

CSV: la stretta di mano universale dei fogli di calcolo

CSV, comma-separated values, è precedente al web ed è descritto vagamente da RFC 4180. È semplicissimo: la prima riga è solitamente un'intestazione, ogni riga successiva è un record, e i campi sono separati da un delimitatore (spesso una virgola, ma tab, punto e virgola e pipe sono comuni). Le stringhe che contengono il delimitatore, una nuova riga o una virgoletta doppia vengono racchiuse in virgolette doppie, e le virgolette doppie interne sono escapate raddoppiandole.

CSV è il formato che ogni foglio di calcolo sulla Terra, ogni strumento BI, ogni bulk loader di database e ogni analista con un notebook Python comprende senza cerimonie. È un formato terribile per dati annidati e un formato meraviglioso per tabelle piatte. Quando il consumatore è un umano con Excel aperto, CSV è quasi sempre la risposta giusta.

Stessi dati, tre formati

Fissiamo le differenze con un esempio concreto. Immagina una lista di tre utenti, ciascuno con un id, un nome, un'email, un ruolo e una lista di tag. Ecco la versione JSON.

[
  {
    "id": 1,
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "role": "admin",
    "tags": ["founder", "math"]
  },
  {
    "id": 2,
    "name": "Linus Torvalds",
    "email": "linus@example.com",
    "role": "maintainer",
    "tags": ["kernel", "git"]
  },
  {
    "id": 3,
    "name": "Grace Hopper",
    "email": "grace@example.com",
    "role": "admin",
    "tags": ["compiler", "navy"]
  }
]

Lo stesso payload come YAML

Nota come la punteggiatura cade. La struttura è trasmessa interamente dall'indentazione, e la lista di tag può essere scritta sia inline (flow style, identico a JSON) sia come blocco. I commenti sono legali e spesso utili.

# Utenti seed per l'ambiente di staging
- id: 1
  name: Ada Lovelace
  email: ada@example.com
  role: admin
  tags:
    - founder
    - math
- id: 2
  name: Linus Torvalds
  email: linus@example.com
  role: maintainer
  tags: [kernel, git]   # flow style va bene per liste corte
- id: 3
  name: Grace Hopper
  email: grace@example.com
  role: admin
  tags:
    - compiler
    - navy

E come CSV

CSV non può esprimere nativamente l'array annidato di tag, quindi dobbiamo appiattirlo. Una convenzione comune è unire la lista con un delimitatore secondario come una pipe o un punto e virgola e documentare quella scelta da qualche parte. La riga di intestazione sostituisce i nomi dei campi, e ogni record è sulla propria riga.

id,name,email,role,tags
1,Ada Lovelace,ada@example.com,admin,founder|math
2,Linus Torvalds,linus@example.com,maintainer,kernel|git
3,Grace Hopper,grace@example.com,admin,compiler|navy

Tre formati, tre dimensioni

La dimensione del file conta più di quanto la gente ammetta. Le pipeline di logging, i bundle del browser e le bollette dello storage se ne preoccupano tutte. Per l'esempio sopra i conteggi approssimativi in byte sono: JSON circa 410 byte pretty-printed e 290 minificato; YAML circa 320 byte; CSV circa 200 byte. CSV vince a mani basse sui dati piatti perché ammortizza i nomi dei campi su ogni riga invece di ripeterli.

Una volta che inizi ad annidare, il quadro si capovolge. JSON e YAML rimangono pressoché costanti per record mentre CSV o deve appiattire con convenzioni che inventi tu o esplodere in più fogli. Per un singolo utente profondamente annidato con venti campi, JSON e YAML saranno più piccoli e più chiari di qualsiasi CSV tu possa costruire.

Dove ciascun formato vince in pratica

Pattern matching di ciò che usano i team reali:

• JSON per API HTTP, payload WebSocket, localStorage del browser, righe di log (specialmente JSON Lines), database documentali come MongoDB e qualsiasi contratto inter-servizio.
• YAML per Kubernetes, Helm, Argo, workspace di Terraform Cloud, pipeline di GitHub o GitLab CI, specifiche OpenAPI e AsyncAPI, configurazione applicativa che gli umani modificano e infrastructure-as-code dove la leggibilità batte la velocità di parsing.
• CSV per esportazioni analytics, importazioni CRM, tabelle di staging ETL, dataset di machine learning, report finanziari e qualsiasi cosa destinata a Excel o Google Sheets.
• Non ricorrere a nessuno di essi se i tuoi dati sono binari, ad altissimo throughput o fortemente tipizzati tra servizi. Protobuf, Avro o Parquet sono di solito la risposta giusta lì.

Insidie di JSON che mordono

Il minimalismo di JSON è una caratteristica, ma crea alcune trappole. La specifica vieta i commenti, quindi i file di configurazione scritti in JSON non possono spiegarsi. Le virgole finali dopo l'ultimo elemento di array o oggetto sono illegali anche se ogni linguaggio moderno le accetta. I numeri sono float a 64 bit per impostazione predefinita, quindi qualsiasi intero più grande di 2 elevato 53 perde silenziosamente precisione, motivo per cui molte API serializzano i grandi ID come stringhe.

JSON inoltre non ha un tipo data nativo. Le stringhe ISO 8601 sono la convenzione de facto, ma tu e il tuo consumatore dovete essere d'accordo. E le chiavi duplicate nello stesso oggetto sono tecnicamente consentite dalla grammatica ma producono comportamenti indefiniti tra i parser, quindi non fare affidamento su di esse.

Insidie di YAML che mordono più forte

La flessibilità di YAML è la sua debolezza. L'indentazione è significativa, quindi mescolare tab e spazi o perdere due caratteri di whitespace iniziale cambia silenziosamente il significato del tuo file. Il famigerato "problema Norvegia" affiora ancora nei parser YAML 1.1: il token non quotato NO viene analizzato come il booleano false, il che ha rovinato liste di codici nazionali più di una volta. YAML 1.2 risolve questo ma molti tool ancora distribuiscono semantiche 1.1.

Le stringhe che sembrano numeri, date o booleani vengono coercizzate a meno che non le citi. Anchor e alias (la sintassi &foo e *foo) sono potenti ma invitano denial of service in stile billion-laughs se accetti YAML non fidato. Analizza sempre YAML fornito dall'utente con un loader sicuro.

Insidie di CSV che mordono in silenzio

CSV è il formato più probabile a sembrare corretto pur essendo sottilmente rotto. Non c'è uno standard per il delimitatore; le impostazioni locali europee esportano con punto e virgola perché la virgola è un separatore decimale, e il tuo importatore deve rilevarlo. Le nuove righe dentro campi quotati sono legali ma fanno inciampare gli splitter di righe ingenui. Excel riformatterà felicemente numeri di telefono e ID lunghi come notazione scientifica quando apre un CSV, rovinando i tuoi dati prima ancora che un umano li veda.

L'encoding è l'altra mina. CSV non ha una dichiarazione di encoding, quindi un file che si apre pulitamente su macOS può mostrare mojibake su Windows a causa di UTF-8 vs Windows-1252. In caso di dubbio, scrivi un BOM UTF-8, documenta il delimitatore e cita ogni campo stringa.

Convertire in modo sicuro tra di essi

La maggior parte dei sistemi reali vive in più di uno di questi formati. Ingerisci un CSV da un fornitore, lo trasformi in JSON per un'API ed emetti YAML per configurare il worker che processa il risultato. Fare quelle conversioni a mano è da dove vengono i bug, motivo per cui Multilities distribuisce convertitori dedicati.

Se stai passando tra JSON e YAML, il convertitore /tools/yaml-json gestisce entrambe le direzioni e preserva i commenti dove può. Per dati tabellari, /tools/csv-json trasforma le esportazioni CSV in array JSON che puoi incollare direttamente in un file di fixture o in una richiesta Postman, e viceversa quando devi consegnare un foglio di calcolo alla finanza. E quando vuoi semplicemente che un blob JSON si legga come se l'avesse scritto un umano, /tools/json-formatter ordina le chiavi, sistema l'indentazione e valida la struttura in un singolo passaggio.

Una checklist decisionale

Quando non sei sicuro, scorri questa lista dall'alto verso il basso e fermati al primo sì.

• Il consumatore è un foglio di calcolo o un bulk loader SQL e i dati sono piatti? Usa CSV.
• Un umano modificherà questo file in un editor di codice e lo revisionerà in una pull request? Usa YAML.
• Il consumatore è un programma, specialmente attraverso la rete, e vuoi cerimonia minima e tooling massimo? Usa JSON.
• Stai serializzando milioni di record ad alto throughput con uno schema fisso? Salta tutti e tre e ricorri a Protobuf, Avro o Parquet.

Per concludere

I tre formati non sono concorrenti quanto specialisti. JSON è il formato di interscambio universale, YAML è il linguaggio di configurazione amichevole per gli umani e CSV è la stretta di mano dei fogli di calcolo che si rifiuta di morire perché nessun altro è altrettanto universalmente compreso dai non sviluppatori. Sapere per quale lavoro è stato progettato ciascuno, e conoscere le insidie, è ciò che separa i team che distribuiscono pipeline di dati pulite dai team che combattono bug di escaping ogni venerdì pomeriggio.

Tieni gli strumenti di conversione nei segnalibri, annota quale delimitatore ed encoding usano i tuoi CSV, cita le tue stringhe YAML in caso di dubbio e non fidarti mai di un ID a 64 bit non firmato per sopravvivere a un round trip attraverso JavaScript. Fai questo e il formato che scegli scomparirà per lo più sullo sfondo, che è esattamente ciò che un buon formato di dati dovrebbe fare.