CSV’den JSON’a Dönüştürme Rehberi: Yöntemler, Tuzaklar ve En İyi Uygulamalar

Operasyon ekibiniz size bir CSV dışa aktarımı gönderiyor. API’niz JSON bekliyor. Dosyayı açıyorsunuz, virgülle ayrılmış 10.000 satır değere bakıyorsunuz ve şunu merak ediyorsunuz: veri kaybetmeden CSV’yi JSON’a dönüştürmenin en hızlı yolu nedir?

Bu rehber dört dönüştürme yöntemini (tarayıcı araçları, JavaScript, Python, CLI), ters yönü (JSON’dan CSV’ye), verinizi sessizce bozan beş tuzağı ve belleğe sığmayacak kadar büyük dosyaların nasıl ele alınacağını kapsar.

CSV ve JSON Karşılaştırması: Hangisini Ne Zaman Kullanmalı

Dönüştürmeden önce, her formatın hangi konuda iyi olduğunu anlamak yardımcı olur.

Boyut	CSV	JSON
Yapı	Düz tablo (satırlar ve sütunlar)	Yuvalanmış hiyerarşi (nesneler, diziler)
Veri tipleri	Her şey karakter dizisidir	string, number, boolean, null
İnsan tarafından okunabilirlik	Tablo programları için uygun	Geliştirici dostu
Birincil kullanım	Veri dışa/içe aktarımı, raporlar, ETL	API’ler, yapılandırma dosyaları, NoSQL depolama
Dosya boyutu	Daha küçük (anahtar adları tekrarlanmaz)	Daha büyük (anahtar adları her kayıtta tekrarlanır)
Şema	Örtük (başlık satırı)	Açık (veya JSON Schema kullanılır)

Pratik kural: Veriniz tablosalsa ve tüketici bir tablo programı veya veri pipeline’ı ise CSV kullanın. Veriniz hiyerarşik yapıdaysa veya tüketici bir API ise JSON kullanın. JSON çıktınızı her zaman bir JSON Biçimlendirici ile doğrulayarak yapısal sorunları erken yakalayabilirsiniz.

Projeniz yapılandırma için JSON5 veya JSONC gibi gevşek JSON formatları kullanıyorsa, söz dizimi farklılıkları ve araçlar için JSON5 ve JSONC biçimlendirme rehberimize bakın.

CSV’yi JSON’a Dönüştürmenin 4 Yolu

Yöntem 1 — Tarayıcı Tabanlı Araç

Tek seferlik dönüştürmeler için tarayıcı tabanlı bir yaklaşım en hızlı yoldur. CSV’nizi çevrimiçi bir dönüştürücüye yapıştırın, JSON çıktısını alın, ardından yapının doğru olduğundan emin olmak için sonucu bir JSON Biçimlendirici içinde doğrulayın.

Avantajı: verileriniz tarayıcınızdan asla çıkmaz. Yükleme yok, sunucu işleme yok, gizlilik kaygısı yok. Bu, dahili verilerle, dışa aktarımlara gömülü API anahtarlarıyla veya üçüncü taraf bir sunucuya göndermeyi tercih etmediğiniz herhangi bir şeyle çalışırken önem kazanır.

En uygun olduğu durumlar: küçük dosyalar (10 MB altı), hızlı tek seferlik dönüştürmeler ve teknik olmayan ekip üyeleri.

Yöntem 2 — JavaScript / Node.js

Tarayıcı (saf JS):

function csvToJson(csv) {
  const lines = csv.trim().split('\n');
  const headers = lines[0].split(',').map(h => h.trim());

  return lines.slice(1).map(line => {
    const values = line.split(',');
    return headers.reduce((obj, header, i) => {
      obj[header] = values[i]?.trim() ?? '';
      return obj;
    }, {});
  });
}

const csv = `name,age,city
Alice,30,New York
Bob,25,London`;

console.log(JSON.stringify(csvToJson(csv), null, 2));

Bu, tırnak içine alınmış alanları olmayan basit CSV’ler için işe yarar. Değerler içinde virgül, alanlarda yeni satır veya tırnaklı karakter dizileri içeren üretim kullanımı için uygun bir ayrıştırıcı kullanın.

Node.js (csv-parser + akışlar):

import { createReadStream } from 'fs';
import { parse } from 'csv-parse';

const records = [];

createReadStream('data.csv')
  .pipe(parse({ columns: true, trim: true, skip_empty_lines: true }))
  .on('data', (row) => records.push(row))
  .on('end', () => {
    console.log(JSON.stringify(records, null, 2));
  });

columns: true seçeneği ilk satırı anahtar olarak kullanır. trim seçeneği değerlerden boşlukları temizler. Bu, tırnak içine alınmış alanları, kaçış karakteriyle korunmuş virgülleri ve çok satırlı değerleri doğru biçimde ele alır.

Yöntem 3 — Python

Standart kütüphane (sıfır bağımlılık):

import csv
import json

with open('data.csv', encoding='utf-8') as f:
    reader = csv.DictReader(f)
    rows = list(reader)

with open('data.json', 'w', encoding='utf-8') as f:
    json.dump(rows, f, indent=2, ensure_ascii=False)

csv.DictReader başlık satırını anahtar olarak kullanarak her satırı bir sözlüğe eşler. ensure_ascii=False bayrağı, Unicode karakterleri (Çince, Japonca, aksanlı karakterler) \uXXXX kaçış dizilerine dönüştürmek yerine olduğu gibi korur.

Pandas (veri bilimcileri için tek satırlık):

import pandas as pd

df = pd.read_csv('data.csv')
df.to_json('data.json', orient='records', indent=2, force_ascii=False)

Hangisini ne zaman kullanmalı:

csv + json: Hafif betikler, Lambda fonksiyonları, minimum bağımlılık istediğiniz container’lar.
pandas: Dönüştürmeden önce veriyi temizlemeniz, filtrelemeniz veya dönüştürmeniz gerektiğinde. Yalnızca format dönüşümünden fazlasını yapıyorsanız pandas’ı içe aktarmanın ek yükü buna değer.

Yöntem 4 — CLI Araçları

Shell betikleri ve otomasyon pipeline’ları için:

csvkit:

# Kurulum: pip install csvkit
csvjson data.csv > data.json

Miller (mlr):

# Kurulum: brew install miller (macOS) veya apt install miller (Ubuntu)
mlr --csv --json cat data.csv > data.json

Filtreleme için jq ile boru ile aktarma:

# Tek bir pipeline'da dönüştür ve filtrele
csvjson data.csv | jq '[.[] | select(.age | tonumber > 25)]'

Miller, CSV, JSON, TSV ve diğer formatları yerel olarak ele aldığı için özellikle güçlüdür. Dönüştürme sırasında veriyi dönüştürebilirsiniz:

# CSV'yi JSON'a dönüştür, bir alanı yeniden adlandır, hesaplanmış bir alan ekle
mlr --csv --json rename name,fullName then put '$age_group = ($age > 30) ? "senior" : "junior"' data.csv

JSON’dan CSV’ye: Ters Yönü Ele Almak

JSON’u CSV’ye dönüştürmek, ileri yönde bulunmayan zorluklar getirir.

Yuvalanmış Nesneleri Düzleştirme

CSV doğası gereği düzdür. JSON’unuzun yuvalanmış nesneleri olduğunda bir düzleştirme stratejisine ihtiyacınız vardır:

{
  "name": "Alice",
  "address": {
    "city": "New York",
    "zip": "10001"
  }
}

Şuna dönüşür:

name	address.city	address.zip
Alice	New York	10001

Nokta gösterimi konvansiyonu (address.city) en yaygın yaklaşımdır. Python’da:

import pandas as pd

data = [
    {"name": "Alice", "address": {"city": "New York", "zip": "10001"}},
    {"name": "Bob", "address": {"city": "London", "zip": "EC1A"}}
]

df = pd.json_normalize(data)
df.to_csv('output.csv', index=False)
# Sütunlar: name, address.city, address.zip

Dizileri Ele Alma

Dizi alanları bir karar gerektirir:

Strateji	Örnek girdi	CSV çıktısı	En uygun olduğu durum
Karakter dizisi olarak birleştir	`["admin","editor"]`	`admin;editor`	Basit listeler, geri içe aktarılabilir
Sütunlara genişlet	`["admin","editor"]`	`role_0: admin, role_1: editor`	Sabit uzunluklu diziler
Satırlara genişlet	`["admin","editor"]`	İki satır, rol başına bir satır	İlişkisel analiz

Akış aşağısındaki tüketicinize göre seçin. CSV bir veritabanına geri gidiyorsa, satırlara genişletmek genellikle en mantıklısıdır.

Tip Bilgisi Kaybı

CSV’nin tip sistemi yoktur. JSON’u CSV’ye dönüştürdüğünüzde:

true, "true" karakter dizisine dönüşür — boolean mı yoksa karakter dizisi mi?
null boş bir hücreye dönüşür — boş bir karakter dizisi "" ile ayırt edilemez.
42, "42" olur — sayı mı yoksa karakter dizisi mi?

Gidiş-dönüş sadakati önem taşıyorsa (CSV → işle → JSON), tip konvansiyonlarınızı bir başlık yorumunda veya yan bir şema dosyasında belgeleyin.

5 Yaygın Tuzak ve Bunlardan Nasıl Kaçınılır

Bu sorunlar veriyi sessizce bozar. Çoğu eğitim bunları atlar. Bunları üretimde öğrenmeyin.

1. Kodlama Mayınları

Sorun: Bir meslektaşınızdan gelen bir CSV’yi açıyorsunuz ve é yerine ÃƒÂ© veya Çince karakterler yerine 锟斤拷 görüyorsunuz.

Neden olur: Dosya bir kodlamada (Windows-1252, GBK, Shift_JIS) kaydedilmiştir ama ayrıştırıcınız UTF-8 varsayar. Windows’ta Excel CSV’yi sıklıkla Windows-1252 olarak kaydeder veya bir UTF-8 BOM ekler (Byte Order Mark — dosyanın başındaki görünmez \xEF\xBB\xBF).

Çözüm:

# Önce kodlamayı tespit et
import chardet

with open('data.csv', 'rb') as f:
    result = chardet.detect(f.read(10000))
    print(result)  # {'encoding': 'Windows-1252', 'confidence': 0.73}

# Sonra doğru kodlamayla oku
with open('data.csv', encoding=result['encoding']) as f:
    reader = csv.DictReader(f)
    # ...

Node.js’te BOM’u açıkça temizleyin:

import { readFileSync } from 'fs';

let content = readFileSync('data.csv', 'utf-8');
// Varsa UTF-8 BOM'u temizle
if (content.charCodeAt(0) === 0xFEFF) {
  content = content.slice(1);
}

2. Ayraç Karışıklığı

Sorun: Ayrıştırıcınız birden fazla alan yerine tek bir dev sütun üretiyor.

Neden olur: Birçok Avrupa yerel ayarında (Fransa, Almanya, İspanya), Excel CSV ayracı olarak noktalı virgül (;) kullanır çünkü virgüller ondalık ayraç olarak kullanılır (örneğin 3.14 yerine 3,14). Sekmeyle ayrılmış dosyalar (.tsv) başka bir varyant ekler.

Çözüm: İlk birkaç satırı örnekleyerek ayracı otomatik tespit edin:

import csv

with open('data.csv') as f:
    sample = f.read(8192)
    dialect = csv.Sniffer().sniff(sample, delimiters=',;\t|')
    f.seek(0)
    reader = csv.DictReader(f, dialect=dialect)

3. Baştaki Sıfırlar Kayboluyor

Sorun: Posta kodu 00501, 501’e dönüşür. Ürün kodu 007, 7’ye dönüşür.

Neden olur: Ayrıştırıcı (veya Excel) alanı bir sayı olarak yorumlar ve baştaki sıfırları temizler. Bu özellikle posta kodları, telefon numaraları ve kimlik kodları için tehlikelidir.

Çözüm: Karakter dizisi tipini zorunlu kılın. Pandas’ta:

df = pd.read_csv('data.csv', dtype={'zip': str, 'product_code': str})

JavaScript’te, orijinal karakter dizisinin sayısal ayrıştırılmasından farklı olup olmadığını denetleyin:

function preserveLeadingZeros(value) {
  if (/^0\d+$/.test(value)) return value; // Karakter dizisi olarak tut
  const num = Number(value);
  return isNaN(num) ? value : num;
}

4. Büyük Sayı Hassasiyet Kaybı

Sorun: 9007199254740993 kimliği JSON’unuzda 9007199254740992’ye dönüşür.

Neden olur: JavaScript Number 64-bit kayan nokta değeridir (IEEE 754). Number.MAX_SAFE_INTEGER (2^53 - 1 = 9007199254740991) üstündeki tam sayılar hassasiyet kaybeder. Bu, veritabanı kimliklerini, Snowflake kimliklerini ve Twitter/X gönderi kimliklerini etkiler.

Çözüm: Büyük sayıları JSON’da karakter dizileri olarak saklayın veya işleme kodunuzda BigInt kullanın:

// Büyük sayılar için karakter dizisi koruyarak ayrıştır
function safeParseNumber(value) {
  const num = Number(value);
  if (Number.isInteger(num) && !Number.isSafeInteger(num)) {
    return value; // Hassasiyeti korumak için karakter dizisi olarak tut
  }
  return isNaN(num) ? value : num;
}

5. Boş Değer Belirsizliği

Sorun: CSV’nizde boş hücreler var. Dönüştürmeden sonra orijinal değerin boş bir karakter dizisi "", null mu yoksa basitçe eksik mi olduğunu anlayamıyorsunuz.

Neden olur: CSV’nin bu üç durumu birbirinden ayırt etmenin bir yolu yoktur. İki virgül arasındaki boş bir alan (Alice,,30) bunlardan herhangi biri anlamına gelebilir.

Çözüm: Bir konvansiyon tanımlayın ve tutarlı biçimde uygulayın:

def parse_value(value):
    if value == '':
        return None        # ya da '' — birini seçin
    if value == 'NULL' or value == 'null':
        return None
    return value

Verileriniz NULL, N/A veya - gibi nöbetçi değerler kullanıyorsa, bunları açıkça belgeleyin ve ele alın.

Büyük Dosyaları Akış Olarak İşleme

CSV’niz 100 MB’ı aştığında, tümünü belleğe yüklemek bir seçenek değildir. Akışı kullanın.

Node.js (akış pipeline’ı):

import { createReadStream, createWriteStream } from 'fs';
import { parse } from 'csv-parse';
import { Transform } from 'stream';
import { pipeline } from 'stream/promises';

let first = true;
const toJsonArray = new Transform({
  objectMode: true,
  transform(record, encoding, callback) {
    const prefix = first ? '[\n' : ',\n';
    first = false;
    callback(null, prefix + JSON.stringify(record));
  },
  flush(callback) {
    callback(null, '\n]');
  }
});

await pipeline(
  createReadStream('large.csv'),
  parse({ columns: true, trim: true }),
  toJsonArray,
  createWriteStream('large.json')
);

Python (üretici):

import csv
import json

def csv_rows(path):
    with open(path, encoding='utf-8') as f:
        reader = csv.DictReader(f)
        for row in reader:
            yield row

# JSON Lines formatına akış (satır başına bir JSON nesnesi)
with open('large.jsonl', 'w', encoding='utf-8') as out:
    for row in csv_rows('large.csv'):
        out.write(json.dumps(row, ensure_ascii=False) + '\n')

Çok büyük dosyalar için tek bir JSON dizisi yerine JSON Lines (.jsonl) düşünün. Her satır bağımsız bir JSON nesnesidir, bu da çıktı dosyasını da satır satır işleyebileceğiniz anlamına gelir — tüm dosyayı ayrıştırmaya gerek yoktur.

SSS

CSV ile JSON arasındaki fark nedir?

CSV (Comma-Separated Values), her değerin bir karakter dizisi olduğu düz bir tablo olarak veri saklar. JSON (JavaScript Object Notation), yuvalanmış nesneler, diziler ve tipli değerlerle (karakter dizileri, sayılar, boolean’lar, null) yapılandırılmış veri saklar. CSV daha küçüktür ve tablo programları için uygundur; JSON daha ifade edici ve API dostudur.

JavaScript’te CSV’yi JSON’a nasıl dönüştürürüm?

Node.js’te csv-parse paketini kullanın: dosyayı createReadStream ile okuyun, parse({ columns: true }) üzerinden boru ile aktarın ve sonuçları toplayın. Tarayıcı kullanımı için, dosyayı FileReader ile okuyun, yeni satırlara göre bölün ve başlık satırını anahtar olarak kullanarak satırları nesnelere eşleyin.

Python’da CSV’yi JSON’a nasıl dönüştürürüm?

Satırları sözlük olarak okumak için standart kütüphaneden csv.DictReader kullanın, ardından bunları bir JSON dizisi olarak yazmak için json.dump() kullanın. Dönüştürmeden önce veri manipülasyonu için pandas.read_csv() ve ardından df.to_json(orient='records') tek satırlık bir alternatiftir.

Yuvalanmış JSON CSV’ye dönüştürülebilir mi?

Evet, ama bir düzleştirme stratejisine ihtiyacınız vardır. En yaygın yaklaşım nokta gösterimi kullanır: address.city gibi bir alan sütun başlığı olur. Python’da pandas.json_normalize() bunu otomatik olarak yapar. Diziler ek kararlar gerektirir — karakter dizisi olarak birleştirme, sütunlara genişletme veya satırlara genişletme.

Dönüştürmeden sonra CSV’mde neden bozuk karakterler var?

Kodlama uyumsuzluğu. Dosya büyük olasılıkla Windows-1252 veya GBK olarak kaydedilmiştir ama ayrıştırıcınız UTF-8 varsayar. Kodlamayı tanımlamak için chardet (Python) gibi bir tespit kütüphanesi kullanın, ardından okurken açıkça belirtin. Ayrıca bazı araçların otomatik olarak eklediği bir UTF-8 BOM olup olmadığını denetleyin.

100 MB’tan büyük bir CSV dosyasını nasıl ele alırım?

Tüm dosyayı belleğe yüklemek yerine akışı kullanın. Node.js’te csv-parse üzerinden akışlarla boru ile aktarın. Python’da bir üretici kullanarak csv.DictReader ile yineleyin. Sonraki aşamadaki işlemeyi kolaylaştırmak için tek bir JSON dizisi yerine JSON Lines (.jsonl) formatı çıkarmayı düşünün.

Dönüştürdüğüm JSON’un geçerli olduğunu nasıl doğrularım?

Söz dizimi, yapı ve yuvalamayı denetlemek için çıktıyı çevrimiçi bir JSON Biçimlendirici içine yapıştırın. Otomatik doğrulama için JavaScript’te JSON.parse() veya Python’da json.loads() kullanın — her ikisi de geçersiz girdide net hatalar fırlatır. Şema doğrulaması için bir JSON Schema tanımlayın ve programlı olarak doğrulayın.

Temel Çıkarımlar

Bağlamınız için doğru yöntemi seçin: hızlı tek seferlik işler için tarayıcı araçları, otomasyon için kod, pipeline’lar için CLI.
Kodlama sorunlarına dikkat edin — varsayılanlara güvenmek yerine her zaman kodlamayı açıkça belirtin.
Tipleri kasıtlı olarak koruyun — baştaki sıfırlar, büyük tam sayılar ve null değerlerin tümü açık ele alma gerektirir.
Büyük dosyaları belleğe yüklemek yerine akış olarak işleyin. Çok büyük veri kümeleri için JSON Lines formatını düşünün.
Çıktınızı doğrulayın — yapısal sorunları üretime ulaşmadan yakalamak için dönüştürülmüş JSON’u bir JSON Biçimlendirici üzerinden çalıştırın.

CSV'den JSON'a Dönüştürme: Yöntemler, Tuzaklar ve Kod Örnekleri