JSON nasıl biçimlendirilir ve doğrulanır: geliştirici rehberi

JSON her yerde: API yanıtları, yapılandırma dosyaları, günlükler, mesaj kuyrukları, istek yükleri, veritabanı sütunları. Bu kadar basit bir format için ne sık sorun yaşadığımız şaşırtıcı — eksik bir virgül bir dağıtımı bozar, fazladan bir boşluk iki dosyayı “farklı” yapar, derin iç içe geçmiş bir yapı hiç kimse girintilemediği için hata ayıklanamaz.

JSON’un gerçekte izin verdiği şeyler

JSON spesifikasyonu kasıtlı olarak küçük. Bir JSON belgesi şunlardan biri:

• Bir nesne: { "key": value, ... }
• Bir dizi: [ value, ... ]
• Bir dize: "text" (her zaman çift tırnaklı, asla tek tırnaklı değil)
• Bir sayı: 42, 3.14, -2.5e10
• Bir boolean: true veya false
• null

Bu kadar. Yorum yok. Sondaki virgül yok. Tırnaksız anahtarlar yok. Tek tırnaklı dizeler yok. undefined yok. NaN veya Infinity yok. Fonksiyon yok.

Bir JSON çözümleyicinin “açıkça geçerli” dosyanızı neden reddettiğini merak ettiyseniz, genellikle bunlardan biri:

{
 "name": "Alice",
 "age": 30, // ← yorum: JSON olarak geçerli DEĞİL
 "email": 'alice@...', // ← tek tırnak: JSON olarak geçerli DEĞİL
 role: "admin", // ← tırnaksız anahtar: JSON olarak geçerli DEĞİL
 "active": true, // ← sondaki virgül: JSON olarak geçerli DEĞİL
}

Bu rahatlıkları destekleyen formatlar var: JSON5 (yorumlara, sondaki virgüllere, tırnaksız anahtarlara izin verir) ve JSONC (VS Code yapılandırma dosyaları tarafından kullanılır). JSON’un üst kümesi ama özel çözümleyici gerektirirler.

JSON’u okunabilir yapan biçimlendirme

Küçültülmüş JSON şöyle görünür:

{"users":[{"id":1,"name":"Alice","roles":["admin","editor"]},{"id":2,"name":"Bob","roles":["viewer"]}]}

Biçimlendirilmiş JSON şöyle:

{
 "users": [
 {
 "id": 1,
 "name": "Alice",
 "roles": ["admin", "editor"]
 },
 {
 "id": 2,
 "name": "Bob",
 "roles": ["viewer"]
 }
 ]
}

Aynı veri, tamamen farklı okunabilirlik.

Önemli biçimlendirme kuralları:

• Girinti: 2 boşluk. Açık ara en yaygın kural. Bazı kod tabanları 4 kullanır; sekmeler nadirdir. Bir proje içinde tutarlı olun.
• Nesneler içinde satır başına bir anahtar, dizilerde öğe başına bir satır
• İki nokta üst üsteden sonra boşluk: "key": value
• Kısa ilkel değerlerin dizileri tek satırda: "roles": ["admin", "editor"] iyidir
• Nesnelerin dizileri her zaman birden çok satırda — aksi takdirde hızla okunamaz hale gelir

JSON Formatter aracımız Format’a tıkladığınızda bunların hepsini otomatik uygular.

JSON doğrulama: nelere dikkat etmeli

1. Eksik veya fazla virgül

Açık ara en yaygın. Neredeyse her sözdizimsel hata bir virgül sorunudur.

{
 "a": 1,
 "b": 2 ← eksik virgül
 "c": 3
}

Dikkat: çözümleyici eksik virgülden sonraki satırı suçlar. Yanıltıcı.

2. Kapanmamış dize

Dize içinde başıboş satır sonu veya eksik kapanış tırnağı:

{ "name": "Alice
}

JSON, dizeler içinde gerçek satır sonlarına izin vermez. \n olarak kaçırılmalı.

3. Eşleşmeyen parantezler

Dosyanın herhangi bir yerinde fazladan } veya ]. Çoğu çözümleyici eşleşmeyen ilk parantezi raporlar — gerçek hatadan uzak olabilir.

4. Geçersiz sayı

Baştaki + yok, baştaki sıfırlar yok (0.x hariç), 1. gibi sonucu olmayan ondalık yok, .5 gibi sıfırsız baştaki nokta yok.

{ "a": +5, "b": 07, "c": 1., "d": .5 } ← hepsi geçersiz

5. Kaçırılmamış karakterler

{ "path": "C:\Users\Alice" } ← geçersiz
{ "path": "C:\\Users\\Alice" } ← geçerli

6. Yinelenen anahtarlar

JSON spesifikasyonu bunu “tavsiye edilmez” olarak tanımlar. Çoğu çözümleyici sessizce son değeri alır. Bu neredeyse her zaman bir hata.

{ "name": "Alice", "name": "Bob" }

Pratikte nasıl biçimlendirilir ve doğrulanır

En hızlı iş akışı:

1. Şüpheli JSON’u bir biçimlendiriciye yapıştırın
2. Format’a tıklayın
3. Kabul ederse biçimlendirilmiş çıktıyı okuyun
4. Reddederse hata mesajını dikkatlice okuyun — satır numarası genellikle gerçek soruna yakın ama tam üstüne değil

JSON Formatter tam olarak bunu yapar. Tarayıcının yerleşik JSON.parse’ını kullanır — her Node.js API ve web servisi tarafından kullanılan aynı çözümleyici. Gördüğünüz hata mesajı, gerçek kodun JSON.parse() çağırdığında alacağıyla aynı.

Minify / Format anahtarı

Biçimlendiricilerin genellikle iki düğmesi var:

• Format (ya da Beautify, Pretty-print): insan okuması için boşluk ve girinti ekler
• Minify (ya da Compact): tüm gereksiz boşlukları kaldırır

Küçültülmüş JSON bayt boyutunu önemsediğinizde kullanılır — kablo üzerinden gönderim, veritabanı depolama, URL’ye gömme. Biçimlendirilmiş JSON ile işlevsel olarak aynı ama büyük belgeler için belirgin şekilde daha küçük:

Biçimlendirilmiş: 1.240 bayt
Küçültülmüş: 680 bayt (-%45)

Üretim API yanıtları için her zaman küçültün. Yapılandırma dosyaları ve insanların okuyacağı her şey için her zaman biçimlendirin.

Biçimlendirici ötesi araçlar

JSON’unuz geçerli ve biçimlendirilmiş olduğunda, onunla daha fazlasını yapmanız gerekebilir:

• JSON schema — geçerli bir belgenin hangi alanlara sahip olması gerektiğini türleri ve kısıtlamalarıyla tanımlar
• JMESPath / jq — JSON sorgu dilleri; jq fiili komut satırı aracı
• JSON diff — iki JSON belgesi arasındaki farkı metin diff’inden daha yararlı şekilde gösteren araçlar

Günlük biçimlendirme için genellikle gerekmez ama düzenli JSON çalışıyorsanız bilmeye değer.

Hızlı referans

İhtiyaç	Ne yapmalı
JSON’u okunabilir yap	2 boşluk girintiyle biçimlendır
Aktarım için küçült	Küçült
Sözdizimi hatası bul	Bir biçimlendiriciye yapıştır
İki belgenin aynı olup olmadığını kontrol et	İkisini de küçült ve karşılaştır ya da JSON diff kullan
Yapı doğrulaması ekle	JSON Schema kullan
URL veya cookie’de depola	Küçült ve URI-kodla

Bir iş akışı ipucu

Değerli bir alışkanlık: ham JSON’u bir e-postaya, sohbet mesajına veya sorun takipçisine önce biçimlendirmeden asla yapıştırmayın. GitHub sorununda küçültülmüş JSON sınırda okunamazdır. Bir biçimlendiricide otuz saniye, duvar metnini okunabilir yapıya dönüştürür.

Gerçek bir API yanıtını debug ederken de aynı kural: önce biçimlendirmeye geçirin, sonra anlamaya çalışın. Bu tek alışkanlık girintisiz çıktıya gözlerini kısmaktan saatler kazandırır.

JSON Formatter tarayıcınızda çalışır — yükleme yok, sunucu gidiş dönüşleri yok, hiçbir şey hiçbir yere kaydedilmiyor. JSON’u yapıştırın, Format veya Minify’a tıklayın, kopyalayın, tamamdır.