Convertir JSON a CSV sense perdre el significat de les dades

JSON i CSV tenen objectius diferents. JSON conserva objectes, llistes i tipus de dades; CSV distribueix valors en files i columnes. La conversió és útil per analitzar un extracte amb un full de càlcul, però no és mai neutra. Abans de convertir cal decidir què representa una fila, quins camps esdevindran columnes, quins tipus s'escriuran com a text i quina informació ja no es podrà reconstruir.

Pensar que CSV és “JSON sense claus” genera exportacions enganyoses. RFC 8259 admet estructures niades, null, booleans, números i cadenes. RFC 4180 descriu registres separats per comes: els camps que contenen comes, cometes o salts de línia han d'anar entre cometes, i les cometes de les dades es dupliquen. Cap dels dos estàndards decideix com s'ha d'encabir un client amb diversos encàrrecs en una sola fila. Aquesta és una decisió del contracte d'exportació.

El problema

El problema comença quan una exportació barreja dades amb cardinalitats diferents. Un registre pot tenir un client i una adreça, però molts encàrrecs; cada encàrrec pot tenir moltes línies. Si cada client ocupa una fila, on van els dos encàrrecs? Si cada línia ocupa una fila, s'han de repetir les dades del client i de l'encàrrec? Les dues respostes poden ser correctes per a finalitats diferents, però produeixen fitxers amb significats diferents.

Els tipus també són importants. L'identificador "00073" no és el número 73: els zeros poden formar part del codi. Una cel·la amb true pot ser un booleà o text literal segons l'importador. null indica absència de valor, mentre que una cadena buida pot indicar un valor conegut però buit. Si tots aquests casos acaben en una cel·la buida, el full sembla net però perd informació per a una importació posterior.

El delimitador no evita l'escapat. Una nota com Lliurar a Madrid, porta 4 conté una coma i s'ha de posar entre cometes. Una nota de dues línies ha de conservar el salt dins d'un camp entrecomillat. Que un programa l'obri correctament no demostra que un altre apliqui el mateix delimitador, codificació o regla de final de línia.

Exemple pràctic

Empra un exemple sintètic, mai dades reals de clients. Aquest JSON conté un client, dos encàrrecs, una llista d'etiquetes, un nul, un booleà, codis amb zeros inicials, una coma i un salt de línia.

{
  "customer": {
    "id": "00073",
    "name": "Lucía, S.A.",
    "marketingAllowed": false,
    "phone": null,
    "tags": ["majorista", "prioritat"],
    "address": { "city": "Madrid", "postalCode": "08001" }
  },
  "orders": [
    { "id": "ORD-001", "paid": true, "note": "Trucar abans de lliurar\na la tarda", "items": [{ "sku": "A-01", "qty": 2 }, { "sku": "B-02", "qty": 1 }] },
    { "id": "ORD-002", "paid": false, "note": "Lliurament a València, recepció", "items": [{ "sku": "C-03", "qty": 4 }] }
  ]
}

Una exportació amb una fila per línia d'encàrrec pot tenir customer.id, customer.name, customer.marketingAllowed, customer.phone, customer.address.city, customer.address.postalCode, order.id, order.paid, order.note, item.sku i item.qty. A la primera fila apareixen "00073", "Lucía, S.A.", false, una cel·la buida, Madrid, "08001", ORD-001, true, una nota entrecomillada de dues línies, A-01 i 2. Les dades del client es repeteixen perquè una fila és una línia, no un client.

Procediment

Primer defineix el gra de la fila amb una frase comprovable: “una fila és una línia d'encàrrec” o “una fila és un encàrrec”. Després llista les rutes JSON que esdevindran columnes amb noms estables com customer.address.postalCode. Evita capçaleres genèriques com id; es tornen ambigües quan conviuen identificadors de client i d'encàrrec.

Després decideix el tractament de cada array. Per a orders i items, una estratègia normalitzada emet una fila per combinació encàrrec-línia i repeteix camps superiors. És útil per filtrar quantitats i sumar vendes. Si el destí necessita una fila per encàrrec, items es pot serialitzar com JSON dins d'una cel·la, però CSV ja no exposa cada propietat. Per a tags, documenta si uniràs valors amb ;, crearàs columnes numerades o faràs una taula separada. No inventis un separador quan una etiqueta el pot contenir.

Fixa també la representació dels tipus. Conserva identificadors i codis postals com a text; en importar al full, marca la columna com a text abans que 00073 passi a 73. Representa booleans amb true i false, o una altra parella acordada, sense barrejar Sí, 1 i true. Defineix una regla explícita per a null, com ara cel·la buida més una especificació que la distingeixi de la cadena buida. Prova accents, comes, cometes i salts de línia.

Al final valida amb un lector CSV que segueixi el format acordat. Comprova el recompte: l'exemple té tres línies d'encàrrec. Verifica que una cometa de dades es duplica en un camp entrecomillat i que el salt de línia no crea un registre extra. La conversió genera el fitxer; la responsabilitat del contracte és de qui l'integra.

Explicació tècnica

L'aplanament transforma rutes d'un arbre en noms de columna. customer.address.city conserva el camí, però per si sola no fa reversible una jerarquia. Les rutes d'objectes són directes perquè un objecte té un valor per clau. Els arrays canvien la relació: una llista té zero, un o molts valors, mentre que una taula ha de triar entre repetir files, unir valors o crear una altra taula.

L'estratègia de files repetides s'assembla a taules relacionades d'una base de dades. Per a cada element d'orders[0].items, l'exportador copia camps de customer i orders[0]. Això permet sumar quantitats sense analitzar JSON dins d'una cel·la. El cost és duplicació: si algú canvia el nom del client només en una fila, les files discrepen. Per això CSV sol ser format d'intercanvi o anàlisi, no l'única font de veritat.

RFC 4180 exigeix cometes per a camps amb comes, cometes o salts de línia, i una cometa interna s'escriu dues vegades. No substitueixis simplement comes per punts i coma: alteraries les dades i fallaries davant un consumidor que espera comes. Especifica també codificació i finals de línia, perquè CSV no aporta metadades fiables per a totes les decisions d'importació.

Errors freqüents

Un error habitual és escollir la primera entrada d'una llista i perdre la resta. Exportar una fila per encàrrec i conservar només el primer item sembla correcte, però elimina dades silenciosament. Un altre és unir valors amb comes sense escapament: Lucía, S.A. semblen dues columnes. Un tercer és usar una cel·la buida tant per a null com per a ""; després no hi ha manera de saber quin valor hi havia.

També és un error suposar que un full preservarà els tipus. Pot convertir 00073 en 73, interpretar ORD-001 com una data segons la configuració local o mostrar números grans amb notació científica. Si el fitxer es reimportarà, lliura una especificació de columnes i una mostra de prova. Conserva el JSON original o un identificador de lot per trobar la font.

Un CSV ben format tampoc no és automàticament segur. Una cel·la controlada per usuari que comença per =, +, - o @ pot ser una fórmula en alguns programes. Per exportar a fulls, aplica i prova una política de mitigació adequada al destí. No alteris silenciosament dades d'una integració crítica sense documentar-ne el contracte.

Consideracions

Pregunta qui llegirà el fitxer abans de dissenyar columnes. Per a una anàlisi ràpida, una taula ampla i repetida pot servir. Per a una migració, poden ser millors diversos CSV relacionats —clients, encàrrecs i línies— units per identificadors textuals. Per a una còpia de seguretat, JSON conserva molt més bé l'estructura. Les mateixes dades poden necessitar tres exportacions diferents sense que una sigui universalment correcta.

Mantén una taula de mapatge al costat de l'exportador: ruta JSON, columna CSV, tipus esperat, transformació, tractament de nul i exemple. Inclou casos límit, com una llista buida, una nota amb cometes i un client sense telèfon. Versiona el mapatge quan canviï una columna. Un consumidor que depèn de customer.id no hauria de descobrir accidentalment que ara s'anomena client_code.

La privacitat també condiciona la conversió. Reduir camps abans d'exportar és normalment més segur que amagar-los després en un llibre compartit. L'exemple és inventat perquè es pugui reutilitzar. Si el fitxer inclou dades personals, limita accessos, evita serveis no avaluats i segueix les obligacions de l'organització responsable.

Limitacions

No hi ha cap conversió JSON→CSV que conservi automàticament tots els significats de qualsevol document. CSV no diferencia per si sol número i text, nul i buit, objecte absent i objecte buit, o una llista d'un element i text que sembla una llista. Una anada i tornada pot reconstruir files seleccionades si desa regles extra, però no l'arbre original en tots els casos.

Aquesta guia no certifica compatibilitat amb un full concret, no substitueix un contracte d'API, proves d'integració ni assessorament professional sobre dades regulades. El comportament d'importació depèn del programa, la configuració regional i la codificació. Prova sempre còpies sintètiques i verifica el destí real abans de processar un lot important.

Llista de comprovació

Defineix què representa una fila i quines rutes JSON seran columnes. Tria i documenta una estratègia per a cada array i la seva duplicació. Conserva identificadors amb zeros inicials com a text. Defineix booleans, nul i cadena buida sense ambigüitat. Escapa comes, cometes i salts de línia segons CSV. Prova el JSON sintètic, compta files i torna a llegir el fitxer amb el consumidor previst. Conserva JSON original quan calgui fidelitat estructural i publica un mapatge versionat perquè una altra persona pugui reproduir l'exportació.