JSON naar CSV converteren: uitleg met een echt voorbeeld

JSON naar CSV converteren betekent een array van objecten omzetten naar een platte tabel: elk object wordt een rij, en de kolomkoppen zijn de unie van alle sleutels die in de hele array voorkomen, niet alleen die van het eerste object. De meeste verwarring ontstaat bij de escaping: zodra een waarde een komma, een aanhalingsteken of een regeleinde bevat, moet die waarde volgens een vaste regel worden omgezet, anders lees je straks een kapotte tabel in.

Waarom CSV nog steeds overal wordt gebruikt

JSON is het formaat van API’s en configuratiebestanden, maar zodra iemand met de data in een spreadsheet wil werken, filteren, sorteren of een draaitabel wil bouwen, is CSV nog altijd de gemeenschappelijke taal. Excel, Google Sheets en zowat elke datapipeline lezen CSV probleemloos in, terwijl geneste JSON eerst platgeslagen moet worden voordat een spreadsheet er iets zinnigs mee kan. Een export uit een database, een response van een API, of een lijst producten uit een e-commerce systeem: het patroon is steeds hetzelfde, een array van vergelijkbare objecten die je in tabelvorm wilt zien.

Een geverifieerd voorbeeld

Neem de volgende JSON, drie productregels met een SKU, een naam, een prijs en een voorraadstatus:

[
  { "sku": "A100", "product": "Wireless Mouse, Black", "price": 19.99, "in_stock": true },
  { "sku": "A101", "product": "17\" Laptop Stand", "price": 42.5, "in_stock": false },
  { "sku": "A102", "product": "USB-C Cable", "price": 8.99, "in_stock": true }
]

De converter leest de sleutels in de volgorde waarin ze voor het eerst verschijnen (sku, product, price, in_stock) en gebruikt die als kolomkoppen. Het resultaat:

sku,product,price,in_stock
A100,"Wireless Mouse, Black",19.99,true
A101,"17"" Laptop Stand",42.5,false
A102,USB-C Cable,8.99,true

Elke rij laat een ander stukje van de escape-logica zien. In rij 1 bevat Wireless Mouse, Black een komma. Zonder ingrijpen zou een CSV-lezer die komma aanzien voor een kolomscheiding en de waarde in tweeën knippen, dus de converter wikkelt de hele waarde in dubbele aanhalingstekens: "Wireless Mouse, Black". In rij 2 zit er een letterlijk aanhalingsteken in 17" Laptop Stand. Volgens RFC 4180, de standaard waarop CSV-parsers zich baseren, wordt zo’n aanhalingsteken verdubbeld (" wordt "") en wordt de héle waarde bovendien nog eens tussen een buitenste paar aanhalingstekens gezet, wat "17"" Laptop Stand" oplevert. Die dubbele stap, eerst verdubbelen, dan omwikkelen, is precies waar mensen die CSV met de hand samenstellen de mist ingaan. Rij 3, USB-C Cable, bevat geen komma, aanhalingsteken of regeleinde en blijft daarom gewoon ongewikkeld staan.

De regel is simpel te onthouden: een waarde krijgt alleen dubbele aanhalingstekens om zich heen als hij een komma, een dubbel aanhalingsteken of een regeleinde bevat. Aanhalingstekens die al in de waarde zitten, worden altijd verdubbeld, ongeacht of de waarde daarnaast ook wordt omwikkeld.

Ontbrekende sleutels: de kolomunie

Niet elk object in een array hoeft dezelfde sleutels te hebben. Stel dat een vierde product een extra veld color heeft dat de andere drie missen:

[
  { "sku": "A100", "product": "Wireless Mouse, Black" },
  { "sku": "A103", "product": "Desk Lamp", "color": "White" }
]

De kolomkoppen worden sku, product, color, want de converter verzamelt de sleutels van alle objecten samen, niet alleen die van het eerste. Voor het eerste object, dat geen color heeft, blijft die cel gewoon leeg in plaats van dat de conversie vastloopt of de kolom wordt weggelaten:

sku,product,color
A100,Wireless Mouse, Black,
A103,Desk Lamp,White

(In de echte output zou “Wireless Mouse, Black” door de komma alsnog tussen aanhalingstekens staan, zoals hierboven al is uitgelegd.) Sommige eenvoudige converters kijken alleen naar de sleutels van het eerste object en laten kolommen van latere objecten stilzwijgend vallen. Deze tool doet dat niet: elke sleutel die ergens in de array voorkomt, krijgt een kolom.

De tool

Plak een JSON-array van platte objecten hieronder. Alles gebeurt lokaal in de browser, er wordt niets naar een server verstuurd, en bij ongeldige JSON of een input die geen array is, krijg je meteen een foutmelding in plaats van een crash. Op de gewone toolpagina wordt de URL automatisch bijgewerkt terwijl je typt, zodat je een resultaat kunt delen, maar dat gebeurt niet wanneer de widget zo ingesloten is als hieronder.

Veelgemaakte fouten

Geneste objecten worden [object Object]. Een waarde als { "address": { "city": "Utrecht", "zip": "3512" } } levert geen twee kolommen op. De converter zet de waarde om met een simpele tekstconversie, en voor een object levert dat de letterlijke tekst [object Object] op, geen leesbare data, gewoon dataverlies. De oplossing is de structuur vóór het converteren plat te slaan: maak van address twee losse velden op het hoogste niveau, bijvoorbeeld address_city en address_zip, zodat elk daadwerkelijk een eigen kolom krijgt.

Arrays worden één kommagescheiden string, geen aparte kolommen. Een waarde als ["red", "blue"] wordt niet uitgesplitst naar twee cellen. De tekstconversie plakt de elementen aan elkaar met komma’s en zonder haakjes, dus je krijgt de string red,blue. Omdat die string zelf weer een komma bevat, herkent de escape-stap dat en wikkelt hem netjes in aanhalingstekens, "red,blue", zodat de kolomstructuur van de rest van de rij intact blijft. Het resultaat is correct CSV, maar wel één cel met twee waarden erin in plaats van twee losse kolommen. Wil je losse kolommen per array-element, dan moet je dat vóór de conversie zelf uitsplitsen.

Excel opent de CSV in één kolom. Dit is puur een instellingenprobleem, geen bug in de conversie. De output van de tool gebruikt altijd een komma als scheidingsteken. Nederlandse Excel-installaties gebruiken de komma echter als decimaalteken en verwachten daarom standaard een puntkomma als lijstscheidingsteken. Open je zo’n comma-CSV rechtstreeks, dan landt de hele rij vaak in kolom A. De oplossing: gebruik in Excel “Gegevens > Tekst naar kolommen” en kies daar expliciet komma als scheidingsteken, of pas het lijstscheidingsteken in de Windows-regio-instellingen aan.

Een los object in plaats van een array. De converter verwacht een array van objecten, dus vierkante haken eromheen, ook als je maar één rij hebt. { "sku": "A100" } geeft een foutmelding, [{ "sku": "A100" }] werkt. Kom je JSON tegen zonder buitenste haken, zet die er dan eerst omheen voordat je converteert.

Veelgestelde vragen

Wat gebeurt er als de JSON geen array is, maar één los object? De tool toont een foutmelding in plaats van een resultaat. De input moet een array zijn, ook als die maar één object bevat, dus { "sku": "A100" } moet worden [{ "sku": "A100" }].

Wat gebeurt er met een array-waarde binnen een object, zoals "tags": ["a", "b"]? Die wordt niet uitgesplitst naar meerdere kolommen. De array wordt omgezet naar een string door de elementen met komma’s aan elkaar te plakken (a,b), en omdat die string zelf een komma bevat, wikkelt de escape-regel hem automatisch in dubbele aanhalingstekens: "a,b". Het blijft één cel.

Waarom staat er [object Object] in mijn CSV? Dat gebeurt wanneer een veld een genest object is in plaats van een simpele waarde. De converter werkt alleen met platte objecten en zet een genest object om via een generieke tekstconversie, die letterlijk [object Object] teruggeeft. Slaat je JSON velden geneste, dan moet je die eerst platslaan naar aparte top-level sleutels, bijvoorbeeld address_city in plaats van address: { city: ... }.

Waarom opent mijn CSV-bestand in Excel met alles in één kolom? De tool gebruikt een komma als scheidingsteken, wat de internationale CSV-standaard is. Nederlandse Excel-installaties verwachten door de regio-instelling vaak een puntkomma als lijstscheidingsteken. Gebruik in Excel de functie “Gegevens > Tekst naar kolommen” met komma als scheidingsteken, of wijzig het lijstscheidingsteken in je systeeminstellingen.

Verlaat mijn data de browser tijdens het converteren? Nee. De conversie draait volledig client-side in JavaScript. Er wordt niets naar een server gestuurd, dus de tool is ook geschikt voor gevoelige of vertrouwelijke data.

Wat als twee objecten in de array verschillende sleutels hebben? De kolomkoppen worden de unie van alle sleutels uit de hele array, in de volgorde waarin ze voor het eerst voorkomen, niet alleen de sleutels van het eerste object. Mist een object een sleutel die een ander object wel heeft, dan blijft die cel voor dat object leeg in plaats van dat de conversie een fout geeft.