JSON Schema doğrulama: Node, Python ve tarayıcıda JSON’u doğrulayın (2026)
JSON Schema, JSON verileri için bir sözleşmedir. Alan tiplerini, zorunlu anahtarları ve kısıtlamaları beyan edersiniz; bir doğrulayıcı da herhangi bir JSON belgesinin bu sözleşmeye uyup uymadığını denetler. Node’da en hızlı doğrulama için Ajv’yi, taşınabilir şemalar için Python’da jsonschema kütüphanesini, hızlı form ve yapılandırma geri bildirimi için tarayıcıda paketlenmiş Ajv’yi kullanın. 2026’da yeni projeler için tercih edilecek sürüm Draft 2020-12’dir.
Aşağıda en küçük çalışan örneği, üç çalışma zamanında uçtan uca kalıpları ve “doğrulama geçiyor ama üretim veriyi reddediyor” hatalarına yol açan gerçek dünya tuzaklarını bulacaksınız.
JSON Schema nedir (ve ne değildir)
Tek cümlelik tanım
Bir JSON Schema, başka JSON belgelerinin biçimini tanımlayan bir JSON belgesidir. Bir doğrulayıcı, şemayı ve veriyi okur; ardından uyumluluğu onaylar veya başarısız olan yolları döner.
En küçük yararlı örnek:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": { "name": { "type": "string" } },
"required": ["name"]
}{"name": "Alice"} geçer. {"age": 30} başarısız olur (name eksik). {"name": 42} başarısız olur (name bir karakter dizisi değil). Zihinsel modelin tamamı bu kadar.
JSON Schema ile JSON söz dizimi doğrulaması
İki farklı problem, sıkça karıştırılır.
| Boyut | JSON söz dizimi denetimi | JSON Schema doğrulaması |
|---|---|---|
| Neyi denetler | Bu, geçerli bir JSON belgesi mi? | Bu JSON sözleşmeye uyuyor mu? |
| Yakaladığı | Eksik virgüller, tek tırnaklar, yorumlar | Yanlış tipler, eksik zorunlu alanlar, aralık dışı değerler |
| Araçlar | JSON.parse(), JSON Biçimlendirici | Ajv, jsonschema (Python), fastjsonschema |
| Ne zaman başvurulur | İlk iş, ayrıştırmadan önce | Ayrıştırmadan hemen sonra, iş mantığından önce |
Pratikte ikisini de yaparsınız: payload’u JSON Biçimlendirici ile düzgünce yazdırarak ayrıştığını doğrularsınız, ardından sözleşmeye uyduğunu onaylamak için bir şemadan geçirirsiniz.
JSON Schema ile JSONPath, JSON Patch, jq ve TypeScript
Bu problem alanını beş araç paylaşır. İşte karar matrisi:
| Araç | Yanıtladığı soru | Ne zaman başvurulur |
|---|---|---|
| JSON Schema | Bu JSON beklenen yapıya uyuyor mu? | API girdisi, yapılandırma dosyaları, form payload’ları doğrularken |
| JSONPath | Bu JSON’dan bir değeri nasıl sorgularım? | İç içe alanları çıkarırken, toplu okumalarda |
| JSON Patch (RFC 6902) | A’dan B’ye farkı nasıl tanımlarım? | Eş zamanlı düzenleme, artımlı eşitleme |
| jq | JSON’u komut satırında nasıl işlerim? | Kabuk betikleri, log boru hatları, CI denetimleri |
| TypeScript tipleri | Kodum bu biçimi doğru kullanıyor mu? | Tek bir kod tabanı içinde derleme zamanı garantileri |
Temel ayrım şudur: JSON Schema çalışma zamanında bilinmeyen veriyi doğrular, TypeScript ise derleme zamanında bilinen kodu doğrular. TypeScript, üçüncü taraf bir webhook’tan veya bir kullanıcı yapıştırmasından gelen JSON için yardım edemez; JSON Schema tam olarak bunun için vardır. Zod ve Pydantic ikisinin arasında bir yer tutar (derleme zamanı tipler ve çalışma zamanı doğrulama); aşağıda ele alınmıştır.
JSON Schema ile OpenAPI
Yaygın bir yanılgı, OpenAPI’nin JSON Schema’nın yerine geçtiğidir. Geçmez. OpenAPI, istek ve yanıt gövdelerini tanımlamak için dahili olarak JSON Schema kullanır; ardından bunun üzerine yollar, parametreler, güvenlik şemaları ve sunucu URL’leri ekler. Şema, veri biçimi sözleşmesidir; OpenAPI ise onu saran API sözleşmesidir.
| Boyut | JSON Schema | OpenAPI |
|---|---|---|
| Kapsam | Tek bir JSON belgesinin biçimi | Bir HTTP API’sinin tamamının biçimi |
| Bağımlılıklar | Yok (şema kendi kendine yeten JSON’dur) | Gövde tanımları için JSON Schema’yı içe aktarır |
| Sürüm eşleşmesi | Draft 7 / Draft 2019-09 / Draft 2020-12 | OpenAPI 3.0 bir Draft 4 alt kümesini kullanır; OpenAPI 3.1 yerel olarak Draft 2020-12’yi kullanır |
| Tipik kullanım | Yapılandırma dosyaları, mesaj zarfları, form doğrulaması, tek payload sözleşmeleri | REST API tasarımı, SDK üretimi, sahte sunucular, sözleşme testleri |
| Kod üretimi | Sınırlı (bazı quicktype tarzı araçlar) | Olgun ekosistem (openapi-generator, oapi-codegen, satıcı SDK’ları) |
| Sözleşme yönetimi | Biçim başına bir dosya, yönlendirme yok | Tek belgede yollar, işlemler, kimlik doğrulama akışları, sürümlü uç noktalar |
Önemsediğiniz eser tek bir belge olduğunda — bir webhook payload’u, bir yapılandırma dosyası, bir kuyruk mesajı veya bir form — sade JSON Schema’ya başvurun. Tanımlanacak HTTP yüzeyi yoktur, dolayısıyla OpenAPI fazladan yüktür.
Bir HTTP API’si yayımlıyor ve dokümanları, SDK üretimini, sahte sunucuları ve sözleşme testlerini tek bir belgeden yürütmek istiyorsanız OpenAPI’ye başvurun. Şemalarınızı önce bir schemas/ dizini içinde bağımsız JSON Schema dosyaları olarak tanımlayın, ardından OpenAPI belgesinden $ref ile bunlara başvurun. Bu, şemaları API bağlamı dışında da yeniden kullanılabilir tutar.
Sürüm eşleşmesi ekipleri yanıltır. OpenAPI 3.0 bir Draft 4 alt kümesini kullanır; bu nedenle 3.0 belgesi içinde prefixItems veya unevaluatedProperties gibi Draft 2020-12 anahtar kelimelerini kullanamazsınız — üreteçler bunları sessizce yok sayar. OpenAPI 3.1, Draft 2020-12’nin bir üst kümesidir; dolayısıyla 2020-12’de geçerli olan her şey 3.1’de de geçerlidir. Seçme şansınız varsa OpenAPI 3.1’i hedefleyin ve her yerde Draft 2020-12 şemaları yazın.
İlk JSON şemanız (5 dakika)
Önce ihtiyaç duyduğunuz anahtar kelimeler
Bunlarla yolun %80’ini alırsınız:
{
"type": "object",
"properties": {
"id": { "type": "integer", "minimum": 1 },
"email": { "type": "string", "format": "email" },
"age": { "type": "integer", "minimum": 0, "maximum": 150 },
"tags": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
"role": { "enum": ["admin", "editor", "viewer"] },
"metadata": { "type": "object", "additionalProperties": true }
},
"required": ["id", "email"],
"additionalProperties": false
}Söz dağarcığı:
type:string,number,integer,boolean,null,array,objectpropertiesverequired: alanları beyan eder ve hangilerinin var olması gerektiğini işaretlerenumveyaconst: sabit bir kümeyle veya tek bir literal değerle sınırlarminimum,maximum,multipleOf: sayısal sınırlarminLength,maxLength,pattern: karakter dizisi uzunluğu ve düzenli ifademinItems,maxItems,uniqueItems: dizi biçimiadditionalProperties: false: beyan edilmemiş anahtarları reddeder (bunu girdi sözleşmelerinde her zaman ayarlayın)
Kullanım senaryosuna göre JSON Schema örnekleri
Yukarıdaki anahtar kelimeler, neyi doğruladığınıza bağlı olarak farklı bileşimlerde ortaya çıkar. Birkaç temsili biçim:
API istek gövdesi — e-posta ve parola kabul eden bir kayıt uç noktası:
{
"type": "object",
"properties": {
"email": { "type": "string", "format": "email" },
"password": { "type": "string", "minLength": 8, "maxLength": 128 }
},
"required": ["email", "password"],
"additionalProperties": false
}Yapılandırma dosyası — düzeyi sabit bir kümeye kilitleyen bir günlük yapılandırması:
{
"type": "object",
"properties": {
"level": { "enum": ["debug", "info", "warn", "error"] },
"output": { "type": "string", "default": "stdout" }
},
"required": ["level"],
"additionalProperties": false
}Koşullu kurallı form payload’u — accountType "business" olduğunda taxId zorunlu hale gelir:
{
"type": "object",
"properties": {
"accountType": { "enum": ["personal", "business"] },
"taxId": { "type": "string" }
},
"if": { "properties": { "accountType": { "const": "business" } } },
"then": { "required": ["taxId"] }
}CSV satırı JSON kaydı — dışa aktarılan siparişler tablosunun tek satırı:
{
"type": "object",
"properties": {
"orderId": { "type": "string", "pattern": "^ORD-[0-9]{6}$" },
"orderedOn": { "type": "string", "format": "date" },
"totalUsd": { "type": "number", "minimum": 0 }
},
"required": ["orderId", "orderedOn", "totalUsd"]
}Webhook olay zarfı — oneOf, type literal’ine göre ayrım yapar; böylece her olay türevi kendi payload biçimine sahip olur:
{
"oneOf": [
{ "properties": { "type": { "const": "order.created" }, "data": { "$ref": "#/$defs/order" } } },
{ "properties": { "type": { "const": "order.refunded" }, "data": { "$ref": "#/$defs/refund" } } }
]
}Bu beş örnek, ekiplerin pratikte yazdıklarının büyük bölümünü kapsar. En yakın eşleşmeyi kopyalayın ve alan adlarını ayarlayın — anahtar kelime söz dağarcığı aynı kalır.
Hiçbir şey kurmadan doğrulayın
Hızlı bir karar için şemayı ve payload’u ajv.js.org veya jsonschemavalidator.net deneme alanına yapıştırın. JSON’un kendisi şüpheli görünüyorsa önce JSON Biçimlendirici üzerinden geçirin.
Node.js’te Ajv ile doğrulama
Kurulum ve 12 satırlık bir örnek
Ajv, ilk compile çağrısında şemanızı optimize edilmiş bir fonksiyona derler ve sonra onu yeniden kullanır.
npm install ajvimport Ajv from "ajv";
const ajv = new Ajv();
const schema = {
type: "object",
properties: {
name: { type: "string" },
age: { type: "integer", minimum: 0 }
},
required: ["name"]
};
const validate = ajv.compile(schema);
const data = { name: "Alice", age: 30 };
if (!validate(data)) console.log(validate.errors);
else console.log("OK");Draft 2020-12’ye geçiş
Varsayılan Ajv yapıcısı, geriye dönük uyumluluk için hâlâ Draft 7’ye sabitlidir. 2020-12’yi açıkça tercih edin:
import Ajv2020 from "ajv/dist/2020";
const ajv = new Ajv2020({ strict: true, allErrors: true });Artık prefixItems, unevaluatedProperties ve $dynamicRef kullanılabilir. Her birinin ne yaptığı için aşağıdaki Draft 2020-12 bölümüne bakın.
format doğrulamasını açma
Bu, başka herhangi bir Ajv tuhaflığından daha fazla geliştiriciyi yanıltır: format: "email" varsayılan olarak hiçbir şey yapmaz. Şartname format’ı yol gösterici olarak ele aldığı için format modülünü ayrıca kaydetmeniz gerekir:
npm install ajv-formatsimport addFormats from "ajv-formats";
addFormats(ajv); // artık "format": "email" gerçekten doğruluyorBu adım olmadan, format: "email" gerektiren bir şemadan {"email": "not-an-email"} geçer. Üretimde her zaman ajv-formats kurun.
Pratikte Express middleware’i
Önyüklemede derlenmiş, rota başına bir doğrulayıcı:
import express from "express";
import Ajv2020 from "ajv/dist/2020";
import addFormats from "ajv-formats";
const ajv = new Ajv2020({ allErrors: true });
addFormats(ajv);
const validateUser = ajv.compile({
type: "object",
properties: {
email: { type: "string", format: "email" },
age: { type: "integer", minimum: 13 }
},
required: ["email"],
additionalProperties: false
});
const app = express();
app.use(express.json());
app.post("/users", (req, res) => {
if (!validateUser(req.body)) {
return res.status(400).json({ errors: validateUser.errors });
}
// ... iş mantığı
res.status(201).json({ ok: true });
});En pahalıya mal olan tek hata, istek işleyicisinin içinde ajv.compile(schema) çağırmaktır. Modül kapsamında bir kez derleyin, dönen fonksiyonu yeniden kullanın. İstek başına yeniden derleme, verimi 50 kat veya daha fazla düşürür.
Python’da jsonschema ile doğrulama
Kurulum ve temel kullanım
pip install jsonschemafrom jsonschema import validate, ValidationError
schema = {
"type": "object",
"properties": {
"name": {"type": "string"},
"age": {"type": "integer", "minimum": 0}
},
"required": ["name"]
}
try:
validate(instance={"name": "Alice", "age": 30}, schema=schema)
print("OK")
except ValidationError as e:
print("FAIL:", e.message, "at", list(e.absolute_path))Draft202012Validator ile tüm hataları toplama
validate(), ilk hatada istisna fırlatır. Her sorunu aynı anda listelemek için (form yanıtları için yararlıdır) iter_errors’ı kullanın:
from jsonschema import Draft202012Validator
validator = Draft202012Validator(schema)
errors = sorted(validator.iter_errors(instance), key=lambda e: e.path)
for err in errors:
print(f" - {'/'.join(map(str, err.absolute_path))}: {err.message}")Bu sayede kullanıcı, gidip gelen turlar yerine her şeyi tek seferde düzeltir.
jsonschema ve Pydantic: hangisini seçmeli
İki güçlü Python kütüphanesi, iki farklı problem.
| Boyut | jsonschema | Pydantic v2 |
|---|---|---|
| Şema biçimi | Bir JSON sözlüğü (şema veridir) | Tip ipuçlarıyla bir Python sınıfı |
| Performans | Yorumlanmış, Pydantic’ten ~10–100 kat yavaş | Rust çekirdeği, ekosistemdeki en hızlısı |
| Diller arası taşınabilirlik | Evet (aynı şema JS, Go, Rust’ta çalışır) | Hayır (yalnızca Python) |
| FastAPI / yerel model entegrasyonu | El ile dönüşüm | Yerleşik |
Tam Draft 2020-12 anahtar kelimeleri ($dynamicRef vb.) | Eksiksiz | Kısmi |
Üretimde işe yarayan kural şudur: diller arası sözleşmeler için jsonschema kullanın (OpenAPI, herkese açık API’ler, webhook’lar); dahili Python servisleri için ise Pydantic kullanın. Pek çok ekip her ikisini birlikte çalıştırır: ağ geçidinde sözleşme dayatması için jsonschema, uygulama katmanında tipli iş mantığı için Pydantic. Şema taşınabilir eserdir ve Ajv’ye verdiğinizle bire bir aynıdır.
Tarayıcıda doğrulama
İstemci tarafında neden doğrulama yapılır
Üç neden var ve önem sırasıyla şöyle sıralanır:
- UX: kullanıcı yazarken hızlı geri bildirim verir, sunucu turundan daha akıcıdır
- Bant genişliği: bariz hatalar tarayıcıdan hiç çıkmaz
- Güvenlik hijyeni: arka uca gelen gereksiz trafiği azaltır (sunucu doğrulamasının yerine geçmez)
Tek başına istemci tarafı doğrulamasına asla güvenmeyin. Sunucuda da yeniden doğrulayın.
Tarayıcı için Ajv’yi paketleme
npm install ajv ajv-formatsimport Ajv2020 from "ajv/dist/2020";
import addFormats from "ajv-formats";
const ajv = new Ajv2020({ allErrors: true });
addFormats(ajv);
export const validateForm = ajv.compile({
type: "object",
properties: {
email: { type: "string", format: "email" },
password: { type: "string", minLength: 8 }
},
required: ["email", "password"]
});Paket, gzip’li yaklaşık 30 KB ekler. Hissedilir bir maliyet ama kabul edilebilir. Ekipler, sunucu ile istemci arasında tek bir şema tanımı paylaşmak istediklerinde Ajv’yi gönderir.
Hafif alternatifler: Zod ve Valibot
JSON Schema ekosistemine ihtiyacınız yoksa ve zaten TypeScript içindeyseniz, TS-yerel bir doğrulayıcı size daha küçük paketler ve daha sıkı tip çıkarımı sunar:
import { z } from "zod";
const UserSchema = z.object({
email: z.string().email(),
password: z.string().min(8)
});
const result = UserSchema.safeParse(data);
if (!result.success) console.log(result.error.issues);Valibot, benzer bir API ile gzip’li yaklaşık 3 KB’ta gelir. Paket boyutu baskınsa onu seçin. Bir kısıtlama var: hiçbiri JSON Schema üretmez. Arka uçlar, üçüncü taraf istemciler veya OpenAPI üreticileriyle paylaşılan tek bir doğruluk kaynağına ihtiyacınız varsa Ajv’de kalın. Her şey kendi TypeScript kodunuzsa, Zod ve Valibot daha ergonomiktir.
Draft 2020-12 neler ekler
Demet doğrulaması için prefixItems
Draft 7, demetleri items: [] ve additionalItems üzerinden ifade ediyordu. Draft 2020-12 onları temiz bir şekilde böler:
{
"type": "array",
"prefixItems": [
{ "type": "string" },
{ "type": "number" }
],
"items": false
}["x", 42] geçer. ["x", 42, "extra"] başarısız olur. Şema, tam olarak ne yaptığı gibi okunur.
Birleşik şemalar için unevaluatedProperties
allOf veya oneOf kullanan her ekibin başına gelen ince bir hata var: additionalProperties: false, yalnızca göründüğü düzeyi denetler. allOf içindeki kardeş alt şemalar istedikleri özellikleri beyan eder. 2020-12 düzeltmesi unevaluatedProperties: false’tır:
{
"allOf": [
{ "$ref": "#/$defs/base" }
],
"unevaluatedProperties": false
}Bu, herhangi bir dal tarafından değerlendirilmemiş her özelliği reddeder; çoğu geliştiricinin additionalProperties: false’tan beklediği davranış da budur.
Özyinelemeli şemalar için $dynamicRef
Draft 7’de özyinelemeli bir ağaç şeması beyan etmeyi deneyen herkes, sürecin ne kadar zahmetli olduğunu bilir. $dynamicRef ile birlikte $dynamicAnchor bunu temizler:
{
"$dynamicAnchor": "node",
"type": "object",
"properties": {
"value": { "type": "string" },
"children": { "type": "array", "items": { "$dynamicRef": "#node" } }
}
}Özyineleme bildirimseldir ve bir $id yeniden yazımına gerek kalmadan torunlardan geçersiz kılınabilir.
Draft 7 ve 2020-12: hangisini seçmeli
- Yeni proje, modern araç zinciri ise Draft 2020-12 seçin
- OpenAPI 3.1 üretiyor veya tüketiyorsanız 2020-12 yerel lehçedir
- OpenAPI 3.0 veya daha eski servislerle çalışıyorsanız Draft 4 kullanın (OpenAPI 3.0, Draft 4 alt kümesini kullanır; lehçeleri karıştırmayın)
- Geniş doğrulayıcı uyumluluğu gerekiyorsa (Postman, eski CI araçları) Draft 7 hâlâ en güvenli değiş tokuş biçimidir
Her modern doğrulayıcı (Ajv, Python jsonschema, jsonschema-rs, Java’nın networknt/json-schema-validator’ı) bugün 2020-12’yi destekler.
Gerçek dünya kalıpları
API girdi doğrulaması
Yukarıdaki Express middleware, üretim biçimidir. Üzerine iki uygulama önerebiliriz: tüm şemaları depo kökünde bir schemas/ dizininde tutun ve şemaların kendisini JSON Schema meta şemasına karşı doğrulamak için ajv test (veya Python eşdeğerini) çalıştıran bir CI adımı ekleyin.
Yapılandırma dosyaları
Visual Studio Code, SchemaStore entegrasyonuyla gelir; package.json, tsconfig.json ve onlarcası için otomatik tamamlama ile satır içi doğrulama sunar. Kendi yapılandırmalarınıza bir $schema alanı ekleyin; editör kullanıcıları aynı muameleyi alır.
CI test sabitleri
Test sabitleri çürür. Biri bir modeli günceller, bir sabit eski biçiminde kalır, test hâlâ geçer çünkü iddialar değişen alana hiç dokunmamıştır. İddialar çalışmadan önce bir şema denetimiyle bunu yakalayın:
import { glob } from "glob";
const files = await glob("__tests__/fixtures/*.json");
for (const f of files) {
const data = JSON.parse(await fs.readFile(f, "utf8"));
if (!validate(data)) throw new Error(`${f}: ${ajv.errorsText(validate.errors)}`);
}Şema denetimi tetiklendiğinde, sonraki adım genellikle yapısal bir farktır. Neyin kaydığını görmek için sabiti taze bir üretim örneğine karşı JSON Karşılaştır içine çekin. Farkta zaman damgaları ve ID’ler baskınsa, sinyali gürültüden ayırmak için JSON diff rehberindeki anlık görüntü yol-yoksayma kalıplarını uygulayın.
Webhook payload’ları (Stripe, GitHub)
Üçüncü taraf webhook’lar, JSON Schema uygulamak için en yüksek değerli yerlerden biridir. Webhook bir sözleşmedir, sağlayıcı onu değiştirebilir ve değiştirdikleri anı bilmek istersiniz. Stripe ve GitHub, JSON Schema çıkarabileceğiniz OpenAPI tanımları yayımlar. Gelen olayları doğrulayın; kırıcı bir yükseltme, durumu sessizce bozmak yerine izlemenizi tetikler.
Şema odaklı form doğrulaması
React Hook Form’un bir @hookform/resolvers/ajv adaptörü vardır, Vue’nun VeeValidate’i de eşdeğer bir Ajv eklentisine sahiptir. Her ikisi de form gösterimini, hata mesajlarını ve gönderim doğrulamasını tek bir JSON Schema’dan yürütür. Şema tek doğruluk kaynağıdır ve UI onun kurallarını miras alır.
Kullanıcı dostu hata mesajları
Varsayılanlar neden pürüzlü
Varsayılan olarak Ajv, #/properties/email format must match "email" gibi hatalar üretir. Bir 400’ü ayıklayan mühendis için bu yeterlidir. Ödeme formunu dolduran bir kullanıcı için işe yaramaz.
Özel mesajlar için ajv-errors
npm install ajv-errorsimport ajvErrors from "ajv-errors";
ajvErrors(ajv);
const schema = {
type: "object",
properties: { email: { type: "string", format: "email" } },
required: ["email"],
errorMessage: {
properties: { email: "Lütfen geçerli bir e-posta adresi girin" },
required: { email: "E-posta zorunludur" }
}
};errorMessage anahtar kelimesi şemanın içinde kalır; böylece doğrulama kuralları ve kullanıcıya gösterilen metin birlikte taşınır.
Çevrilmiş hatalar için ajv-i18n
ajv-i18n, varsayılan mesajların çevirilerini 30’dan fazla dilde gönderir. Başlangıçta tek bir satır eklersiniz ve doğrulayıcınız İspanyolca, Fransızca, Japonca veya hizmet ettiğiniz hangi dilde olursa olsun konuşur. errorMessage geçersiz kılmalarınız her kısıtlamayı kapsamadığında bir geri dönüş olarak yararlıdır.
Şema yollarını form alanlarına eşleme
Her Ajv hatasının /users/0/email gibi bir instancePath’i vardır. Çoğu form kütüphanesi users[0].email gibi noktalı yollar bekler. Tek satırlık çözüm:
const fieldPath = error.instancePath.replace(/^\//, "").replace(/\//g, ".");Python’un jsonschema’sında eşdeğeri error.absolute_path’tedir. Aynı etki için . ile birleştirin.
Doğrulamayı geçen ama üretimi çökerten beş tuzak
1. format varsayılan olarak yol göstericidir
ajv-formats ve addFormats(ajv) olmadan, her format anahtar kelimesi bir boşa işlemdir. {"format": "email"}, "not-an-email"’i kabul eder. Üretimde her zaman format paketini kurun.
2. additionalProperties varsayılan olarak true’dur
additionalProperties: false olmadan, şemanız beyan edilmemiş her alanı kabul eder. İstemciler, doğrulamayı tamamen atlayan ekstra alanlar gönderebilir. additionalProperties: false’ı girdi sözleşmelerinde varsayılan yapın, gerektiğinde bilinçli olarak gevşetin.
3. additionalProperties birleşmez
allOf, oneOf veya anyOf içinde additionalProperties: false yalnızca kendi düzeyindeki özellikleri inceler. Kardeş alt şemalar arasından kayıp gider. Draft 2020-12 düzeltmesi unevaluatedProperties: false’tır.
4. Uzak $ref bir üretim riskidir
$ref: "https://example.com/schema.json", ilk derlemede Ajv’nin ağ üzerinden veri çekmesine neden olur. Bu, ek gecikme, uzak ana bilgisayar takılırsa DoS açıklığı ve bir MITM saldırı yüzeyi demektir. Tüm $ref hedeflerini satır içine alın veya derleme zamanında diskten yükleyin.
5. Üretilen şemalar gerçek veriden sapar
quicktype ve typescript-json-schema gibi araçlar, mevcut tiplerden şemalar üretir. Çıktı genellikle aşırı izin verici olur (her alan isteğe bağlı, additionalProperties açık). Üretilen şemaları taslak olarak ele alın, elle sıkılaştırın ve gerçek üretim örneklerini şemaya karşı (ve tersi) doğrulayan bir CI çalıştırın; böylece sapma hızla yüzeye çıkar.
Performans: sayılar ve pratik kurallar
- Ajv (Node.js): derlenmiş doğrulayıcılar bir denetimi mikrosaniyenin çok altında halleder. Mevcut en hızlı üretim sınıfı JS doğrulayıcısıdır.
jsonschema(Python): yorumlanmış, Pydantic’ten 10–100 kat yavaş. Bu sıkıntı verdiğindefastjsonschema’ya geçin; Python kodu üretir ve Ajv’ye yakın bir noktaya iner.- Rust ve Go:
jsonschema-rsvexeipuuv/gojsonschema, ağ geçidi katmanında Ajv’nin üzerine 2–5 kat daha verir. - En büyük tek kazanç önceden derlemedir.
ajv.compile(schema)’yı modül yüklenirken bir kez yapın, dönen doğrulayıcıyı her istekte yeniden kullanın. İstek başına yeniden derleme, verimi 50 kat veya daha fazla öldürür.
Sıkça sorulan sorular
JSON Schema doğrulaması sade Türkçeyle nedir?
JSON Schema doğrulaması, bir JSON belgesinin bir sözleşmeye uyup uymadığını denetler. Sözleşme (şema) kendisi de JSON’dur; tipleri, zorunlu alanları ve kısıtlamaları beyan eder. Bir doğrulayıcı, şemayı ve veriyi okur ve “geçer” veya başarısız olan yolları ve nedenini bildirir.
Bir JSON’u şemaya karşı çevrimiçi nasıl doğrularım?
Hızlı bir karar için şemayı ve veriyi ajv.js.org deneme alanına veya jsonschemavalidator.net’ye yapıştırın. JSON bozuk görünüyorsa önce JSON Biçimlendirici ile temizleyin; her ikisi de tarayıcıda çalışır, yükleme gerekmez.
2026’da hangi JSON Schema doğrulayıcısı en hızlısı?
Node’da, önceden derlenmiş doğrulayıcılarla Ajv bir denetimi bir mikrosaniyenin altında halleder. Python’da, fastjsonschema kod üretir ve Ajv sınıfı verime ulaşır. Ağ geçidi katmanında, jsonschema-rs (Rust) ve gojsonschema (Go) Ajv’den 2–5 kat daha hızlıdır. Hangisini seçerseniz seçin, bir kez önceden derleyin ve yeniden kullanın.
JSON Schema ile TypeScript tipleri arasındaki fark nedir?
TypeScript, yazdığınız kodu derleme zamanında denetler. JSON Schema, bilinmeyen JSON’u çalışma zamanında denetler. TypeScript, bir HTTP yanıtından, bir dosyadan veya bir kullanıcı yapıştırmasından gelen JSON’u göremez; JSON Schema tam olarak bunun içindir.
Draft 2020-12’yi mi yoksa Draft 7’yi mi kullanmalıyım?
2026’da yeni projeler için Draft 2020-12’yi seçin. prefixItems, unevaluatedProperties ve $dynamicRef gerçek sorunları çözer. OpenAPI 3.1 yerel olarak 2020-12’yi kullanır. Yalnızca Postman uyumluluğu veya eski servisler için Draft 7’de kalın. OpenAPI 3.0 bir Draft 4 alt kümesini kullanır, lehçeleri karıştırmayın.
Mevcut JSON’dan bir JSON Schema nasıl üretirim?
Üç seçeneğiniz var: örnekleri quicktype.io veya jsonschema.net’e yapıştırın; komut satırında npx genson-js veya pip install genson && genson sample.json çalıştırın; ya da elle yazın. Otomatik üretilen şemalar fazla izin vericidir (her alan isteğe bağlı, additionalProperties: true); bu yüzden onları sözleşme olarak ele almadan önce her zaman sıkılaştırın.
JSON Schema, OpenAPI’nin yerine geçebilir mi?
Hayır. OpenAPI, istek ve yanıt gövdelerini tanımlamak için dahili olarak JSON Schema kullanır; ardından yollar, güvenlik şemaları, parametreler ve sunucu URL’leri ekler. Birbirini tamamlarlar: şemalarınızı yazın, bir OpenAPI belgesinden onlara referans verin, eksiksiz API sözleşmeleri elde edin.
JSON Schema, JSONPath veya jq ile aynı mı?
Farklı problemler. JSON Schema yapıyı doğrular (“bu JSON sözleşmeye uyuyor mu?”). JSONPath ve jq değerleri çıkarır (“Running fazındaki her pod adı”). Şemayla doğrulayın; JSONPath veya jq ile sorgulayın.
Ajv doğrulamam neden geçiyor ama üretim veriyi reddediyor?
Üç suçlu neredeyse her vakayı kapsar: ajv-formats’ı unutmak (böylece format: "email" hiç doğrulanmamış olur); additionalProperties: false’ı atlamak (böylece ekstra istemci alanları geçer); allOf veya oneOf içinde additionalProperties: false kullanmak ve birleşmediğini keşfetmek. Bu son durumda unevaluatedProperties: false’a geçin.
Son kullanıcılar için JSON Schema hata mesajlarını özelleştirebilir miyim?
Evet. Node’da, şemanın içine errorMessage gömmek için ajv-errors’ı ve 30’dan fazla dilde çeviriler için ajv-i18n’i kurun. Python’da, jsonschema her hata nesnesinde tam doğrulama bağlamını ortaya çıkarır; böylece hata türünü ve yolunu, tasarım sisteminizin kullandığı metne eşleyebilirsiniz.