JSON–CSV-muunnin

JSONista CSV:ksi – hierarkian litistäminen taulukoksi selaimessa

JSONin muuntaminen CSV:ksi on periaatteessa yksinkertainen toimenpide, mutta se kätkee alleen rakenteellisen muutoksen, joka kannattaa ymmärtää ennen kuin painaa "lataa". Tämä työkalu toimii kokonaan selaimessa: tiedostoa ei koskaan lähetetä palvelimelle. Kaikki käsittely tapahtuu JavaScriptillä paikallisesti. Erona moniin muihin muunnostyökaluihin tässä ei ole kyse vain formaatin vaihdosta vaan tietotyypin ja rakenteen pakkaamisesta toiseen, paljon yksinkertaisempaan ilmaisuun.

Miten JSONin hierarkia litistetään CSV:ksi

JSON tukee mitä tahansa sisäkkäisiä objekteja, taulukoita, lukuja, totuusarvoja ja null-arvoja. CSV puolestaan on vain kaksiulotteinen taulukko, jossa jokaisella solulla on yksi merkkijonoarvo, ei tietotyyppiä. Tästä seuraa kolme keskeistä muunnosongelmaa:

• Sisäkkäiset objektit täytyy litistää. Työkalu käyttää oletuksena dot-path-merkintää: objektin { "osoite": { "kaupunki": "Helsinki", "postinumero": "00100" } } kentistä tulee sarakkeet osoite.kaupunki ja osoite.postinumero. Tämä on yleinen tapa, mutta se muuttaa sarakkeiden nimet pitkiksi ja voi aiheuttaa yhteensopivuusongelmia joidenkin CSV-lukijoiden kanssa.
• Taulukot objekteineen – kun JSON on muodoltaan taulukko objekteja (kuten tyypillinen API-vastaus), jokainen objekti muuttuu yhdeksi riviksi. Jos objekteilla on eri avaimia, tuloksena on yhdistelmä kaikista esiintyvistä avaimista litistettyinä. Puuttuvat kentät jäävät tyhjiksi.
• Taulukot taulukoina – jos JSON on taulukko taulukoita (kuten matriisi), jokainen sisätaulukko muuttuu riviksi ja sen alkiot sarakkeiksi ilman avaimia. Tällöin ei ole otsikkoriviä objekteista.

Työkalu ei tue useita taulukoita eikä moniulotteisia rakenteita. JSONin täytyy olla taulukkomuotoinen – eli joko taulukko objekteja tai taulukko taulukoita, ei esimerkiksi yksittäinen objekti tai syvästi sisäkkäinen rakenne. Jos JSON ei ole tällaista muotoa, käyttäjä saa virheilmoituksen: "This JSON is invalid or not table‑shaped."

Syötteet, tulosteet ja käyttäjän valinnat

Syötteenä on yksi JSON-tiedosto. Työkalu hyväksyy myös CSV- ja XLSX-tiedostoja, mutta ne eivät liity tähän muunnossuuntaan. Tiedosto voidaan ladata joko "Valitse tiedosto" -painikkeella tai raahaamalla se selainikkunaan. Tiedoston koko on rajoitettu – tarkka maksimikoko mainitaan virheilmoituksessa: "This file is too large. Use a file under ‹max›." Samoin rivi- ja sarakerajoitukset: "This table has more than ‹max› rows." ja "This table has more than ‹max› columns." Työkalu ei kerro etukäteen mitä nämä rajat ovat, mutta ne ovat olemassa.

Käyttäjä valitsee CSV-erottimen kolmesta vaihtoehdosta:

• Pilkku (,)
• Puolipiste (;)
• Sarkain (tab)

Valinnalla on suuri merkitys, koska CSV-tiedoston lukijat (kuten Excel) odottavat usein tiettyä erotinta riippuen maa-asetuksista. Suomessa erottimena käytetään yleensä puolipistettä, koska pilkku on desimaalierotin. Työkalu ei automaattisesti päättele erotinta – se on aina käyttäjän valittava.

Tulosteena on CSV-tiedosto, jonka voi ladata. Ennen latausta käyttäjä näkee esikatselun muunnetusta taulukosta, jossa näkyvät rivien ja sarakkeiden määrät sekä tulostiedoston koko tavuina. Esikatselun perusteella on helppo tarkistaa, että litistäminen on onnistunut odotetulla tavalla.

Säännöt ja reunatapaukset – mitä työkalu tekee ja mitä ei

Työkalu on suunniteltu vain näkyvien arvojen käsittelyyn. Se ei laske kaavoja eikä suorita koodia – JSON ei sellaisia tyypillisesti sisälläkään, mutta jos JSON-merkkijonossa on laskettavaa logiikkaa, se jätetään huomiotta.

Tärkeimmät reunatapaukset:

• Tyyppien menetys: Kaikki JSON-arvot muuttuvat merkkijonoiksi CSV:ssä. Luku 42 tulee tekstiksi "42", totuusarvo true tekstiksi "true" ja null tyhjäksi soluksi tai tekstiksi "null" (riippuen toteutuksesta – työkalu ilmoittaa, että kaikista tulee merkkijonoja, joten null todennäköisesti muuttuu tyhjäksi merkkijonoksi). Johtavat nollat häviävät, koska CSV-lukijat saattavat tulkita "00123" numeroksi ja muuttaa sen 123:ksi. Tämä on yleinen ongelma esimerkiksi postinumeroita tai tuotekoodeja käsiteltäessä.
• Lainausmerkit ja rivinvaihdot: CSV-spesifikaatio edellyttää, että arvot, jotka sisältävät erottimen, lainausmerkin tai rivinvaihdon, ympäröidään lainausmerkeillä. Työkalu hoitaa tämän automaattisesti, mutta käyttäjän on hyvä tiedostaa, että monimutkaiset JSON-merkkijonot (esim. HTML-koodi tai pitkät tekstikentät) voivat aiheuttaa yllättäviä tuloksia taulukkolaskentaohjelmissa.
• Virheilmoitukset: Muut kuin taulukkomuotoiset JSON-tiedostot aiheuttavat virheen "This JSON is invalid or not table‑shaped." Muita mahdollisia virheitä: "Choose one file first." (jos yritetään muuntaa ilman tiedostoa), "Choose a CSV, JSON or XLSX file." (väärä tiedostotyyppi), "Choose a different output format." (jos käyttäjä yrittää muuntaa samaksi formaatiksi?), "Could not convert this file." (yleinen muunnosvirhe), "Conversion cancelled." (käyttäjä peruu), "This conversion is taking too long. Try a smaller file." (aikakatkaisu suurilla tiedostoilla).
• Miksi työkalu sallii CSV- ja XLSX-tulot? Vaikka tämä sivu on otsikoitu "JSON to CSV", se on osa suurempaa työkalupakettia, jossa eri suuntia käsitellään samalla käyttöliittymällä. Käyttäjän on siis varmistettava, että valitsee oikean lähdeformaatin.

Kenelle tämä työkalu on tarkoitettu ja milloin sitä käytetään

Työkalu sopii erityisesti tilanteisiin, joissa JSON-tietoa tarvitaan taulukkomuodossa analysointia varten. Tyypillisiä käyttäjiä ovat:

• Kehittäjät, jotka käsittelevät API-vastauksia ja haluavat tuoda ne Exceliin tai Google Sheetsiin jatkokäsittelyä varten. JSONista saatava data on usein hyvin strukturoitua, mutta taulukkolaskentaohjelmat eivät osaa lukea sitä suoraan.
• Tietoanalyytikot, jotka tarvitsevat nopean tavan muuntaa JSON-raportteja CSV:ksi ilman ohjelmointia.
• Yksityisyystietoiset käyttäjät, jotka eivät halua ladata arkaluonteista dataa kolmannen osapuolen palvelimelle. Koska muunnos tapahtuu selaimessa, tiedosto ei poistu koneelta.
• Käyttäjät, jotka tarvitsevat tietyn erottimen – esimerkiksi suomalaiset käyttäjät, jotka tarvitsevat puolipisterajoitettua CSV:tä suomenkieliselle Excelille.

Työkalu on hyödyllinen myös nopeassa prototyyppivaiheessa: tarkista JSON-rakenne, litistä se ja lataa CSV – kaikki sekunneissa.

Tekniset yksityiskohdat – erottimet, lainaus ja tyyppien menetys

Kun JSON muunnetaan CSV:ksi, jokaisesta rivistä tulee merkkijono, jossa kentät erotetaan valitulla erottimella. Esimerkiksi JSON-rivi:

{"nimi": "Mäkeläinen", "ika": 45, "osoite": {"kaupunki": "Tampere", "posti": "33100"}}

Muuttuu CSV-riviksi puolipiste-erottimella (kun litistys päällä):

nimi;ika;osoite.kaupunki;osoite.postinumero
Mäkeläinen;45;Tampere;33100

Huomaa, että ika menetti lukumuotonsa ja 33100 säilyi (ei johtavaa nollaa, joten se on ok). Jos postinumero olisi 00100, se muuttuisi 100:ksi CSV:ssä. Tämä on väistämätöntä, koska CSV ei tunne erillistä tekstimuotoa – taulukkolaskentaohjelmat tulkitsevat solun arvoja oletuksena.

Lainausmerkkien automaattinen lisäys on standardin RFC 4180 mukaista: jos arvo sisältää erottimen, lainausmerkin tai rivinvaihdon, koko arvo ympäröidään lainausmerkeillä ja arvossa olevat lainausmerkit tuplataan. Työkalu tekee tämän, mutta käyttäjän on hyvä varautua siihen, että suuri tiedosto saattaa kasvaa lainausten vuoksi.

Usein kysytyt kysymykset

Miksi työkalu antaa virheilmoituksen "This JSON is invalid or not table‑shaped" vaikka JSON on mielestäni oikein?
Todennäköisesti JSON on objekti eikä taulukko. Esimerkiksi { "a": 1, "b": 2 } on objekti, ei taulukko objekteja. Tarvitaan [ { "a": 1, "b": 2 } ] tai [ ].

Voinko muuntaa JSONin, jossa on syvästi sisäkkäisiä objekteja?
Kyllä, mutta kaikki sisäkkäiset tasot litistetään dot-path-merkinnällä. Tämä voi tuottaa hyvin pitkiä sarakkeiden nimiä, kuten data.user.profile.address.street. Työkalu ei tarjoa vaihtoehtoista litistystapaa.

Häviävätkö tiedot, kun JSONin tyypit muuttuvat merkkijonoiksi?
Kyllä, kaikki tyyppi-informaatio katoaa. Numeroista, totuusarvoista ja null-arvoista tulee pelkkiä merkkijonoja. Jos tarvitset tyyppejä, CSV ei ole oikea formaatti – harkitse JSONin säilyttämistä.

Miksi johtavat nollat katoavat?
Koska CSV-lukijat (kuten Excel) tulkitsevat numerosarjat usein lukuina. Jos solu sisältää "0012", Excel voi muuttaa sen 12:ksi. Työkalu itse ei poista nollia muuntovaiheessa, mutta tulostiedoston latauksen jälkeen toinen ohjelma saattaa tehdä sen.

Voiko työkalu käsitellä erittäin suuria JSON-tiedostoja?
On olemassa rajoitus tiedoston koolle ja rivien/sarakkeiden määrälle. Tarkat rajat mainitaan virheilmoituksissa. Jos työkalu ilmoittaa “This conversion is taking too long. Try a smaller file.”, kannattaa jakaa tiedosto pienempiin osiin.

Tarvitseeko minun olla huolissani tietoturvasta tiedoston lataamisen yhteydessä?
Ei, koska tiedostoa ei koskaan lähetetä palvelimelle. Kaikki käsittely tapahtuu selaimen JavaScript-moottorissa. Voit tarkistaa tämän esimerkiksi katkaisemalla verkkoyhteyden ennen muunnosta – työkalu toimii edelleen, jos sivu on jo ladattu.