Hatalı Biçimli JSON Dosyalarını Hızlıca Düzeltme: Geliştiriciler İçin Saha Kılavuzu

API çağrınız JSONDecodeError: Expecting property name enclosed in double quotes hatasıyla başarısız oldu. Saat işliyor. Veriler bir LLM’den geldi ve o 2.000 tokenlik yanıtta tek bir sonda virgülü tüm boru hattınızı çökertti.

Mayıs 2026 itibarıyla hatalı biçimli JSON dosyalarını düzeltmenin en hızlı yolu json_repair (Python) veya jsonrepair (npm) gibi otomatik kütüphaneler kullanmaktır. Bu araçlar, LLM tarafından üretilen sözdizimi hatalarını anında gidermek için özel olarak tasarlanmıştır. Manuel onarımlarda başlıca şüpheliler sonda virgüller, tek tırnaklar veya tırnaksız anahtarlar olur — bunlar RFC 8259 standardının en sık ihlal edilen üç kuralıdır.

En Hızlı Çözüm: LLM Çıktıları için json_repair

Python’un json.loads() gibi standart çözümleyicileri tasarımsal olarak katıdır. Yanlış konumlandırılmış tek bir karakter JSONDecodeError tetikler ve her şey durur. Bu, 2026’da gündelik bir sorundur çünkü LLM’ler JSON’u rutin olarak sohbet metni içine sarar, yanıtları cümlenin ortasında keser veya standardı bozan açıklamalar serpiştirir.

json_repair kütüphanesi başvurulacak çözümdür. GitHub bilgisine göre bu proje 2026 itibarıyla 4.700’ü aşkın yıldıza sahip. Çalışma prensibi, dizenin niyetini “tahmin etmek”tir — eksik köşeli parantezleri kapatır, tırnak ekler ve JSON bloğunu çevreleyen fazladan metni temizler.

Python: Öncesi ve Sonrası

Kurulum: pip install json-repair

Hatalı girdi:

import json_repair

bad_json = '{"user": "Alice", "status": tru'
decoded_object = json_repair.loads(bad_json)

Arka planda neler oldu: json_repair, tru ifadesinin muhtemelen true olduğunu fark etti, eksik kapanış ayracını ekledi ve geçerli bir Python sözlüğü döndürdü. Sıfır manuel müdahale.

Kurtarma Modu: Veri Gerçekten Berbatsa

Daha zor durumlar için json_repair (v0.59.5+) bir Kurtarma Modu (Salvage Mode) içerir. Proje belgelerinde belirtildiği üzere bu mod özellikle kesilmiş AI yanıtları veya bozuk günlük dosyaları için tasarlanmıştır. Dizileri zorla nesnelere dönüştürebilir ya da kurtarılamayacak kadar bozuk öğeleri atarak çıktının şemanıza uymasını sağlar.

import json_repair

# Salvage mode for severely truncated data
result = json_repair.loads(
    '{"items": [{"id": 1, "name": "Widget"}, {"id": 2, "na',
    salvage_mode=True
)
# Result: {'items': [{'id': 1, 'name': 'Widget'}, {'id': 2}]}
# Dropped the incomplete 'na' but saved everything else

npm Alternatifi

Node.js projeleri için jsonrepair CLI aynı işi halleder:

# Fix a file in place
npx jsonrepair broken.json > fixed.json

# Fix a string in a script
const { jsonrepair } = require('jsonrepair');
const fixed = jsonrepair('{"name": "test",}');

Manuel Hata Ayıklama: Standardı Bozan Şeyi Bulmak

Otomasyon yeterli olmadığında, dosyanın tam olarak nerede RFC 8259‘u ihlal ettiğini bulmanız gerekir. JSON, YAML veya JavaScript’ten çok daha az affedicidir. JSONParser Tanılama Ekibi‘nin açıkladığı gibi: “Çözümleyici, anlamlandıramadığı ilk karakterde başarısız olur ve bu çoğu zaman birkaç satır yukarıdaki bir sorunun aşağı yönlü bir belirtisidir.”

Üç JSON Katili

Katil 1: Sonda Virgüller

DEV Community bilgisine göre sonda virgülleri çözümleme başarısızlıklarının 1 numaralı nedenidir. JavaScript’te sorun değildirler ama bir JSON dizisininin veya nesnesinin son öğesinden sonra geçersizdirler.

// BROKEN - trailing comma after "active"
{
  "name": "Alice",
  "status": "active",
}

// FIXED - no comma before closing brace
{
  "name": "Alice",
  "status": "active"
}

Katil 2: Tek Tırnaklar

JSON, hem anahtarlar hem de dize değerleri için çift tırnak (") gerektirir. Pek çok Python ve JavaScript geliştiricisi yanlışlıkla tek tırnak (') kullanır. TidyCode‘nun belirttiği gibi bu zorunlu bir düzeltmedir.

// BROKEN - single quotes
{'name': 'Alice'}

// FIXED - double quotes
{"name": "Alice"}

Katil 3: Tırnaksız Anahtarlar

JavaScript’te { name: "Alice" } yazabilirsiniz. JSON’da ise her anahtarın çift tırnağa ihtiyacı vardır.

// BROKEN - unquoted key
{name: "Alice"}

// FIXED - quoted key
{"name": "Alice"}

“Unexpected Token” Hatası

Bir doğrulayıcı “Unexpected Token” bayrakladığında, çözümleyicinin NaN, Infinity veya undefined ile karşılaştığı anlamına gelir — bunlar JSON’ın desteklemediği JavaScript sabitleridir. JSON yalnızca null, true, false ve sayılara izin verir.

// BROKEN - NaN is not valid JSON
{"score": NaN, "result": Infinity}

// FIXED - replace with null or valid values
{"score": null, "result": null}

Katı Çözümleme ve Onarım Çözümlemesi: Hangisi Ne Zaman Kullanılır

Doğru yaklaşım, verilerinizin nereden geldiğine bağlıdır. İnsan tarafından düzenlenen yapılandırma dosyaları, yazarı hataları düzeltmeye zorlamak için katı çözümlemeyi hak eder. LLM’lerden veya API günlüklerinden gelen makine üretimi veriler ise onarım tabanlı çözümlemeye ihtiyaç duyar.

Pydantic ile Şema Kılavuzlu Onarımlar

Onarım sürecini Pydantic v2 veya JSON Schema ile yönlendirebilirsiniz. json_repair‘a bir şema verdiğinizde araç yalnızca sözdizimini düzeltmekle kalmaz — türleri de düzeltebilir (dize "1"‘i sayı 1‘e çevirir) ve eksik zorunlu alanları varsayılan değerlerle doldurabilir.

from pydantic import BaseModel
import json_repair

class User(BaseModel):
    id: int
    name: str
    active: bool = True

# Broken JSON with wrong types
raw = '{"id": "42", "name": "Alice"}'
repaired = json_repair.loads(raw)

# Validate against schema
user = User(**repaired)
# user.id is now int(42), user.active defaults to True

Stefano Baccianella‘nın 2025 proje atıfında belirttiği gibi, bu yaklaşım dil modellerinin üretmeye meyilli olduğu “çoğunlukla doğru ama teknik olarak geçersiz” JSON için optimize edilmiştir.

Çok Gigabaytlık Dosyaları Çökmeden İşleme

10KB’lık bir parçayı onarmak kolaydır. 2GB’lık bir dosyayı düzeltmek ise tüm RAM’inizi yemeyecek bir strateji gerektirir. Dosyanın tamamını belleğe yüklemek Bellek Yetersizliği (OOM) hatalarına yol açar.

Strateji 1: ijson ile Akış İşleme

Devasa veri kümeleri için verileri parça parça işlemek üzere ijson kullanın. Scrapfly‘ın belirttiği gibi ijson verileri artımlı olarak işler. Bunu, çözümlemeden önce sorunları satır satır düzelten bir temizlik betiğiyle eşleştirin.

import ijson

# Stream through a large JSON file
with open('huge_broken.json', 'r') as f:
    for item in ijson.items(f, 'records.item'):
        # Process each item individually
        process(item)

Strateji 2: Maksimum Verimlilik için CLI Boru Hattı

Büyük dosyalar için en bellek dostu yöntem jsonrepair CLI’yi kullanıp çıktıyı doğrudan yeni bir dosyaya boru hattıyla aktarmaktır:

# Streams repair, never loads full file into memory
jsonrepair large_broken.json > fixed.json

Bu, dosyayı Python’a veya bir tarayıcıya yüklemekten çok daha bellek dostudur.

Sonuç

json_repair gibi yapay zeka farkındalığına sahip kütüphaneler sayesinde hatalı biçimli JSON’u düzeltmek artık manuel bir iş değil. Yine de RFC 8259 temellerini — sonda virgül yok, tek tırnak yok, tırnaksız anahtar yok — anlamaya devam etmelisiniz; ancak 2026’da ölçek açısından veriler için otomasyon tek pratik yaklaşımdır.

İş akışı basittir: önce bir onarım kütüphanesi deneyin. O başarısız olursa, kesin sözdizimi hatasını konumlandırmak için bir doğrulayıcı kullanın. Bu, gelen veriler mükemmelden uzak olsa bile uygulamalarınızın çalışmaya devam etmesini sağlar.

SSS

JSON resmi olarak açıklamaları veya tek tırnakları destekler mi?

Hayır. RFC 8259 standardı açıklamaları kesinlikle yasaklar. Tek tırnaklar da geçersizdir — anahtarlar ve dizeler için yalnızca çift tırnağa izin verilir. Ancak json_repair gibi araçlar dosyaların standart kütüphanelerce çözümlenebilmesi için açıklamaları otomatik olarak temizleyip tırnakları dönüştürebilir.

Çok büyük ve hatalı biçimli JSON dosyalarını çökmeden nasıl işlerim?

Verileri öbekler halinde işlemek için ijson gibi bir akış çözümleyici kullanın. Hatalı dizenin tamamını tek bir değişkene yüklemekten kaçının. En hızlı sonuçlar için, çıktıyı bellekte her şeyi tutmadan doğrudan diskteki yeni bir dosyaya boru hattıyla aktaran CLI onarım araçlarını kullanın.

Hatalı biçimli JSON ile geçersiz JSON arasındaki fark nedir?

Hatalı biçimli (malformed) JSON sözdizimi kurallarını ihlal eder — eksik köşeli parantezler, tırnaksız anahtarlar, sonda virgüller — bu yüzden çözümlenmesi imkansızdır. Geçersiz (invalid) JSON tüm sözdizimi kurallarına uyar ama belirli bir JSON Schema’ya uyum sağlayamaz (örneğin bir alan, şema tamsayı beklerken dizedir). Hatalı biçimli JSON’u düzeltmek yapısal onarımdır; geçersiz JSON’u düzeltmek ise veri bütünlüğüyle ilgilidir.

json_repair’i Pydantic doğrulamasıyla birlikte kullanabilir miyim?

Evet. Önce sözdizimi hatalarını düzeltmek için json_repair.loads() çalıştırın, ardından tür doğrulaması ve şema zorlaması için onarılmış sözlüğü Pydantic modelinize aktarın. Bu iki adımlı yaklaşım hem yapısal hem de anlamsal sorunları ele alır.

JavaScript tarzı açıklamalı JSON’a ne demeli?

Standart JSON açıklamaları desteklemez ama json_repair // ve /* */ açıklamalarını otomatik olarak temizleyebilir. Yapılandırma dosyalarınızda açıklamalara ihtiyaç duyuyorsanız JSONC (Açıklamalı JSON) biçimini ve Python için json5 gibi uyumlu bir çözümleyiciyi düşünün.