JSON Nedir? Örneklerle Sade Bir Rehber

JSON (JavaScript Object Notation), müşteri, sipariş ya da ürün listesi gibi yapılandırılmış verileri ad ve değer çiftleri halinde yazmak için kullanılan basit bir metin biçimidir. İnsanların okuması kolaydır, programların üretmesi ve çözümlemesi de kolaydır. Uygulamalar ve servisler web üzerinde veri alışverişi yaptığında en yaygın biçim JSON’dur.

Yapay zekâyla yapı kurarken JSON neden önemli?

Kod yazmasanız bile JSON’la sürekli karşılaşırsınız:

• API’ler. Uygulamanızın ekranları arka ucundan veri yüklediğinde ya da arka ucunuz bir ödeme, e-posta veya yapay zekâ servisini çağırdığında veri genellikle JSON olarak gider. Bkz. API nedir.
• Ayar dosyaları. Birçok proje yapılandırma dosyası JSON’dur; örneğin bir JavaScript projesinin bağımlılıklarını listeleyen package.json.
• Veritabanları. Postgres, düzenli satır ve sütunlara uymayan veriler için bir sütunda JSON saklayabilir (jsonb türü). Bkz. Postgres nedir.
• Yapay zekâ çıktıları. Bir yapay zekâ modelinden bir programın kullanabileceği bir şey istediğinizde (etiket listesi, fatura alanlarını ayıklama gibi), genellikle JSON istersiniz.
• Hata mesajları ve günlükler. Birçok hata JSON olarak gelir; hatanın ne olduğunu bulmanın en hızlı yollarından biri de bunu okumaktır.

JSON okuyabilmek, uygulamanızın gerçekte ne aldığını kontrol etmenizi, eksik bir alanı görmenizi ve sorunları yapay zekâ oluşturucunuza kesin biçimde anlatmanızı sağlar.

Günlük bir benzetme

Kağıt bir formu düşünün: Ad: ____, Telefon: ____, Bülten: ☐ evet ☐ hayır. Her girdi bir etiket ve yanındaki değerdir. JSON, bu formun bilgisayarın tahmin yürütmeden okuyabileceği katı bir düzende metin olarak yazılmış halidir. Formlar gibi, JSON da iç içe bölümler (sokak, şehir ve posta kodunu içeren bir adres bloğu) ve listeler (birkaç telefon numarası) içerebilir.

JSON neye benzer?

Tek bir randevu JSON’da şöyle görünür:

{
  "id": 5001,
  "customer": "Lena Park",
  "service": "Haircut",
  "startsAt": "2026-10-03T14:00:00Z",
  "price": 35.5,
  "paid": false,
  "notes": null,
  "extras": ["beard trim", "hot towel"],
  "contact": {
    "email": "lena@example.com",
    "phone": "+44 20 7946 0000"
  }
}

Okuması şöyle:

• Süslü parantezler { } bir nesneyi sarar: bir dizi ad ve değer çifti.
• Her çift "ad": değer biçimindedir ve virgüllerle ayrılır.
• Köşeli parantezler [ ] bir diziyi, yani sıralı bir listeyi sarar.
• Nesneler ve diziler, contact ve extras örneğinde olduğu gibi birbirinin içine girebilir.

Altı değer türü

JSON’da yalnızca altı tür değer vardır. Bu küçük liste, JSON’un her yerde çalışmasının önemli bir nedenidir.

JSON’da tarih türü yoktur. Tarihler metin olarak yazılır; genellikle yukarıda gösterilen ISO 8601 biçiminde (2026-10-03T14:00:00Z; buradaki Z, UTC anlamına gelir). Bu biçim üzerinde anlaşmak, bir dizi saat dilimi hatasını önler.

Katı kurallar (hatalar nereden gelir)

JSON göründüğünden daha az hoşgörülüdür. Şunların hepsi geçersizdir:

{ name: "Lena" }            ← çift tırnaksız anahtar
{ 'name': 'Lena' }          ← tek tırnak
{ "a": 1, "b": 2, }         ← sondaki virgül
{ "a": 1 "b": 2 }           ← eksik virgül
{ "a": 1 // yorum }         ← yorumlara izin verilmez

Gördüğünüz “Unexpected token” hatalarının çoğu bunlardan biridir. Bir JSON doğrulayıcı ya da biçimlendirici hatanın tam satırını gösterir.

Çalışılmış bir örnek: bir uygulamada JSON’un akışı

Bir müşteri, bir kuaför uygulamasında saç kesimi randevusu alıyor. JSON’un nerede göründüğü şöyle:

1. Randevu formu uygulamanın arka ucuna şunu gönderir:

{ "service": "Haircut", "startsAt": "2026-10-03T14:00:00Z", "name": "Lena Park" }

1. Arka uç randevuyu veritabanına kaydeder ve 201 Created durumu ile şunu döndürür:

{ "id": 5001, "status": "confirmed" }

1. Saat zaten doluysa, bunun yerine 409 Conflict durumu ve şunu döndürebilir:

{ "error": "slot_taken", "message": "That time was just booked. Please pick another." }

Sayfa status ya da error alanını okuyup doğru mesajı gösterir. Sayfa boş bir ekran gösteriyorsa, tarayıcının geliştirici araçlarını (Network sekmesi) açmak size bu JSON’u gösterir; çoğu zaman sorunun ipucu buradadır.

Temel terimler

Yaygın yanlış anlamalar

• “JSON, JavaScript’tir.” Söz dizimi JavaScript’ten gelir, ama dilden bağımsızdır; Python, Java, C#, Go ve diğerleri de onu okur.
• “Tırnak içindeki sayılar sorun değil.” "35" bir sayı değil, metindir. Karıştırmak "35" + "5" ifadesinin "355" olması gibi hatalara yol açar. Para genellikle yuvarlama sorunlarını önlemek için tam kuruş olarak (3550) saklanır.
• “Veri olduğu için JSON güvenlidir.” JSON her şeyi taşıyabilir, gizli bilgileri de dahil. Tarayıcıya gönderilen bir JSON’a API anahtarı koymayın.
• “Her şeyi bir JSON sütununa koy.” Esnek ek alanlar için pratiktir, ama aradığınız, filtrelediğiniz veya birleştirdiğiniz veriler genellikle düzgün sütunlarda olmalıdır.
• “Yapay zekâ her zaman geçerli JSON döndürür.” Modeller fazladan metin ekleyebilir ya da biçimi bozabilir. Birçok sağlayıcı yapılandırılmış çıktı modu sunar; yine de kodunuz geri gelen veriyi kontrol etmelidir.

Yapay zekâ oluşturucunuzdan ne isteyin

• “Bu uç noktanın döndürdüğü JSON’un bir örneğini göster.”
• “Hataları bir error kodu ve insanların okuyabileceği bir message ile JSON olarak döndür.”
• “Tarihleri UTC’de ISO 8601 metni olarak sakla ve yerel saate yalnızca ekranda çevir.”
• “Fiyatları tam sayı kuruş olarak sakla.”
• “Gelen JSON’u sunucuda doğrula; eksik ya da yanlış türde alanları olan istekleri reddet.”
• “Yapay zekâ modelini çağırırken JSON’u tam bu biçimde iste ve kullanmadan önce kontrol et.”

Mythex’te JSON

Mythex’te JSON’u elle yazmanız gerekmez: ne istediğinizi anlatırsınız, ajan onu gönderen ve okuyan kodu yazar. Yine de tanımak yardımcı olur; bir şey bozulduğunda JSON hatasını sohbete yapıştırmak ajana kesin bir ipucu verir. Dokümanlardaki REST API arka ucu tarifi baştan “açık JSON hataları” ister; herhangi bir API’yi entegre et tarifi de dış servisleri çağırmayı anlatır. Daha geniş resim için bkz. REST ve GraphQL ve yapay zekâyla yapılmış bir uygulamadaki hatalar nasıl ayıklanır.

Sorular