JSON Schema: Frontend ile Backend Arasındaki Sözleşme

JSON Schema Nedir?

JSON Schema, JSON belgelerini açıklamanıza ve doğrulamanıza olanak tanıyan bir kelime dağarcığıdır. Bunu yalnızca derleme zamanında değil, çalışma zamanında da çalışan JSON için bir tip sistemi olarak düşünün.

{
  "type": "object",
  "properties": {
    "id": { "type": "integer" },
    "email": { "type": "string", "format": "email" }
  },
  "required": ["id", "email"],
  "additionalProperties": false
}

additionalProperties: false Neden Önemlidir

Bu, herhangi bir JSON Schema'daki tek en değerli satırdır. Onsuz şemanız bir öneridir. Onunla bir sözleşmedir — properties içinde olmayan herhangi bir anahtar doğrulamanın başarısız olmasına neden olur.

Bu, en yaygın API kayması senaryosunu yakalar: backend yeni bir zorunlu alan ekler ve frontend bir şey çalışma zamanında bozulana kadar bunu sessizce görmezden gelir.

Gerçek Verilerden Schema Oluşturma

JSON Schema yazmanın en hızlı yolu gerçek API yanıtlarından başlamaktır. Gerçek bir yanıtı dönüştürücümüze yapıştırın ve anında taslak bir schema elde edin. Ardından:

1. required dizisini gözden geçirin — gerçekten isteğe bağlı olan alanları kaldırın
2. Dizeler için "format" ipuçları ekleyin: "date-time", "email", "uuid"
3. İş mantığının geçerli olduğu sayılar için "minimum"/"maximum" ekleyin
4. Şekil kararlı hale geldiğinde additionalProperties: false ayarlayın

Doğrulama Kütüphaneleri

Dil	Kütüphane
JavaScript/TypeScript	ajv, zod (with .parse)
Python	jsonschema, pydantic
Go	gojsonschema
Java	networknt/json-schema-validator
Rust	jsonschema crate

Schema vs Zod vs TypeScript

Bu araçlar rekabet etmez, birbirini tamamlar:

• TypeScript kod tabanınızdaki derleme zamanında tip hatalarını yakalar
• Zod uygulama sınırınızda çalışma zamanında doğrulama yapar (API çağrıları, form girişleri)
• JSON Schema herhangi bir yerde, herhangi bir dilde doğrulama yapar ve API dokümantasyonunun standardıdır (OpenAPI bunu kullanır)

Maksimum kapsam için üçünü birden kullanın.