JSON’ın Tanımı: JSON Schema

Herkese selamlar, bu yazımda JSON veri formatı için bir şema görevi gören JSON Schema kavramından bahsedeceğim.

JSON Schema , kullanmakta olduğunuz için JSON dokümanları içerisinde bulunan “key-value” çiftlerinin neler olduğunu, bu çifte uygulanmış bir veri kısıtının olup olmadığını belirtmek amacıyla kullanılır. JSON Schema ile kullanmakta olduğunuz JSON dokümanı içerisinde yer alan veri çiftlerine açıklamalarda ekleyebilirsiniz. JSON Schema bir nevi kullanmakta olduğunuz JSON dokümanının meta-data’ sıdır.

Aşağıdaki github-gist’inde yer almakta olan JSON verisi bizim JSON Schema’sını inceleyeceğimiz ve oluşturacağımız dokümana aittir.

Bu JSON dokümanı içerisinde yer alan “key-value” çiftleri bir arabaya aittir. Car objesinin içerisinde de “carId”, “brand”, “model”, “dailyPrice”, “color”, “description” gibi key’ler bulunmaktadır.

Bu dokümana ait JSON Schema’ yı oluşturmak istediğimizde ise ilk olarak aşağıdaki bölümde yer almakta olan tanımlamaları yapmamız gereklidir.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://apinizer.com/cars.schema.json",
  "title": "Cars",
  "description": "Bu JSON dokümanı bir rentACar firmasına aittir.",
  "type": "object"
}

$schema, oluşturulan JSON şemasının belirli bir standarda uygun olarak oluşturulduğunu ifade etmektedir.

$id, JSON şeması için ve bu json şeması içerisinde yer almakta olan URL’ler için temel bir URL adresi belirtir.

$schema ve $id ifadeleri JSON schema’larında anahtar kelimeler olarak gruplanmaktadır.

“title” oluşturulan JSON schema dokümanı için bir başlık görevi görür, “description” ifadesi ise JSON schema dokümanlarına açıklama eklemek için kullanılır.

Bu kavramlar anlamı arttıran kavramlardır ve JSON schema dokümanı içerisinde yer alan ifadeleri etkilememektedir.

“type” ifadesi ise JSON dokümanımız için ilk kısıtlamanın gerçekleştirildiği yerdir. Aldığı ifade “object” değeridir çünkü doküman içerisinde tanımı yapılacak olan her şey birer objedir.

Şimdi yukarıda oluşturmaya başladığımız schema’mıza kaldığımız yerden devam edelim.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://apinizer.com/cars.schema.json",
  "title": "Cars",
  "description": "Bu JSON dokümanı bir rentACar firmasına aittir.",
  "type": "object", 
  "properties": {
    "carId": {
      "description": "carId bir araba için eşsiz ve benzersizdir",
      "type": "number"
    }
  },
  "required": [ "carId" ]
}

JSON dokümanımız içerisinde yer alacak olan “key/value” çiftlerini tanımlamak için “properties” anahtar kelimesi kullanılmaktadır. Schema’sını hazırladığımız JSON dokümanı içerisinde yer alan “carId” key ifadesi bir arabanın kaydını oluştururken verilir ve diğer arabaların birbirlerinden ayırt edilmesi için kullanılır. Burada “description” ifadesi ile kullanılan key’e ait açıklama yapılır, “type” ise “carId” isimli key’in alacağı değerlerin “number” olabileceğine dair bir kısıtlama ve tanım getirir, “required” ifadesi ise JSON dokümanı içerisinde yer alan key’lerin kullanılmasının zorunlu olduğunu belirtir.

Kullanımı zorunlu olan alanlar isteğe göre ve kullanıma göre daha da çoğaltılabilir. Buna ait örnek gösterimde aşağıda yer almaktadır.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://apinizer.com/cars.schema.json",
  "title": "Cars",
  "description": "Bu JSON dokümanı bir rentACar firmasına aittir.",
  "type": "object", 
  "properties": {
    "carId": {
      "description": "carId bir araba için eşsiz ve benzersizdir",
      "type": "number"
    },
    "brand": {
      "description": "Araba kaydı oluştururken marka boş geçilemez",
      "type": "string"
    }
  },
"required": [ "carId","brand" ]
}

Burada “carId” key ifadesinden sonra bir virgül koyarak başka bir key ifadesi olan “brand” ifadesi eklenmiştir ve bu alanda “required” array’i içerisinde belirtilmiştir.

JSON Schema kullanımının mantığını biraz kavradıysak eğer JSON Schema’mızı daha özel bir hâle getirelim.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://apinizer.com/cars.schema.json",
  "title": "Cars",
  "description": "Bu JSON dokümanı bir rentACar firmasına aittir.",
  "type": "object", 
  "properties": {
    "carId": {
      "description": "carId bir araba için eşsiz ve benzersizdir",
      "type": "number"
    },
    "brand": {
      "description": "Araba kaydı oluştururken marka boş geçilemez",
      "type": "string"
    },
    "dailyPrice": {
      "description": "Arabalara ait olan fiyat bilgisidir",
      "type": "number",
      "exclusiveMinimum": 0
    }
   },  
  "required": [ "carId","brand","dailyPrice" ]
}

Yukarıda da görüldüğü üzere JSON Schema’mızın içerisinde bir de “dailyPrice” isminde bir key’in daha tanımı gerçekleştirdik. Burada dikkat edilmesi gereken nokta ise “exclusiveMinimum” ifadesidir. Bu ifade ile de “dailyPrice” isimli key’in alabileceği değerlerin sıfırdan büyük olması gerektiği belirtilir.

Şimdi ise sırada bir JSON Scheması içerisinde array tanımı nasıl gerçekleştirilir bunu inceleyelim.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://apinizer.com/cars.schema.json",
  "title": "Cars",
  "description": "Bu JSON dokümanı bir rentACar firmasına aittir.",
  "type": "object", 
  "properties": {
    "carId": {
      "description": "carId bir araba için eşsiz ve benzersizdir",
      "type": "number"
    },
    "brand": {
      "description": "Araba kaydı oluştururken marka boş geçilemez",
      "type": "string"
    },
    "dailyPrice": {
      "description": "Arabalara ait olan fiyat bilgisidir",
      "type": "number",
      "exclusiveMinimum": 0
    },
    "color": {
      "description": "Arabalara ait renk bilgisidir",
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "uniqueItems": true
    }
   },  
  "required": [ "carId","brand","dailyPrice" ]
}

Cars.json isimli dokümanımızda yer alan bir diğer key’imiz ise “color” ifadesidir. Bu ifade array tipinde olup içerisinde de string veri türünde değerler tutmaktadır. Burada array içerisinde yer alan değerlerin string türünde olduğunu “items” anahtar kelimesiyle tanımı gerçekleştirilmiştir. Burada dikkat edilmesi gereken iki anahtar kelime daha vardır, bunlar “minItems” ve “uniqueItems” ifadeleridir.

“minItems”:1 ifadesi ile oluşturulacak olan array’in en az bir tane değer alması gerektiği belirtilir.

“uniqueItems”:true ifadesi ise oluşturulacak olan array’in içerisindeki değerlerin birbirlerinden farklı olması gerektiğini belirtir.

JSON Schema tanımı yaparken kullanılan anahtar kelimeler ve kısıtlamalar sadece bunlardan ibaret değildir. Daha fazla anahtar kelime ve kısıtlamaları incelemek için buradaki linke tıklayabilirsiniz.

Apinizer’da JSON Schema

Apinizer’da REST mimari de hazırlanmış olan API’lerinizi yönetebilir ve güvenliklerini sağlayabilirsiniz. Güvenlik kısmında ise API’lerinize poliçeler ekleyebilirsiniz. Bu poliçelerden biri olan “JSON Schema Validation” poliçesi ile gelen mesajın içeriği belirlenen JSON Schema’sına uygun değilse backend API’ye erişimine izin verilmez.

Apinizer ile daha güvenli ve daha hızlı bir şekilde veri iletişimini sağlayabilirsiniz. Apinizer hakkında daha çok bilgi etmek isterseniz buradaki linke tıklayabilirsiniz. Ürün demomuza erişim sağlamak için ise buradaki linke tıklayabilirsiniz.

JSON ile alakalı yazımı okumadıysanız buradaki linkten okuyabilirsiniz. Serimin üçüncü yazısı “JSON Path” konusu ile devam edecektir. Bir sonraki yazımda buluşmak dileğiyle.