JSON Schema Doğrulayıcı

JSON Schema Doğrulama Nedir?

JSON Schema doğrulama, bir JSON belgesinin, JSON Schema içinde tanımlanmış yapısal ve değer kısıtlamalarına uyup uymadığını kontrol etme işlemidir. Şemanın kendisi de bir JSON belgesidir ve verilerinizin beklenen biçimini tanımlar: hangi özelliklerin zorunlu olduğunu, hangi tipleri alması gerektiğini, sayılar için izin verilen aralıkları, dize desenlerini, dizi uzunluklarını ve daha fazlasını. JSON Schema spesifikasyonu json-schema.org'da yönetilmekte ve bir dizi IETF taslağı olarak yayımlanmaktadır; Draft 7 ve Draft 2020-12 en yaygın benimsenenlerdir.

Sıradan JSON doğrulama yalnızca sözdizimini kontrol eder (parantezler kapalı mı? dizeler tırnak içinde mi?), oysa şema doğrulaması daha ileri gider. Şu soruları yanıtlar: Bu API'nin yanıtı her zaman tam sayı olan bir "id" alanı içeriyor mu? "status" alanı izin verilen üç değerden biri mi? İç içe nesneler doğru biçimde şekillendirilmiş mi? Bu tür yapısal doğrulama, sözdizim kontrollerinin tamamen kaçırdığı hataları yakalar; çünkü sözdizimsel olarak geçerli JSON, uygulamanız için anlamsal olarak yanlış olabilir.

JSON Schema; OpenAPI/Swagger tanımlarında, yapılandırma dosyası doğrulamasında, form doğrulamasında, veritabanı belge kısıtlamalarında ve otomatik testlerde kullanılır. Ajv (JavaScript), jsonschema (Python) ve check-jsonschema (CLI) gibi araçlar, spesifikasyonu uygulayarak veriyi programatik olarak doğrulamanızı sağlar. Bu online doğrulayıcı, herhangi bir kütüphane kurmadan hem şemayı hem de veri belgesini yapıştırarak uyumu anında kontrol etmenizi sağlar.

Neden Online JSON Schema Doğrulayıcı Kullanılmalı?

Şema yazmak ve doğrulama hatalarını elle ayıklamak yavaştır. Online bir JSON Schema doğrulayıcı, verilerinizin şemanızla eşleşip eşleşmediği konusunda anında geri bildirim sağlar; hatanın tam olarak nerede meydana geldiğini gösteren net hata mesajlarıyla.

JSON Schema Doğrulama Kullanım Durumları

JSON Schema Anahtar Kelime Referansı

Bir JSON Schema, her biri doğrulanan veri üzerinde bir kısıtlama uygulayan anahtar kelimelerden oluşur. Aşağıdaki tablo, Draft 7 ve sonrasında en yaygın kullanılan anahtar kelimeleri listeler. Her anahtar kelime, aynı şema nesnesindeki diğerleriyle birleştirilebilir.

JSON Schema Taslak Karşılaştırması: Draft 7 vs 2019-09 vs 2020-12

JSON Schema birçok taslak sürümden geçmiştir. Draft 7 (2018'de yayımlandı), araç desteği açısından en yaygın benimsenendir. Draft 2019-09, $defs'i ($definitions yerine), unevaluatedProperties'i ve $recursiveRef'i tanıttı. Draft 2020-12 (en son kararlı sürüm), $recursiveRef'i $dynamicRef ile değiştirdi ve tuple doğrulaması için prefixItems'ı tanıttı. Taslak seçerken, doğrulama kütüphanenizin onu desteklediğini doğrulayın. Ajv üç taslağı da destekler. Python'un jsonschema kütüphanesi, sürüm 4.0'dan itibaren 2020-12'ye kadar destekler.

Kod Örnekleri

Aşağıdaki örnekler, JSON'un bir şemaya karşı programatik olarak nasıl doğrulanacağını göstermektedir. Her biri kendi dil ekosistemi için iyi bakımlı bir kütüphane kullanır.

import Ajv from 'ajv';

const ajv = new Ajv();

const schema = {
  type: 'object',
  properties: {
    name: { type: 'string', minLength: 1 },
    age: { type: 'integer', minimum: 0 },
    email: { type: 'string', format: 'email' }
  },
  required: ['name', 'email'],
  additionalProperties: false
};

const data = { name: 'Alice', age: 30, email: 'alice@example.com' };

const validate = ajv.compile(schema);
const valid = validate(data);
console.log(valid);          // → true
console.log(validate.errors); // → null

// Invalid data — missing required "email"
validate({ name: 'Bob', age: 25 });
console.log(validate.errors);
// → [{ instancePath: '', keyword: 'required', params: { missingProperty: 'email' } }]

from jsonschema import validate, ValidationError

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string", "minLength": 1},
        "age": {"type": "integer", "minimum": 0},
        "tags": {
            "type": "array",
            "items": {"type": "string"},
            "uniqueItems": True
        }
    },
    "required": ["name"]
}

# Valid data
validate(instance={"name": "Alice", "age": 30, "tags": ["admin"]}, schema=schema)
# → No exception raised

# Invalid data — wrong type for "age"
try:
    validate(instance={"name": "Alice", "age": "thirty"}, schema=schema)
except ValidationError as e:
    print(e.message)
    # → 'thirty' is not of type 'integer'
    print(e.json_path)
    # → $.age

package main

import (
    "fmt"
    "strings"
    "github.com/santhosh-tekuri/jsonschema/v5"
)

func main() {
    schemaJSON := `{
        "type": "object",
        "properties": {
            "id": { "type": "integer" },
            "status": { "enum": ["active", "inactive"] }
        },
        "required": ["id", "status"]
    }`

    compiler := jsonschema.NewCompiler()
    compiler.AddResource("schema.json", strings.NewReader(schemaJSON))
    schema, _ := compiler.Compile("schema.json")

    // Valid data
    data := map[string]interface{}{"id": 1, "status": "active"}
    err := schema.Validate(data)
    fmt.Println(err) // → <nil>

    // Invalid — missing "status"
    bad := map[string]interface{}{"id": 2}
    err = schema.Validate(bad)
    fmt.Println(err) // → validation failed: missing properties: 'status'
}

# Install via pip
pip install check-jsonschema

# Validate a file against a schema
check-jsonschema --schemafile schema.json data.json
# → ok -- validation done

# Validate against a remote schema (e.g., GitHub Actions workflow)
check-jsonschema --builtin-schema vendor.github-workflows my-workflow.yml

# Validate multiple files at once
check-jsonschema --schemafile schema.json file1.json file2.json file3.json

Sıkça Sorulan Sorular