JSON Schema Doğrulama Kılavuzu: Veri Yapılarınızı Doğrulayın

Dış kaynaklardan veri alan her uygulama aynı temel sorunla karşı karşıyadır: Bu verilere güvenebilir miyim? API istek gövdesi, yapılandırma dosyası, kuyruk mesajı veya veri içe aktarma olsun, güvenilmeyen veriler sisteme girmeden önce doğrulanmalıdır. JSON Schema, geçerli verilerin nasıl göründüğünü tanımlamanın ve gelen verilerin bu tanıma uygun olup olmadığını doğrulamanın standartlaştırılmış, dilden bağımsız bir yolunu sağlar. Bu kılavuz, ilk Schema'nızı yazmaktan karmaşık doğrulama için gelişmiş desenlere kadar her şeyi ve hemen uygulayabileceğiniz pratik örnekleri kapsar.

JSON Schema Nedir?

JSON Schema, diğer JSON belgelerinin yapısını ve kısıtlamalarını tanımlayan bir JSON belgesidir. Internet Engineering Task Force (IETF) tarafından standartlaştırılmış, JSON verilerini açıklamanıza ve doğrulamanıza olanak tanıyan bir kelime dağarcığıdır. JSON Schema, hangi alanların bulunması gerektiği, hangi türde olmaları gerektiği, hangi değerlerin kabul edilebilir olduğu ve nesneler ile dizilerin nasıl yapılandırılması gerektiği hakkında kurallar tanımlar.

JSON Schema'yı veri sözleşmeniz olarak düşünün. Veritabanı şemasının tabloların sütunlarını, türlerini ve kısıtlamalarını tanımladığı gibi, JSON Schema da JSON belgelerinin özelliklerini, türlerini ve kısıtlamalarını tanımlar. Schema'daki tüm kısıtlamaları karşılayan JSON verilerine geçerli örnek denir, herhangi bir kısıtlamayı ihlal eden veriler ise geçersizdir.

JSON Schema Ne Değildir

• Veri formatı değildir: JSON Schema, verilerin nasıl serileştirileceğini veya aktarılacağını tanımlamaz. Yalnızca geçerli verilerin nasıl göründüğünü açıklar.
• İş mantığının yerine geçmez: Schema doğrulaması yapısal doğruluğu kontrol eder (tür, format, aralık). "Kullanıcı bakiyesinden fazla transfer yapamaz" gibi karmaşık iş kuralları uygulama koduna aittir.
• Veritabanı şeması değildir: Kavramsal olarak benzer olsa da, JSON Schema veritabanı tablolarını değil JSON belgelerini doğrular. Ancak, savunma derinliği için JSON Schema'yı veritabanı kısıtlamalarıyla birlikte kullanabilirsiniz.

JSON Schema Sürümleri

JSON Schema, her biri özellikler ekleyen ve kelime dağarcığını geliştiren birden çok taslak üzerinden evrimleşmiştir. Bu sürümleri anlamak, projeniz için doğru olanı seçmenize ve uyumluluk sorunlarından kaçınmanıza yardımcı olur.

İlk Schema'nızı Yazma

Basit bir örnekle başlayalım: ad, e-posta ve yaş içeren bir kullanıcı nesnesi için Schema.

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://example.com/schemas/user.json",
    "title": "User",
    "description": "A user account in the system",
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "The user's full name"
        },
        "email": {
            "type": "string",
            "format": "email",
            "description": "The user's email address"
        },
        "age": {
            "type": "integer",
            "minimum": 0,
            "maximum": 150,
            "description": "The user's age in years"
        }
    },
    "required": ["name", "email"],
    "additionalProperties": false
}

Bu Schema, geçerli bir kullanıcının, name ve email'in zorunlu dize özellikleri olduğu bir nesne olması gerektiğini belirtir. age özelliği isteğe bağlıdır ancak varsa 0 ile 150 arasında bir tamsayı olmalıdır. additionalProperties: false kısıtlaması, Schema'da tanımlanmayan özellikleri engeller, bu da yazım hatalarını ve beklenmeyen alanları yakalar.

Temel Anahtar Kelime Referansı

JSON Schema, kısıtlamaları tanımlamak için zengin bir anahtar kelime dağarcığı sağlar. İşte kategoriye göre düzenlenmiş en önemli anahtar kelimeler.

Tür Anahtar Kelimeleri

Sayı Kısıtlamaları

Dize Kısıtlamaları

Nesne Kısıtlamaları

Dizi Kısıtlamaları

Yaygın Schema Desenleri

Gerçek dünya Schema'ları genellikle basit tür kontrolünün ötesine geçen desenler gerektirir. İşte en sık kullanılan desenler.

if/then/else ile Koşullu Doğrulama

Özellik değerlerine göre farklı kısıtlamalar uygulamak için koşullu mantık kullanın. Örneğin, ödeme nesneleri ödeme yöntemine göre farklı alanlar gerektirir.

{
    "type": "object",
    "properties": {
        "method": { "enum": ["credit_card", "bank_transfer"] },
        "card_number": { "type": "string" },
        "routing_number": { "type": "string" }
    },
    "required": ["method"],
    "if": {
        "properties": { "method": { "const": "credit_card" } }
    },
    "then": {
        "required": ["card_number"]
    },
    "else": {
        "required": ["routing_number"]
    }
}

allOf, anyOf, oneOf ile Birleştirme

Birleştirme anahtar kelimeleri, Schema'ları güçlü şekillerde birleştirmenize olanak tanır:

• allOf: Veri tüm alt Schema'ları karşılamalıdır. Birden çok kısıtlamayı birleştirmek veya yeniden kullanılabilir Schema parçalarını karıştırmak için kullanılır.
• anyOf: Veri en az bir alt Schema'yı karşılamalıdır. Birden çok şeklin kabul edilebilir olduğu birleşim türleri için kullanılır.
• oneOf: Veri tam olarak bir alt Schema'yı karşılamalıdır. Birbirini dışlayan alternatifler için kullanılır.

{
    "oneOf": [
        {
            "type": "object",
            "properties": {
                "type": { "const": "email" },
                "address": { "type": "string", "format": "email" }
            },
            "required": ["type", "address"]
        },
        {
            "type": "object",
            "properties": {
                "type": { "const": "phone" },
                "number": { "type": "string", "pattern": "^\\+?[1-9]\\d{1,14}$" }
            },
            "required": ["type", "number"]
        }
    ]
}

$ref ile Schema Yeniden Kullanımı

$ref anahtar kelimesi, Schema'ları referans almanıza ve yeniden kullanmanıza olanak tanır, tekrarı ortadan kaldırır ve Schema'ları bakımı yapılabilir tutar. Aynı belge içindeki veya harici dosyalardaki Schema'lara referans verebilirsiniz.

{
    "$id": "https://example.com/schemas/order.json",
    "type": "object",
    "properties": {
        "customer": { "$ref": "#/$defs/address" },
        "shipping": { "$ref": "#/$defs/address" },
        "billing": { "$ref": "#/$defs/address" },
        "items": {
            "type": "array",
            "items": { "$ref": "#/$defs/lineItem" },
            "minItems": 1
        }
    },
    "required": ["customer", "items"],
    "$defs": {
        "address": {
            "type": "object",
            "properties": {
                "street": { "type": "string" },
                "city": { "type": "string" },
                "zip": { "type": "string", "pattern": "^\\d{5}(-\\d{4})?$" },
                "country": { "type": "string", "minLength": 2, "maxLength": 2 }
            },
            "required": ["street", "city", "zip", "country"]
        },
        "lineItem": {
            "type": "object",
            "properties": {
                "product": { "type": "string" },
                "quantity": { "type": "integer", "minimum": 1 },
                "price": { "type": "number", "exclusiveMinimum": 0 }
            },
            "required": ["product", "quantity", "price"]
        }
    }
}

Nullable Türler

JSON Schema Draft 2020-12'de, nullable türler "null" içeren bir tür dizisi kullanılarak temsil edilir:

{
    "type": ["string", "null"],
    "description": "An optional display name, or null if not set"
}

Daha eski taslaklarda, OpenAPI spesifikasyonu nullable: true anahtar kelimesini kullanıyordu. Standart JSON Schema için her zaman tür dizisi yaklaşımını kullanın.

Format Doğrulaması

format anahtar kelimesi, yapısal kontrolün ötesinde anlamsal doğrulama sağlar. Bir dizenin iyi bilinen bir formata uyması gerektiğini belirtir. Yaygın olarak desteklenen formatlar şunları içerir:

Programatik Olarak JSON Verilerini Doğrulama

Schema doğrulaması, uygulama koduna entegre edildiğinde en kullanışlıdır. İşte farklı dillerdeki popüler kütüphaneleri kullanan örnekler.

Ajv ile JavaScript

Ajv, JavaScript'te en yaygın kullanılan JSON Schema doğrulayıcısıdır. Tüm taslak sürümlerini destekler ve Schema'ların JIT derlemesiyle mükemmel performans sunar.

import Ajv from 'ajv';
import addFormats from 'ajv-formats';

const ajv = new Ajv();
addFormats(ajv);

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

const validate = ajv.compile(schema);
const valid = validate({ name: 'Alice', email: 'alice@example.com', age: 30 });

if (!valid) {
    console.log(validate.errors);
    // [{ keyword: 'required', params: { missingProperty: 'email' }, ... }]
}

jsonschema ile Python

from jsonschema import validate, ValidationError

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string", "minLength": 1},
        "email": {"type": "string", "format": "email"},
        "age": {"type": "integer", "minimum": 0}
    },
    "required": ["name", "email"],
    "additionalProperties": False
}

try:
    validate(instance={"name": "Alice", "email": "alice@example.com"}, schema=schema)
except ValidationError as e:
    print(f"Validation failed: {e.message}")

API Veri Doğrulaması için JSON Schema

JSON Schema'nın en değerli uygulamalarından biri, API istek ve yanıt verilerini doğrulamaktır. Bu, API'nizin iyi biçimlendirilmiş girdi almasını ve verileri beklenen formatta döndürmesini sağlar, hataları erken yakalar ve istemcilere net hata mesajları sağlar.

Express.js Middleware

import Ajv from 'ajv';

const ajv = new Ajv({ allErrors: true });

function validateBody(schema) {
    const validate = ajv.compile(schema);
    return (req, res, next) => {
        if (!validate(req.body)) {
            return res.status(400).json({
                error: 'Validation failed',
                details: validate.errors
            });
        }
        next();
    };
}

app.post('/api/users',
    validateBody({
        type: 'object',
        properties: {
            name: { type: 'string', minLength: 1, maxLength: 100 },
            email: { type: 'string', format: 'email' },
            role: { enum: ['admin', 'editor', 'viewer'] }
        },
        required: ['name', 'email'],
        additionalProperties: false
    }),
    (req, res) => {
        // req.body is guaranteed valid here
        createUser(req.body);
    }
);

OpenAPI ve JSON Schema

OpenAPI (eski adıyla Swagger), API istek ve yanıt Schema'larını tanımlamak için JSON Schema'nın bir alt kümesini kullanır. Zaten OpenAPI kullanıyorsanız, API spesifikasyonunuzdan Schema'ları çıkarabilir ve çalışma zamanı doğrulaması için kullanabilirsiniz. openapi-schema-validator ve express-openapi-validator gibi araçlar bu süreci otomatikleştirerek API belgelerinizin ve doğrulama mantığınızın her zaman senkronize kalmasını sağlar.

En İyi Uygulamalar

• Her zaman $schema ayarlayın: Schema'nızın hangi taslak sürümünü kullandığını belirtmek için $schema anahtar kelimesini ekleyin. Bu belirsizliği önler ve doğrulayıcının Schema'nızı doğru yorumlamasını sağlar.
• Schema tanımlayıcı olarak $id kullanın: $id anahtar kelimesi, Schema'nız için benzersiz bir tanımlayıcı sağlar ve $ref referanslarını çözmek için temel URI olarak hizmet eder. Yerel Schema'lar için bile her zaman ayarlayın.
• additionalProperties: false ayarlayın: Varsayılan olarak JSON Schema, nesnelerde herhangi bir ek özelliğe izin verir. additionalProperties: false ayarlamak yazım hatalarını ve beklenmeyen alanları yakalar, Schema'nızı daha katı ve API'nizi daha öngörülebilir hale getirir.
• Yeniden kullanılabilir bileşenler için $defs kullanın: Ortak Schema'ları $defs içinde tanımlayın ve $ref ile referans verin. Bu tekrarı azaltır ve Schema'ların bakımını kolaylaştırır.
• Açıklama ekleyin: Her özellik ve Schema'nın description alanı olmalıdır. Bu hem belgeleme görevi görür hem de diğer geliştiricilerin her alanın amacını ve kısıtlamalarını anlamasına yardımcı olur.
• Sistem sınırlarında doğrulayın: Schema doğrulamasını sistemin kenarlarında uygulayın: API uç noktaları, mesaj tüketicileri, veri içe aktarma ardışık düzenleri ve yapılandırma yükleyicileri. Kendi kodunuzun zaten ürettiği ve güvendiğiniz verileri doğrulamayın.
• Doğrulayıcıda katı modu etkinleştirin: Doğrulayıcıyı bilinmeyen anahtar kelimeleri reddedecek, format doğrulamasını zorunlu kılacak ve ilk hatada durmak yerine tüm hataları raporlayacak şekilde yapılandırın. Bu, tek bir doğrulamada daha fazla sorunu yakalar.
• Schema'ları sürümlendirin: $id URI'sine Schema sürümünü ekleyin (ör. https://example.com/schemas/user/v2.json). Bu, mevcut tüketicileri bozmadan Schema'ları evrimleştirmenize olanak tanır.
• Schema'nızı test edin: Schema'nız için geçerli ve geçersiz örnekler içeren birim testleri yazın. Bu, Schema'nızın amaçladığınız kısıtlamaları uyguladığından emin olmanızı ve Schema değişikliklerinde gerilemeleri yakalamanızı sağlar.
• Anlamsal doğrulama için format kullanın: Karmaşık regex desenleri yerine format: "email" kullanmayı tercih edin. Formatlar daha okunabilir, daha bakımı kolaydır ve doğrulayıcı kütüphanelerdeki iyi test edilmiş doğrulama mantığından yararlanır.