JSON Schema Doğrulayıcı

JSON Schema Doğrulayıcı Nedir?

// A 5-line schema that catches three real bugs
const schema = {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id":    { "type": "integer", "minimum": 1 },
    "email": { "type": "string", "format": "email" },
    "age":   { "type": "integer", "minimum": 0, "maximum": 150 }
  },
  "required": ["id", "email"],
  "additionalProperties": false
};

// Three bugs the schema catches:
const bad = { "id": "42", "age": 200 };
//   /id   → type: expected integer, got string
//   /email → required: missing
//   /age   → maximum: 200 > 150

// In Node:        new Ajv().compile(schema)(bad)  // false; ajv.errors has the paths
// In Python:      jsonschema.validate(bad, schema)
// In the browser: this tool — same errors, same paths, no install

Temel Özellikler

Örnekler

{
  "id": 42,
  "email": "alice@example.com",
  "age": 30
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": { "type": "integer", "minimum": 1 },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "minimum": 0, "maximum": 150 }
  },
  "required": ["id", "email"],
  "additionalProperties": false
}

{
  "id": "42",
  "age": 200
}

{
  "type": "object",
  "properties": {
    "id": { "type": "integer" },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "maximum": 150 }
  },
  "required": ["id", "email"]
}

{
  "type": "order.created",
  "data": { "orderId": "ORD-001234", "totalUsd": 49.99 }
}

{
  "oneOf": [
    {
      "properties": {
        "type": { "const": "order.created" },
        "data": {
          "type": "object",
          "properties": {
            "orderId": { "type": "string", "pattern": "^ORD-[0-9]{6}$" },
            "totalUsd": { "type": "number", "minimum": 0 }
          },
          "required": ["orderId", "totalUsd"]
        }
      },
      "required": ["type", "data"]
    },
    {
      "properties": {
        "type": { "const": "order.refunded" },
        "data": { "type": "object", "required": ["refundId"] }
      },
      "required": ["type", "data"]
    }
  ]
}

[
  { "sku": "A1", "qty": 3 },
  { "sku": "B2", "qty": 5 },
  { "sku": "A1", "qty": 3 }
]

{
  "type": "array",
  "minItems": 1,
  "uniqueItems": true,
  "items": {
    "type": "object",
    "properties": {
      "sku": { "type": "string", "pattern": "^[A-Z][0-9]+$" },
      "qty": { "type": "integer", "minimum": 1 }
    },
    "required": ["sku", "qty"]
  }
}

Nasıl Kullanılır

1. 1

   JSON Schema'nızı yapıştırın

   Schema'nızı sağ panele bırakın. Doğrulayıcı, $schema URI'si varsa draft'ı otomatik algılar; yoksa araç çubuğundan Draft 2020-12, 2019-09 veya Draft-07'yi seçin.

2. 2

   JSON verinizi yapıştırın

   Kontrol etmek istediğiniz JSON belgesini sol panele bırakın. Doğrulama yazarken çalışır; büyük girişler (>200 KB) yazımı akıcı tutmak için manuel Doğrula düğmesine geçer.

3. 3

   Hata listesini okuyun

   Her hatanın bir JSON Pointer yolu, bir keyword'ü ve tek satırlık bir mesajı vardır. Bir hataya tıklayarak verinizdeki konuma atlayın, düzeltin ve sayacın gerçek zamanlı düştüğünü görün.

Yaygın JSON Schema Tuzakları

{ "qty": 1.0 }   schema: { "type": "integer" }   → error: not an integer

{ "qty": 1 }     schema: { "type": "integer" }   → valid

{ "properties": { "name": { "type": "string", "required": true } } }

{ "properties": { "name": { "type": "string" } }, "required": ["name"] }

{ "properties": { "id": { "type": "integer" } } }   accepts: { "id": 1, "foo": "bar", "x": null }

{ "properties": { "id": { "type": "integer" } }, "additionalProperties": false }

{ "type": "string", "nullable": true }   in 2020-12: nullable is just an unknown keyword

{ "type": ["string", "null"] }   in 2020-12: explicitly allows null

pattern: "[A-Z]+"   accepts: "helloX"   (because X matches)

pattern: "^[A-Z]+$"   accepts only: "HELLO"

oneOf: [ { type: "string" }, { type: "string", maxLength: 10 } ]   on: "hi"   → error: matches both

anyOf: [ { type: "string" }, { type: "string", maxLength: 10 } ]   on: "hi"   → valid

Yaygın Kullanım Senaryoları

API İstek Doğrulaması

Deploy etmeden önce bir istek gövdesini ve endpoint'inizin schema'sını yapıştırın. Testlerinizin kapsamadığı 400 yanıtlarını yakalayın — eksik required alanlar, yanlış türler, aralık dışı sayılar.

Webhook Payload Doğrulaması

Tedarikçi, handler'ınızın reddettiği bir payload mı gönderdi? Gerçek payload'u önce kendi schema'nıza, sonra tedarikçinin yayımlanmış schema'sına karşı doğrulayın. İkisi arasındaki diff sizin bug'ınızdır.

Yapılandırma Dosyası Linting

package.json, tsconfig.json, helm values.yaml — her yapılandırma dosyasının açık bir schema'sı vardır. Schema'yı yapıştırın, yapılandırmayı yapıştırın, yazım hatasını bulun. Deneme-yanılmayı atlayın.

OpenAPI Bileşen Testi

Bir OpenAPI 3.1 belgesinden bir schema bileşenini çıkarın, buraya yapıştırın, örnek payload'ları doğrulayın. Mock sunucu kurmaktan hızlı, deterministik, SDK'sız.

Form Gönderimi Pre-Flight

Frontend doğrulamasını bağlamadan önce örnek bir form payload'unu yapıştırın. Schema'nın beklediklerinizi reddettiğini, kabul ettiğini onaylayın, sonra aynı schema'yı istemciye ve sunucuya gönderin.

Veri Pipeline Sözleşme Denetimi

ETL çıktınız mı kaydı? Örnek bir satır ile aşağı akıştaki schema'yı yapıştırın. Pipeline 10.000 kaydı yeniden denemeden önce hangi üreticinin değiştiğini ve hangi anahtarların kırıldığını saptayın.

Teknik Detaylar

Draft 2020-12 Uyumlu

Yayımlanan Draft 2020-12 spektini uygular — keyword'ler, tür sistemi, format sözlüğü. Ajv 8.x ve ajv-formats çıktısına karşı çapraz doğrulanmıştır.

JSON Pointer Hata Yolları

Hatalar RFC 6901 JSON Pointer kullanır (/user/email/0). Her keyword başarısızlığı veride tek bir çözülebilir konumu işaret eder — belirsizlik yok, string araması yok.

Dahili $ref Çözümü

Tek bir belge içindeki $ref işaretçilerini çözer (#/$defs/foo, #/properties/bar). Döngüler tespit edilir ve raporlanır. Harici HTTP $ref'leri gizlilik için devre dışıdır.

En İyi Uygulamalar

Daima additionalProperties: false Ayarlayın

Giriş sözleşmelerinde (istek gövdeleri, yapılandırma dosyaları, kuyruk mesajları) bilinmeyen anahtarlar genellikle bug'lardır — yazım hataları, kazara alanlar veya saldırgan yoklamaları. Varsayılan olarak reddedin.

Yeniden Kullanılabilir Alt Schema'lar İçin $defs Kullanın

Aynı şekli iki kez satır içine alın, kayar. Ortak tanımları $defs'e taşıyın ve $ref ile başvurun — tek doğru kaynak, her değişiklik her yerde uygulanır.

İş Mantığından Önce Doğrulayın

JSON.parse'ın hemen ardından, parse edilmiş yapıya dokunmadan önce schema doğrulamasını çalıştırın. Tür daraltma, varsayılan atama ve kalıcılaştırma sözleşmenin tutmasına bel bağlar — tuttuğundan emin olun.

Sık Sorulan Sorular