Free Instant Tools
Menü
dev 12 dk okuma |

JSON Şema Doğrulaması İçin Kapsamlı Rehber: Veri Bütünlüğünü Sağlama

Modern yazılım geliştirme dünyasında veri, her uygulamanın can damarıdır. İster mikro hizmetler arasında değiş tokuş edilsin, ister bir istemciden sunucuya gönderilsin veya bir NoSQL veritabanında saklansın, bu verilerin bütünlüğü ve yapısı büyük önem taşır. JSON (JavaScript Object Notation), basitliği ve insan tarafından okunabilir formatı sayesinde veri değişimi için fiili standart haline gelmiştir. Ancak, JSON'un esnekliği aynı zamanda bir zayıflık da olabilir: Kuralları uygulamanın bir yolu olmazsa, uygulamanız beklenmedik veriler alabilir ve bu da çökmelere, güvenlik açıklarına veya tutarsız durumlara yol açabilir.

İşte bu noktada JSON Şema devreye girer. JSON belgelerine açıklama eklemek ve bunları doğrulamak için güçlü, bildirimsel (declarative) bir dil sunarak verilerin önceden tanımlanmış bir yapıya uymasını sağlar. Bu kılavuzda, temel kavramlardan gelişmiş şema bileşimine kadar her şeyi keşfedeceğiz.

JSON Şema Nedir?

JSON Şema, JSON belgelerine açıklama eklemenize ve bunları doğrulamanıza olanak tanıyan bir sözlüktür. Bunu verileriniz için bir "plan" (blueprint) olarak düşünün. Bir veritabanı şemasının bir tablodaki sütunları ve türleri tanımlaması gibi, bir JSON Şema da bir JSON nesnesinin anahtarlarını, türlerini ve kısıtlamalarını tanımlar.

Aşağıdaki konularda net bir yol sağlayan bir IETF standardıdır (şu anda birden fazla taslak halindedir):

  • Mevcut veri formatınızı tanımlama.
  • Net, insan ve makine tarafından okunabilir dokümantasyon sağlama.
  • Otomatik testler ve istemci/sunucu tarafı doğrulaması için verileri doğrulama.

JSON Şema kullanarak, doğrulama mantığını emir kipi (imperative) kodunuzdan (if-ifadeleri) çıkarıp farklı programlama dilleri ve platformlar arasında paylaşılabilen bildirimsel bir formata taşırsınız.

Temel Kavramlar ve Temel Türler

Her JSON Şeması kendisi de bir JSON nesnesidir. En basit haliyle bir şema boş bir nesne {} olabilir ve bu her türlü JSON'u doğrular. Şemayı kullanışlı hale getirmek için anahtar kelimeleri kullanarak kısıtlamalar tanımlarız.

type Anahtar Kelimesi

type anahtar kelimesi en temel kısıtlamadır. JSON verilerini aşağıdaki temel türlerden biriyle sınırlandırır:

  • string: Metinsel veriler için.
  • number: Herhangi bir sayısal değer için (tamsayı veya kayan noktalı).
  • integer: Sadece tam sayılar için.
  • boolean: true veya false.
  • object: Anahtar-değer çiftleri için.
  • array: Sıralı değer listeleri için.
  • null: Null değeri için.

Nesneler ve Özellikler

Bir object tanımlarken, genellikle belirli anahtarlar için şemayı tanımlamak üzere properties anahtar kelimesini kullanırsınız. required anahtar kelimesi, veride MUTLAKA bulunması gereken anahtarları listelemek için kullanılır.

{
  "type": "object",
  "properties": {
    "username": { "type": "string" },
    "age": { "type": "integer" }
  },
  "required": ["username"]
}

Bu örnekte, "username" zorunludur ve bir dize olmalıdır; "age" ise isteğe bağlıdır ancak sağlanırsa bir tam sayı olmalıdır.

Doğrulama Anahtar Kelimelerine Derinlemesine Bakış

JSON Şema, doğrulama kurallarınıza ince ayar yapmanız için zengin bir anahtar kelime seti sunar.

Sayısal Doğrulama

number ve integer türleri için aralıklar uygulayabilirsiniz:

  • minimum ve maximum: Dahil edici sınırlar.
  • exclusiveMinimum ve exclusiveMaximum: Hariç tutucu sınırlar.
  • multipleOf: Sayının belirli bir değere bölünebilir olmasını sağlar.

Dize (String) Doğrulaması

Dizeler uzunluk veya içeriğe göre doğrulanabilir:

  • minLength ve maxLength: Dizenin uzunluğunu kontrol eder.
  • pattern: Dize formatını doğrulamak için bir Düzenli İfade (Regex) kullanın (örneğin belirli bir kimlik önekini kontrol etmek).
  • format: email, date-time, ipv4 ve hostname gibi yaygın formatlar için yerleşik doğrulama sağlar.

Dizi (Array) Doğrulaması

Diziler boyut ve içerik benzersizliği açısından doğrulanabilir:

  • minItems ve maxItems: Eleman sayısını kontrol eder.
  • uniqueItems: true olarak ayarlanırsa, dizideki her eleman benzersiz olmalıdır.
  • items: Dizideki her elemanın uyması gereken bir şema tanımlar.

Karmaşık Şemaları Yapılandırma

Verileriniz büyüdükçe şemalarınız karmaşıklaşacaktır. JSON Şema, yeniden kullanılabilirlik ve organizasyon için mekanizmalar sağlar.

Tanımlamalar ve Referanslar ($ref)

Aynı şema mantığını (birden fazla yerde kullanılan bir "kullanıcı nesnesi" gibi) tekrarlamak yerine, bunu bir definitions (veya $defs) bölümünde bir kez tanımlayabilir ve $ref anahtar kelimesini kullanarak ona referans verebilirsiniz.

{
  "$defs": {
    "address": {
      "type": "object",
      "properties": {
        "street": { "type": "string" },
        "city": { "type": "string" }
      }
    }
  },
  "type": "object",
  "properties": {
    "billing_address": { "$ref": "#/$defs/address" },
    "shipping_address": { "$ref": "#/$defs/address" }
  }
}

Koşullu Mantık

Mantıksal operatörleri kullanarak şemaları birleştirebilirsiniz:

  • allOf: Veriler sağlanan TÜM şemalara göre geçerli olmalıdır.
  • anyOf: Veriler şemalardan EN AZ BİRİNE göre geçerli olmalıdır.
  • oneOf: Veriler şemalardan TAM OLARAK BİRİNE göre geçerli olmalıdır.
  • not: Veriler sağlanan şemaya göre geçerli OLMAMALIDIR.

Pratik Kullanım Durumları

JSON Şema sadece teorik bir kavram değildir; muazzam pratik uygulamaları vardır:

1. API İstek ve Yanıt Doğrulaması

REST veya GraphQL API'leriniz için şemalar tanımlayarak, hatalı biçimlendirilmiş istekleri iş mantığınıza ulaşmadan otomatik olarak reddedebilirsiniz. Bu, kalıplaşmış kod miktarını azaltır ve beklenmedik veri türleri yoluyla enjeksiyon saldırılarını önleyerek güvenliği artırır.

2. Yapılandırma Dosyaları

Uygulamanız yapılandırma için JSON kullanıyorsa, bir şema kullanıcılara yazım hatası yaptıklarında veya geçersiz bir değer sağladıklarında anında geri bildirim sağlayabilir; bu genellikle doğrudan VS Code gibi IDE'lere entegre edilir.

3. Veri Migrasyonu ve Bütünlüğü

Sistemler arasında veri taşırken, dışa veya içe aktarılan verilerin hedef sistemin gereksinimlerini karşıladığından emin olmak için JSON Şema kullanabilirsiniz.

Örnekler: Geçerli vs. Geçersiz JSON

Basit bir ürün girişi için bir şemaya bakalım:

{
  "type": "object",
  "properties": {
    "id": { "type": "integer" },
    "name": { "type": "string", "minLength": 3 },
    "tags": { "type": "array", "uniqueItems": true }
  },
  "required": ["id", "name"]
}

Geçerli JSON:

{
  "id": 101,
  "name": "Kablosuz Fare",
  "tags": ["elektronik", "çevre birimleri"]
}

Geçersiz JSON (Zorunlu 'id' eksik):

{
  "name": "Klavye"
}

Geçersiz JSON (İsim çok kısa):

{
  "id": 102,
  "name": "AB"
}

İlgili Araçlar ve Kaynaklar

JSON ile çalışmayı daha da kolaylaştırmak için şu yararlı araçlara göz atın:

  • JSON'dan TypeScript'e Dönüştürücü: JSON verilerinizden veya şemalarınızdan otomatik olarak TypeScript arayüzleri oluşturarak kodunuzda tip güvenliği sağlayın.
  • JSON Güzelleştirici ve Formatlayıcı: JSON belgelerinizi okunmasını ve hata ayıklanmasını kolaylaştırmak için hızlıca formatlayın ve temizleyin.

Sonuç olarak JSON Şema, modern web teknolojileriyle çalışan her geliştirici için vazgeçilmez bir araçtır. Verilerinizin tam olarak beklediğiniz gibi olmasını sağlamak için standart bir yol sunarak hataları azaltır ve yazılım mimarinizin genel kalitesini artırır.