JSON Şeması: Temel Kavramlar ve Uygulama Rehberi

JSON Schema Nedir? – Kısa ve Net Tanım

JSON Schema, JSON verilerini tanımlamak, doğrulamak ve otomatik olarak belgelemek için kullanılan bir standarttır. Bu tanım, geliştiricilerin, veri mühendislerinin ve teknik mimarların veri modellerini tutarlı ve güvenli bir şekilde yönetmelerine olanak tanır.

Bu makalede, JSON Schema’nın temel kavramları, pratik örnekleri, genişletme yöntemleri ve gelecekteki trendler ele alınacak. Ayrıca, UBOS homepage üzerinden sunulan AI‑destekli platformların JSON Schema ile entegrasyonu incelenecek.

Temel Terimler: Şema, Metaschema, Diyalekt, Sözlük, Anahtar Kelimeler, Anchor, Uzantılar

Şema (Schema)

Veri yapısını tanımlayan temel JSON belgesidir. Örneğin, bir kullanıcı nesnesi için aşağıdaki şema kullanılabilir:

{
  "type": "object",
  "properties": {
    "username": { "type": "string", "minLength": 3 },
    "email":    { "type": "string", "format": "email" },
    "age":      { "type": "integer", "minimum": 13 }
  },
  "required": ["username", "email"]
}

Metaschema (Metaschema)

Şemaların yapısını tanımlayan şemadır. Metaschema, bir şemanın geçerli olup olmadığını kontrol eder. Örneğin, "type" anahtarının yalnızca belirli değerleri alabileceği metaschema içinde tanımlanır.

Diyalekt (Dialect)

JSON Schema’nın farklı sürümlerine (Draft‑4, Draft‑7, Draft‑2020‑12 vb.) verilen isimdir. Diyalekt, hangi anahtar kelimelerin geçerli olduğunu ve davranışlarını belirler. Şemanızın başında "$schema" özelliğiyle diyalekti tanımlarsınız:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object"
}

Sözlük (Vocabulary)

Anahtar kelimelerin mantıksal gruplandırılmasıdır. Örneğin, core, validation ve metadata sözlükleri vardır. Sözlükler, şemanın modüler ve genişletilebilir olmasını sağlar.

Anahtar Kelimeler (Keywords)

Şemada kullanılan özel isimlerdir (type, properties, minimum vb.). Anahtar kelimeler iki kategoriye ayrılır:

• Assertions: Doğrulama hatası oluşturur (ör. minimum).
• Annotations: Sadece belge amaçlıdır, doğrulamayı etkilemez (ör. title, description).

Anchor ve Dynamic Anchor

Şema içinde referans noktaları oluşturur. $anchor sabit bir referans iken, $dynamicAnchor bağlam‑bağımlı referanslar sağlar.

Uzantılar (Extensions)

Özel iş ihtiyaçlarına göre tanımlanan ek anahtar kelimelerdir. Örneğin, bir veri tabanı şeması dbIdentifier gibi bir uzantı ekleyebilir.

JSON Schema Genişletme ve Özelleştirme

JSON Schema, vocabularies ve uzantılar sayesinde kolayca genişletilebilir. Aşağıdaki adımlar, özel bir uzantı oluşturmayı gösterir.

Adım 1 – Core Vocabulary’i Kullanma

Her uzantı, core sözlüğünü zorunlu kılar. Örneğin, bir dbIdentifier uzantısı şöyle tanımlanabilir:

{
  "$id": "https://example.com/vocab/db",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$vocabulary": {
    "https://json-schema.org/draft/2020-12/vocab/core": true
  },
  "type": "object",
  "properties": {
    "dbIdentifier": {
      "type": "string",
      "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$"
    }
  }
}

Adım 2 – Şemaya Uzantıyı Entegre Etme

Ana şemanıza yeni anahtar kelimeyi ekleyin ve $vocabulary içinde uzantıyı işaretleyin:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$vocabulary": {
    "https://json-schema.org/draft/2020-12/vocab/core": true,
    "https://example.com/vocab/db": true
  },
  "type": "object",
  "properties": {
    "tableName": {
      "type": "string",
      "dbIdentifier": true
    }
  }
}

Adım 3 – UBOS Üzerinde Uygulama

UBOS platformu, özelleştirilmiş şemaları UBOS platform overview içinde doğrudan kullanmanıza izin verir. Özellikle Enterprise AI platform by UBOS sayesinde, uzantılı şemalar AI model girişleri olarak güvenle işlenebilir.

Adım 4 – Şema Doğrulama ve Test

UBOS, UBOS pricing plans kapsamında çevrimiçi bir validator sunar. Şemanızı yükleyip, örnek JSON verileriyle test edebilirsiniz.

Kaynaklar ve Dış Bağlantı

Bu makale, aşağıdaki kaynaklardan derlenmiştir:

• JSON Schema Demystified – Orijinal Makale
• JSON Schema Resmi Dokümantasyonu: json-schema.org
• UBOS Platform Belgeleri: About UBOS