JSON Nedir? JSON Formatı Ne İşe Yarar, Nasıl Okunur?

JSON (JavaScript Object Notation, JavaScript Nesne Gösterimi), veriyi anahtar-değer çiftleri ve listeler hâlinde saklamaya ve taşımaya yarayan, sade ve hafif bir metin biçimidir. Adında JavaScript geçse de dilden bağımsızdır; PHP, Python, Java, Go ve neredeyse tüm programlama dilleri JSON'u okuyup yazabilir. Bugün web ve mobil uygulamaların sunucularla konuştuğu API'lerin büyük çoğunluğu veriyi JSON olarak gönderir.

Yazar Haber Ajansı'nın (YHA) JSON döndüren API'sini kullanmak istiyorsanız uç noktalar ve kod örnekleri için Yazar Haber Ajansı API belgelerine geçebilirsiniz.

JSON'un Kısa Tarihçesi

JSON, 2000'lerin başında JavaScript'in nesne yazım sözdiziminden esinlenerek tarif edildi ve kısa sürede tarayıcı ile sunucu arasındaki veri alışverişinde XML'e hafif bir alternatif olarak yaygınlaştı. Biçimin popülerleşmesinde Douglas Crockford'un çalışmaları ve json.org sitesi önemli rol oynadı. Bugün JSON iki ayrı standartla tanımlanır: IETF'in RFC 8259 belgesi ve Ecma International'ın ECMA-404 standardı. İkisi aynı sözdizimini tarif eder.

JSON Ne İşe Yarar?

JSON'un başlıca kullanım alanları şunlardır:

1. API iletişimi: Bir uygulama sunucudan veri istediğinde yanıt çoğunlukla JSON'dur. API kavramını API nedir yazımızda anlattık.
2. Yapılandırma dosyaları: Pek çok yazılım ayarlarını JSON dosyalarında tutar.
3. Veri saklama: Bazı veritabanları kayıtları doğrudan JSON benzeri belgeler olarak saklar.
4. Yapılandırılmış veri (SEO): Arama motorlarına sayfa hakkında bilgi veren şema işaretlemesi JSON-LD biçiminde yazılır. Bu sayfanın kaynak kodunda da bir JSON-LD bloğu bulunur.
5. Dosya ve günlük kayıtları: Uygulama logları ve dışa aktarılan veriler sıkça JSON biçimindedir.

JSON Formatı: Bir Haberin JSON Hâli

Aşağıda bir haber ajansının API'sinden dönebilecek bir haber nesnesinin örnek hâlini görüyorsunuz. Alan adları kavramı göstermek için seçilmiştir:

{
  "id": "h-102938",
  "baslik": "Merkez Bankası faiz kararını açıkladı",
  "ozet": "Para Politikası Kurulu toplantısının ardından karar duyuruldu.",
  "kategori": "ekonomi",
  "yayin_tarihi": "2026-10-24T14:05:00+03:00",
  "guncellendi": false,
  "kelime_sayisi": 412,
  "etiketler": ["faiz", "para politikası", "enflasyon"],
  "gorsel": {
    "url": "https://cdn.ornek-ajans.com/faiz.jpg",
    "genislik": 1600,
    "yukseklik": 900,
    "aciklama": "Kurul toplantısından bir görüntü"
  },
  "video": null
}

Bu küçük örnekte JSON'un tüm temel yapı taşları yer alıyor: bir nesne, nesnenin içinde metinler, sayılar, mantıksal değer, liste, iç içe bir nesne ve boş değer. Dikkat ederseniz belge, hiçbir açıklama olmadan da okunabiliyor: baslik alanının haberin başlığı, etiketler dizisinin haberin anahtar kelimeleri olduğu kolayca anlaşılıyor. JSON'un bu kadar yaygınlaşmasının en önemli sebeplerinden biri de bu okunabilirliktir.

JSON Veri Türleri

JSON yalnızca altı tür değer tanır. Bu sadelik, onu öğrenmeyi ve her dilde işlemeyi kolaylaştırır:

Dikkat edilmesi gereken bir nokta: JSON'da tarih türü yoktur. Tarihler metin olarak yazılır. Farklı sistemlerin aynı tarihi aynı şekilde anlaması için ISO 8601 / RFC 3339 biçimini (2026-10-24T14:05:00+03:00) saat dilimiyle birlikte kullanmak en güvenli yoldur. Saat dilimi yazılmazsa haber, alıcı tarafta saatlerce kaymış görünebilir.

JSON Yazım Kuralları

JSON'un kuralları azdır ama katıdır. Bir kuralın ihlali, tüm belgenin okunamamasına yol açar:

• Anahtarlar her zaman çift tırnak içinde yazılır: "baslik" doğru, baslik veya 'baslik' yanlıştır.
• Metin değerleri de çift tırnak kullanır; tek tırnak geçersizdir.
• Çiftler ve dizi öğeleri virgülle ayrılır, ancak son öğeden sonra virgül konmaz.
• Yorum satırı yoktur. // veya /* */ ile açıklama eklemek belgeyi bozar.
• true, false ve null küçük harfle yazılır.
• Metin içindeki çift tırnak, ters bölü ve satır sonu gibi özel karakterler kaçış dizisiyle yazılır: \", \\, \n.
• Belge UTF-8 kodlamasıyla taşınmalıdır; RFC 8259, kapalı bir sistemin parçası olmayan sistemler arasındaki aktarımda UTF-8'i şart koşar. Türkçe karakterler doğrudan yazılabilir veya \u00e7 (ç) gibi Unicode kaçışıyla gösterilebilir.

En Sık Yapılan JSON Hataları

Bu hataların çoğu JSON'u elle yazarken veya metinleri birleştirerek "kendi JSON'unuzu" üretmeye çalışırken ortaya çıkar. JSON üretirken her zaman dilinizin yerleşik fonksiyonlarını kullanın: PHP'de json_encode, Python'da json.dumps, JavaScript'te JSON.stringify.

JSON Nasıl Okunur?

JSON düz metin olduğu için herhangi bir metin düzenleyiciyle açılabilir. Tek satırda sıkıştırılmış büyük bir yanıtı okumak zordur; bu yüzden şu araçlar işinizi kolaylaştırır:

• Tarayıcılar: Firefox, JSON yanıtlarını katlanabilir ağaç görünümünde gösterir; diğer tarayıcılara eklentiyle bu özellik eklenebilir.
• Kod düzenleyiciler: JSON'u biçimlendirir, hataların yerini işaretler.
• Komut satırı: jq gibi araçlarla JSON filtrelenip biçimlendirilebilir.

Programlama dillerinde JSON okumak tek satırlık bir iştir. Aşağıdaki örnekler, yukarıdaki haber nesnesinden başlığı okur:

<?php
$haber = json_decode($yanit, true, 512, JSON_THROW_ON_ERROR);
echo $haber['baslik'];

import json
haber = json.loads(yanit)
print(haber["baslik"])

PHP örneğindeki JSON_THROW_ON_ERROR bayrağı, bozuk bir JSON geldiğinde sessizce null dönmek yerine hata fırlatır; böylece sorunu gözden kaçırmazsınız.

JSON Schema ile Doğrulama

İki sistem düzenli olarak JSON alışverişi yapıyorsa, gelen verinin beklenen yapıda olup olmadığını kontrol etmek önemlidir: her haberin bir id'si ve baslik'ı var mı, yayin_tarihi gerçekten tarih biçiminde mi? Bu kurallar JSON Schema ile tanımlanabilir. Şema, bir anlamda iki taraf arasındaki veri sözleşmesidir ve hatalı verinin sisteminize girmeden yakalanmasını sağlar.

JSON'un Türevleri

JSON'un sadeliği, belirli ihtiyaçlar için türevlerinin ortaya çıkmasına da yol açtı:

• JSON-LD: Bağlantılı veri için JSON. Google'ın önerdiği yapılandırılmış veri biçimidir; makale, ürün, etkinlik gibi bilgileri arama motorlarına anlatır.
• JSON Lines (NDJSON): Her satırda bir JSON nesnesi bulunur. Çok büyük veri setlerini satır satır işlemek ve log kaydı tutmak için idealdir.
• GeoJSON: Harita ve konum verisi için standartlaşmış bir JSON yapısıdır.

JSON ile XML Arasındaki Fark

JSON'dan önce sistemler arası veri alışverişinde en yaygın biçim XML'di. İkisi de aynı haberi taşıyabilir; fark yaklaşımdadır:

Aynı haberin XML karşılığını ve XML'in kurallarını XML nedir yazımızda bulabilirsiniz. Kısa bir özet: web API'lerinde JSON fiilî standarttır; RSS beslemeleri, site haritaları ve bazı kurumsal sistemlerde ise XML yaygınlığını korur.

Haber Entegrasyonunda JSON'la Çalışırken İpuçları

Haber verisini JSON olarak alan bir geliştirici için birkaç pratik öneri:

1. Kimliği esas alın: Haberleri başlığa göre değil, benzersiz id alanına göre eşleyin. Başlık düzeltilebilir, kimlik değişmez.
2. Bilinmeyen alanları görmezden gelin: Sağlayıcı yeni bir alan eklediğinde kodunuz bozulmamalıdır.
3. Boş değerlere hazırlıklı olun: null gelen bir görsel alanı sayfanızda kırık bir görsele dönüşmemelidir.
4. HTML içeriği temizleyin: Haber gövdesi HTML içeriyorsa, sitenize basmadan önce izin verilen etiketler dışında kalanları temizleyin.
5. Saat dilimini koruyun: Tarihleri veritabanınıza yazarken saat dilimini kaybetmeyin.

Büyük JSON Yanıtlarıyla Çalışmak

Bir haber ajansının arşivinde on binlerce haber bulunabilir. Bunların hepsini tek bir JSON yanıtında göndermek hem sunucuyu hem de istemciyi zorlar: yanıtın indirilmesi uzun sürer, bellek tüketimi artar ve küçük bir bağlantı kopması tüm işi boşa çıkarır. Bu yüzden API'ler büyük listeleri sayfalama ile parçalara böler. Yanıtın içinde genellikle bir sonraki sayfanın adresini veya bir imleç (cursor) değerini taşıyan bir alan bulunur; istemci bu değeri bir sonraki isteğe ekleyerek listeyi parça parça alır.

Çok büyük veri dışa aktarımlarında ise JSON Lines biçimi tercih edilebilir. Her satır bağımsız bir JSON nesnesi olduğu için dosyanın tamamını belleğe yüklemeden satır satır işlemek mümkündür. Yarıda kesilen bir aktarımda da yalnızca son satır kaybolur, öncekiler kullanılabilir kalır.

JSON ve Güvenlik

JSON'un kendisi zararsız bir metin biçimidir; riskler, JSON'un nasıl işlendiğinden doğar. Dikkat edilmesi gereken başlıca noktalar:

• JSON'u kod olarak çalıştırmayın. Eski JavaScript örneklerinde görülen eval() ile JSON okuma yöntemi, kötü niyetli bir yanıtın kod çalıştırmasına izin verir. Her zaman JSON.parse gibi güvenli ayrıştırıcıları kullanın.
• Gelen metni olduğu gibi sayfaya basmayın. JSON içindeki bir başlık veya gövde, HTML ya da betik içerebilir. Sayfanıza yazmadan önce kaçış uygulayın veya izin verilen etiketlerle sınırlandırın; aksi hâlde siteler arası betik çalıştırma (XSS) açığı oluşabilir.
• Boyut sınırı koyun. Beklenmedik büyüklükteki bir yanıtı ayrıştırmaya çalışmak sunucunuzun belleğini tüketebilir.
• Gizli bilgileri JSON yanıtlarında taşımayın. API anahtarları ve parolalar, tarayıcıya giden yanıtlarda yer almamalıdır.

Yazar Haber Ajansı'nda JSON Nasıl Kullanılır?

Yazar Haber Ajansı API'si, haberleri JSON formatında döndürür. Akış, haber listesi, tekil haber ve arama yanıtlarının hepsi UTF-8 kodlu JSON nesneleri olarak gelir; zamanlar ISO 8601 biçiminde ve UTC'dir. Bu sayede verileri herhangi bir programlama diliyle kolayca işleyebilirsiniz. Yanıtın tam alan listesi, sayfalama yapısı, hata yanıtlarının biçimi ve curl, Python, JavaScript ve C# örnekleri Yazar Haber Ajansı API belgelerinde anlatılıyor.

Bir fikir vermesi için: YHA'nın haber nesnesinde başlık baslik, spot spot, haber metni govde, kategori kategori alanında gelir; düzeltmelerde surum_no artar. Listeler ogeler, sonraki_imlec ve devami_var alanlarıyla imleçli olarak sayfalanır; hatalar ise { "hata": { "kod", "mesaj", "belge" } } biçimindedir. Yanıtta tanımadığınız yeni bir alan görürseniz yok saymanız istenir; bu, yukarıdaki "bilinmeyen alanları görmezden gelin" önerisinin uygulamadaki karşılığıdır.

Anlık bildirim isteyenler için YHA webhook bildirimleri de olay verisini JSON gövdesiyle iletir. Tüm entegrasyon seçeneklerini Yazar Haber Ajansı geliştirici belgeleri sayfasında karşılaştırabilirsiniz.

Sıkça Sorulan Sorular

JSON bir programlama dili mi?

Hayır. JSON bir veri biçimidir; komut çalıştırmaz. Yalnızca veriyi düzenli bir şekilde temsil eder.

JSON dosyası nasıl açılır?

Herhangi bir metin düzenleyiciyle açılabilir. Daha rahat okumak için tarayıcıda açabilir veya JSON biçimlendirme özelliği olan bir kod düzenleyici kullanabilirsiniz.

JSON'a yorum satırı eklenebilir mi?

Standart JSON yorum satırını desteklemez. Açıklama gerekiyorsa ayrı bir alan (ör. "_not") eklemek veya belgeyi ayrı tutmak gerekir.

JSON mu daha iyi, XML mi?

İhtiyaca bağlıdır. Web ve mobil API'lerde JSON daha hafif ve pratiktir. Belge benzeri içerik, karma metin ve sıkı doğrulama gerektiren yerlerde XML avantajlı olabilir.

JSON'da Türkçe karakter kullanılabilir mi?

Evet. JSON UTF-8 ile taşındığında Türkçe karakterler doğrudan yazılabilir.