Schema

Schema bileşeni, transition, flow ve master-data için JSON şema tanımıdır. Hem ön uçta hem arka uçta istekler doğrulanır ve instance data tutarlılığı korunur.

Schema kaynağı: vnext-schema/schema-definition.schema.json

Tanım JSON Örneği

Schema: schema-definition.schema.json

{
  "key": "account-type-selection",
  "version": "1.0.0",
  "domain": "banking",
  "flow": "sys-schemas",
  "flowVersion": "1.0.0",
  "tags": ["banking", "account", "selection"],
  "_comment": "Hesap türü seçimi için transition schema",
  "attributes": {
    "type": "workflow",
    "schema": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "$id": "https://schemas.vnext.com/banking/account-type-selection.json",
      "title": "Account Type Selection",
      "description": "Schema for account type selection input",
      "type": "object",
      "required": ["accountType"],
      "properties": {
        "accountType": {
          "type": "string",
          "title": "Account Type",
          "description": "Type of account to be opened",
          "oneOf": [
            { "const": "demand-deposit", "description": "Vadesiz Hesap" },
            { "const": "time-deposit", "description": "Vadeli Hesap" },
            { "const": "savings-account", "description": "Tasarruf Hesabı" }
          ]
        }
      },
      "additionalProperties": false
    },
    "labels": [
      { "label": "Account Type Selection", "language": "en-US" },
      { "label": "Hesap Türü Seçimi", "language": "tr-TR" }
    ]
  }
}

---

Kullanım Türleri

Tür	Atandığı Yer	Amacı
Master Schema	Workflow root (attributes.schema)	Instance data ana yapısı; her değişimde tutarlılık kontrolü
Transition Schema	Transition tanımı	Transition request body validation

---

Master Schema Davranışı

Master schema, flow'un kendisine tanımlanır ve instance data'nın şablon yapısını belirler. Amacı yalnızca doğrulama değil; aynı zamanda x-roles (alan bazlı yetkilendirme), x-encryption, x-lookup gibi vNext özelliklerini ve instance filtering'i etkin kılmaktır. Bir instance data merge uygulandığında flow'da master schema tanımlıysa runtime bunu valide eder; uygun değilse isteği reject eder.

required kullanmayın, additionalProperties: true olmalı

Instance data her state'de merge ile genişler ve farklı seviyelerde yeni alanlar kazanır. Bu nedenle master schema'da:

• required kullanılmamalıdır — aksi halde henüz oluşmamış alanlar erken merge'lerde reddedilir.
• additionalProperties: true olmalıdır — verinin genişlemesine izin verecek şekilde.

Zorunluluk ve sıkı doğrulama, master schema'da değil transition schema'larında (request body validation) yapılmalıdır.

Buna karşılık master schema'da pattern, ana omurga şablonu, vocabulary tanımları (x-*) ve filtering tanımları kıymetlidir ve korunmalıdır.

Filtering ve Data Function'daki Rolü

Data Function veriyi response ederken master schema aktif rol alır. Instance filtering sırasında, instance data gibi dinamik alanların tiplerini şemadan çözerek gelişmiş (advance) filtre esnekliği kazandırır. Master schema olmadan dinamik alanlarda tip-duyarlı filtreleme mümkün olmaz. Bir alanın hangi operatörlerle filtrelenebileceği ve sıralanabilirliği x-filterOperators / x-sortable ile bildirilir (aşağıda).

Alan bazlı görünürlük, master şema property'lerinde x-roles keyword'ü ile tanımlanır (aşağıda); bkz. Yetkilendirme → Master Şema Alan Görünürlüğü.

Alan Bazlı Yetkilendirme: x-roles

x-roles, bir JSON Schema property'sine (instance data field'ı) rol değerlendirmesi (role evaluation) ile yetkilendirme uygulayan vocabulary keyword'üdür. Özellikle master şemada önem kazanır: hangi field'ların kime görünür olacağını x-roles belirler — yani alan (column) seviyesinde güvenlik sağlar. Data Function ve veri dönen endpoint'ler authorize katmanını çalıştırıp yalnızca çağıranın görmesine izinli alanları döndürür.

{
  "x-roles": [
    { "role": "morph-idm.initiator", "grant": "allow" },
    { "role": "$userBehalfOf.$.context.Instance.Data.initial.customer.ownerUserId", "grant": "deny" }
  ]
}

Alan	Tip	Zorunlu	Açıklama
x-roles	array	—	Property için rol grant listesi (minItems: 1). Tanımlı değilse field tüm yetkili çağıranlara görünür
role	string	Evet	Domain-qualified rol adı (ör. morph-idm.initiator) veya dinamik JSONPath ifadesi (ör. $userBehalfOf.$.context...)
grant	string	Evet	allow veya deny. DENY her zaman ALLOW'u geçersiz kılar

role değeri statik bir ad ya da JSONPath ifadesi olabilir; sistem rolleri ($InstanceStarter vb.) ve JSONPath grant prefiksleri ($user. / $userBehalfOf. / $role.) burada da geçerlidir. Bu kalıpların çözümleme semantiği için bkz. Yetkilendirme.

x-encryption de aynı alan-yönetişim kapsamındadır; bir field'ın şifreleme tipini (persisted / transport) belirtir. Tüm property seviyesi x-* uzantılarının ayrıntısı için bkz. Schema Tanımı.

Filtreleme & Sıralama Vocabulary'si

Bir JSON (attributes.*) alanının filtrelenip sıralanabilirliği master şemada üç keyword ile bildirilir. Data Function ve instance listeleme endpoint'leri (.../instances?filter=, .../functions/data) bu vocabulary'e göre çalışır:

Keyword	Tip	Zorunlu	Açıklama
x-filterOperators	string[]	Hayır	İzin verilen filtre operatörleri. Boş veya yok ise alan filtrelenemez
x-sortable	boolean	Hayır	true ise alan sıralanabilir. Yok ise sıralanabilir değil
x-displayFormat	string	Hayır	UI'a yönelik format ipucu (örn. yyyy-MM-dd'T'HH:mm:ssXXX)

x-filterOperators değerleri: eq, ne, gt, ge, lt, le, between, match, like, startswith, endswith, in, nin (uniqueItems).

"startDateTime": {
  "type": "string",
  "format": "date-time",
  "x-filterOperators": ["eq", "gt", "ge", "lt", "le", "between"],
  "x-sortable": true,
  "x-displayFormat": "yyyy-MM-dd'T'HH:mm:ssXXX"
}

Kurallar (özet):

• x-filterOperators dolu ise alan filtrelenebilir; boş/yok ise filtrelenemez.
• x-sortable: true değilse alan sıralanamaz.
• Filtrelenemez bir alan veya izin verilmeyen bir operatör kullanıldığında SchemaFilterValidationException fırlatılır.

Operatörlerin alan tipine göre (numeric / tarih / metin / boolean / dizi) davranışı, JSON dizi alanları için includes operatörü ve SchemaFilterValidationException ayrıntıları için bkz. Instance Filtering → Şema-Tabanlı Filtrelenebilirlik.

Data Context Vocabulary (data-vocab)

Vocabulary: vnext-schema/vocabularies/data-vocab.json

data-vocab, şema güdümlü client context-store bağlama için iki anotasyon tanımlar. Amaç: generic bir client'ın, akış başına özel kod yazmadan — yalnızca backend şemalarından — girdi alanlarını client context-store'undan çözmesi ve yeniden kullanılabilir çıktıları oraya geri yazması.

Anotasyon	Nerede tanımlanır	Yön	Ne zaman uygulanır
x-context-source	Transition input şemasının bir property'sinde	context-store → input	Start/transition payload'ı oluşturulurken
x-context-target	Workflow master şemasında	instance data → context-store	Her instance okumasında (start sonucu, her transition sonrası)

x-context-source — property'yi client tarafından çözülen bir alan olarak işaretler; client bu alan için form field'ı render etmez. Değer üç kaynaktan birinden gelir:

Form	Anlamı
{ "const": <değer> }	Şemaya gömülü literal değer (yalnız source)
{ "context": { "boundary": "device|user|subject", "key": "<key-template>", "storage"?: "memory|local|secure" } }	Context-store veri slot'u. key şablonu {instance} ve {subject} interpolasyonu destekler
{ "identity": "subject" | "user" }	Context-store kimliği — aktif subject (JWT sub, örn. login'li userId) veya aktif user (yalnız source)

"properties": {
  "oldPassword": { "type": "string" },
  "channel":  { "type": "string", "x-context-source": { "const": "web" } },
  "deviceId": { "type": "string", "x-context-source": { "context": { "boundary": "device", "key": "device.id" } } },
  "userId":   { "type": "string", "x-context-source": { "identity": "subject" } }
}

x-context-target — master şema üzerinde, instance data alan yollarını (dot-notation) context-store slot'larına eşler. Client bunu her instance okumasında uygular; böylece bir transition'dan sonra ortaya çıkan değerler (token, cihaz kaydı, sertifika…) otomatik olarak context-store'a taşınır ve sonraki akışlar x-context-source ile okuyabilir. Hedefler yalnızca context slot'u olabilir (const ve identity source-only'dir):

"x-context-target": {
  "deviceData.instanceId": { "context": { "boundary": "device", "key": "device.registration.{instance}" } },
  "certificate":           { "context": { "boundary": "device", "key": "device.cert.{instance}", "storage": "secure" } }
}

{instance} şablonu: Aynı mantıksal alan farklı instance'larda gelebilir (örn. cihaz başına bir device-manager instance'ı). Key'e {instance} (instance id) eklemek her instance'ın değerini ayrı bir konuma yazar. Akışlar arası singleton değerler için {instance} kullanmayın — sabit bir key'de kalsın ki sonraki akışın x-context-source'u bulabilsin. Kullanılabilir şablon değişkenleri: {instance}, {subject}.

:::note Geriye dönük uyumluluk JSON Schema (draft 2020-12) bilinmeyen keyword'lere izin verir: standart validator'lar x-context-* anotasyonlarını yok sayar. Anotasyonsuz bir şema bugünkü gibi davranır — benimseme şema başına ve kademelidir. :::

View ile Kullanımı

• Read-only view (girdi yoksa): master schema doğrudan view'a dataSchema olarak verilebilir; mevcut durumu özetleyen ekranlar için yeterlidir.
• Girdi içeren view: girdi alınan kısımlarda master schema değil, transition'a özel schema kullanılmalıdır.

vNext vocabulary'sinin (x-labels, x-lov, x-lookup, x-conditional, x-encryption vb.) ayrıntılı anlatımı için bkz. Pseudo UI → Schema Tanımı.

---

Properties

Top-Level Alanlar

Alan	Tip	Zorunlu	Pattern / Kısıt	Açıklama
$schema	string	Hayır	—	JSON Schema referansı
key	string	Evet	^[a-z0-9-]+$	Schema'nın benzersiz tanımlayıcısı
version	string	Evet	^\d+\.\d+\.\d+(-[a-zA-Z]+\.\d+)?$	Semantic versioning (Major.Minor.Patch)
domain	string	Evet	^[a-z0-9-]+$	Schema'nın ait olduğu domain
flow	string	Evet	Sabit: sys-schemas	Flow tanımlayıcısı
flowVersion	string	Evet	^\d+\.\d+\.\d+(-[a-zA-Z]+\.\d+)?$	Flow versiyonu
tags	string[]	Evet	minItems: 1	Kategorilendirme ve arama etiketleri
_comment	string	Hayır	—	Açıklama / yorum
attributes	object	Evet	—	Schema davranış tanımı (aşağıda)

attributes Alanları

Alan	Tip	Zorunlu	Açıklama
type	string	Evet	Schema tipi — aşağıdaki enum tablosuna bakın
schema	object	Evet	JSON Schema tanımı (Draft 2020-12). Aşağıdaki iç yapı tablosuna bakın
labels	array	Hayır	Çoklu dil etiketleri. Her öğe: label (string) + language (pattern: ^[a-z]{2}-[A-Z]{2}$)

attributes.type Enum Değerleri

Değer	Açıklama
workflow	Workflow bileşeni tanımı
task	Task bileşeni tanımı
function	Function bileşeni tanımı
view	View bileşeni tanımı
schema	Schema bileşeni tanımı
extension	Extension bileşeni tanımı
headers	Headers schema tanımı

attributes.schema İç Yapısı (JSON Schema)

Alan	Tip	Zorunlu	Açıklama
$schema	string	Evet	JSON Schema spesifikasyon versiyonu. Sabit: https://json-schema.org/draft/2020-12/schema
$id	string	Evet	Schema tanımlayıcı URI'si
title	string	Evet	Schema başlığı (minLength: 1)
type	string	Evet	JSON tipi: object, array, string, number, integer, boolean, null
description	string	Hayır	Schema açıklaması
properties	object	Hayır	Obje property tanımları
required	string[]	Hayır	Zorunlu property listesi
additionalProperties	boolean	Hayır	Ek property'lere izin verilip verilmeyeceği
items	object	Hayır	Array elemanları schema tanımı
enum	array	Hayır	İzin verilen sabit değerler listesi
oneOf	array	Hayır	Alternatif schema seçenekleri (tam bir eşleşme)
anyOf	array	Hayır	Alternatif schema seçenekleri (en az bir eşleşme)
allOf	array	Hayır	Tüm schema gereksinimleri (tümü eşleşmeli)
if / then / else	object	Hayır	Koşullu schema tanımları
format	string	Hayır	String format doğrulaması (örn. email, date-time, uri)
pattern	string	Hayır	String regex doğrulaması
minimum / maximum	number	Hayır	Sayısal değer aralığı
minLength / maxLength	integer	Hayır	String uzunluk aralığı
minItems / maxItems	integer	Hayır	Array eleman sayısı aralığı
const	any	Hayır	Sabit değer
default	any	Hayır	Varsayılan değer

Standart JSON Schema alanlarına ek olarak, property seviyesinde vNext x-* vocabulary uzantıları desteklenir — alan bazlı yetkilendirme (x-roles), şifreleme (x-encryption), filtreleme (x-filterOperators), sıralama (x-sortable), görüntü formatı (x-displayFormat), etiketleme (x-labels), LOV (x-lov), lookup (x-lookup), koşullu görünürlük (x-conditional), client context bağlama (x-context-source, x-context-target) vb. Tam liste ve örnekler için bkz. Schema Tanımı ve Data Context Vocabulary.

---

Validation

Schema'lar Ajv2019 ile doğrulanır. Front-end'de form validation için annotation'lar kullanılabilir; back-end'de transition/start request'lerinde otomatik valide edilir.

• Frontend: form annotation, real-time validation
• Backend: request body validation, instance data merge validation
• CI/CD: schema kendisi vnext-schema repo'da merkezi olarak doğrulanır

Tipik Kullanım Senaryoları

• Master schema ile instance data'nın immutable ve versionable kalmasını garanti et
• Transition schema ile her transition için farklı request body validation

İlgili

• Instance Data — instance veri yapısı
• Workflow component — attributes.schema master schema referansı
• Pseudo UI → Schema Tanımı — vNext vocabulary (x-labels, x-lov, x-lookup, x-conditional, x-encryption)
• Yetkilendirme — master şema alan bazlı görünürlük
• Instance Filtering — master schema ile tip-duyarlı filtreleme
• Mappings — transition ve mapping kullanımı
• Schema kaynağı: vnext-schema (GitHub)