Tip Sistemi

Temel tipler

Bileşik tipler

enum

status: enum["pending", "approved", "rejected"]

Yalnızca string değerler alır ve boş olamaz. JSON Schema karşılığı { "type": "string", "enum": [...] }. Listede olmayan bir değer X.y must be one of these values: … hatası verir.

Array

tags: string[]        // unbounded list of strings
items: LineItem[]      // list of nested schemas
grid: int[][]         // nested array

JSON Schema: { "type": "array", "items": { … } }. Her eleman ayrı ayrı doğrulanır ve hata mesajında indeks görünür: Invoice.items[2].amount missing.

Elemana [] ile erişilir — rows[0], rows[i].customer.name — ve aynı biçim bir ='in solunda yazma yapar. Sonun ötesini okumak adlandırılmış hatadır, sessiz bir null değil: xs[5] is out of bounds (length 2). Sonun ötesine yazmak da reddedilir; liste indekslenerek büyümez. Sınır durumlarının tam tablosu dil sayfasındadır.

map<T> / record<T>

metrics: map<float>       // { "score": 0.95, "confidence": 0.8 }
labels: record<string>    // record is an alias for map

Dinamik anahtarlı nesne. JSON Schema: { "type": "object", "additionalProperties": { … } }. Anahtarlar serbesttir, değerlerin tipi doğrulanır.

Değere m["key"] ile erişilir; olmayan bir anahtara yazmak onu oluşturur. Olmayan bir anahtarı okumak ise null döndürmez — eksik anahtar adlandırılmış bir hatadır: m["missing"] is not present. Bu yalnızca runtime hakkında değil, tip hakkında bir ifadedir: map<T> T tutar, T | null değil; yani lookup, programa null'ın girebileceği bir yer değildir. Emin olmadığın bir anahtar okunmadan önce kontrol edilmelidir:

import col from "std/collections"

agent Reader {
  fn read(labels: map<string>, key: string) -> Out {
    if contains(col.keys(labels), key) {
      return { value: labels[key] }
    }
    return { value: "unknown" }
  }
}

İndekslemenin sınır durumlarının tam tablosu — listeler ve map'ler, okuma ve yazma — dil sayfasındadır.

schema MetaEntry {
  key: string
  value: string
}

// inside InvoiceExtract:
meta: MetaEntry[] @desc("Schema alanlarına girmeyen tüm bilgiler")

json<T>

import json from "std/json"

schema Envelope {
  raw: string           // JSON text
  data: any              // parsed, unvalidated value
  payload: json<Payload>    // parsed AND validated against Payload
}

Tuple

coordinate: [float, float]      // exactly two elements, positional

Sabit uzunluklu, konum-tipli array. Doğrulamada eleman sayısı ve her konumun tipi kontrol edilir. En az bir virgül içermelidir ([float] tuple değildir).

Error: @range can only be used on numeric fields or numeric arrays.

schema Point {
  lat: float [-90..90]
  lon: float [-180..180]
}

Schema referansı

schema Address {
  city: string
}

schema Customer {
  address: Address      // nested object
  history: Address[]    // list of nested objects
}

JSON Schema'da { "$ref": "#/$defs/Address" } olarak üretilir; tanım $defs altında bir kez yer alır.

Parametrik schema — Name<T>

schema LineItem {
  sku: string
  amount: float
}

schema Page<T> {
  items: T[]
  total: int
}

schema Report {
  page: Page<LineItem>
}

Bir schema tip parametresi alabilir. Gövdenin içinde parametre başka herhangi bir tip adı gibi okunur; her kullanım yeri de somut bir argüman verir: Page<LineItem>, Page<Customer>.

Page<LineItem> dosya parse edilirken açılır. Parser Page'in gövdesini kopyalar, T'nin durduğu yere LineItem'ı koyar ve sonucu Page_LineItem adıyla sıradan bir schema olarak kaydeder. O noktadan sonra hiçbir şey ortada bir parametre olduğunu bilmez — JSON Schema üretimi, doğrulama, $defs, where, when, @desc ve std/schema reflection'ı, elle yazılmış bir schema'da nasıl işliyorsa açılmış schema üzerinde de aynen öyle işler; sağlayıcıya hiçbir genericlik ulaşmaz.

Gördüğün ad, açılmış addır. Hem $defs anahtarı odur, hem schema.name(…) onu döndürür, hem de o schema'ya karşı üretilen doğrulama hatasının öneki odur:

Page_LineItem.items[0].amount missing.

Schema adının kabul edildiği her pozisyon

Asıl önemli olan taşıma durumu: üreten method Page<LineItem> döndürür, tüketen method aynı şeyi parametre olarak alır; böylece sarmalayıcı ikisinin arasındaki sınırda elle açılmak zorunda kalmaz.

Birden fazla parametre, iç içe kullanım, primitive'ler

schema LineItem {
  sku: string
}

schema Customer {
  name: string
}

schema Page<T> {
  items: T[]
}

schema Pair<A, B> {
  left: A
  right: B
}

schema Box<T> {
  value: T
}

schema Envelope<T> {
  payload: T
  trace_id: string
}

schema Deep<T> {
  inner: Box<T>
}

schema Catalogue {
  pair: Pair<LineItem, Customer>
  pages: Page<Envelope<LineItem>>
  count: Box<int>
  deep: Deep<LineItem>
}

Tip argümanı bir primitive (Box<int>), bir schema veya başka bir açılım (Page<Envelope<LineItem>>) olabilir; generic bir gövde de ikinci bir generic'e başvurabilir — yukarıdaki Deep<T> içinde bir Box<T> taşıyor. Birbirinden farklı her açılım bir kez üretilir ve adı argümanlarından kurulur: Pair_LineItem_Customer, Page_Envelope_LineItem, Box_int, Deep_LineItem. Argüman sayısı tutmazsa sayı adıyla söylenir: Generic schema 'Pair' expects 2 type argument(s), got 1.

Parametre neyin yerine geçer, ona ne verilebilir

Yer değiştirmenin iki tarafı da yukarıdaki örneklerin düşündürdüğünden geniştir. Parametre çıplak bir alanla sınırlı değildir: her bileşik pozisyona yerleşir, yani tek bir bildirim aynı tipin array, map, nullable, tuple ve ham JSON biçimlerinin hepsini kapsar.

schema LineItem {
  sku: string
}

schema Multi<T> {
  one: T
  many: T[]
  lookup: map<T>
  maybe: T | null
  pair: [T, string]
  raw: json<T>
}

schema Catalogue {
  rows: Multi<LineItem>
}

Argümanın da bir schema adı olması gerekmez. Tip gramerinin yazabildiği her şey verilebilir; her biri argümanın kendi yazılı biçiminden kurulan bir adla açılır:

Type parameter yalnızca schema'ya ait bir yapıdır. Başka bir blok üzerine yazmak generic bir agent ya da generic bir fonksiyon vermez.

import "./base.luma"      // Taban, Ek, Zarf<T>

schema Birlesik = Taban + Ek        // composition
schema Kullanim = Zarf<Ic>          // generic alias
schema Sonuc { kutu: Zarf<Ic> }     // generic alan tipi

Error: Schema definition 'schema K = …' matches no known form: use 'A + B' composition, 'A | B tagged by field' union, or a 'Template<Args>' generic alias.

Error: Unknown type argument schema 'Missing' for generic 'Page'.
Error: Generic schema cycle found: Tree<int> -> Tree<int>.
Error: Tagged unions cannot use generic schema members: Document.
Error: Tagged union 'Document' must contain at least two members.

Error: 'Page' variable is not defined yet.

Union ve nullable

note: string | null
value: int | float | null
flexible: string | int

Union, | ile yazılır ve JSON Schema'da anyOf üretir. Doğrulama sırasında üyeler sırayla denenir; hiçbiri tutmazsa tüm alt hatalar birleştirilerek raporlanır:

Customer.tax_id does not match any union type: Customer.tax_id must be a string. | Customer.tax_id must be null.

Etiketli union — tagged by

Bir alan tipinin içine yazılan |, etiketsiz bir union'dır. = ve tagged by ile tanımlanan schema ise başka bir şeydir: bir sum type. Değer üyelerden biridir ya da diğeridir; hangisi olduğunu bir etiket alanı söyler.

schema Invoice {
  date: string
  total: float
  invoice_number?: string
}

schema Receipt {
  date: string
  total: float
  reference?: string
}

schema Document = Invoice | Receipt tagged by kind

Tanım tek satırdır, gövdesi yoktur ve en az iki üye ister; üyelerin hepsi önceden tanımlı schema olmalıdır — tanınmayan bir üyede parser Tagged union 'Document' member schema 'Voucher' was not found. diyerek durur. Bu noktadan sonra iki yazım tamamen farklı kurallarla çözümlenir:

Etiket alanı enjekte edilir, yazılmaz

tagged by kind, her üyeye kind alanını ekler ve bu alanın değeri o üyenin schema adıdır: "Invoice", "Receipt". Alanı sen hiç yazmazsın ve üyeler değişmez — Invoice tek başına, alan tipi, parametre ya da ask çıktısı olarak kullanıldığında yine tam olarak kendi tanımladığı alanlara sahiptir, aralarında kind yoktur.

Etiket enjekte edildiği için, onu bir de üyenin tanımlaması çakışmadır; parser tüm programı reddeder:

Error: Tagged union 'Document' discriminator 'kind' conflicts with member schema 'Invoice'.

Etiketin okunması

Etiket her şeyden önce okunur. Tek bir üyeyi seçer ve değerin kalanı yalnızca o üyeye göre doğrulanır; böylece bütün üyeler otururken bile seçilen dal deterministiktir:

agent Router {
  fn route(document: Document) -> Result {
    match document {
      case Invoice invoice { return { branch: "Invoice" } }
      case Receipt receipt { return { branch: "Receipt" } }
    }
  }
}

router = Router()
out = router.route({ kind: "Receipt", date: "2026-02-01", total: 42.0 })

Etiketi olmayan — ya da string olmayan — bir değer hiçbir üyeye ulaşamaz; etiketi union dışındaki bir schema'yı adlandıran değer de öyle:

Router.route.document.kind must identify a tagged union member.
Router.route.document.kind has unknown tagged union member 'Voucher'.

Baştaki ön ek, doğrulanan değerin yoludur; burada Router.route metodunun document parametresi.

Opsiyonel / nullable matrisi

Bu tablo Luma'da en sık karıştırılan ayrımdır:

// The preferred pattern in invoice extraction:
invoice_number: string | null @desc("Fatura numarası")
due_date: string | null @desc("Son ödeme tarihi")
items: InvoiceItem[] @desc("Tüm kalemler; yoksa boş liste")

Array ve null

Nullable bir array'e uygulanan @minItems, @unique gibi koleksiyon annotation'ları yalnızca değer gerçekten array olduğunda çalışır; değer null ise atlanır.

Boyut ve aralık kısayolları

schema Answer {
  title: string
  paragraphs: string[2]           // exactly two paragraphs
  people: Person[1..3]        // 1-3 people
  scores: float[1..3] [0..100]
  confidence: float [0..1]        // a single number between 0 and 1
}

JSON Schema eşlemesi

Aşağıdaki schema ve onun ürettiği gerçek JSON Schema çıktısı, schema.toJsonSchema(...) ile alınmıştır:

schema Address {
  city: string
}

schema Customer @desc("Fatura müşterisi") {
  name: string @length(2, 40) @title("Ad Soyad") @example("Ayşe Yılmaz")
  tax_id: string | null @length(10) @desc("Vergi kimlik numarası")
  email?: string @fmt("email") @alias("e_mail")
  score: float [0..100]
  tags: string[] @minItems(1) @unique @contains("vip")
  kind: enum["individual", "company"]
  metrics: map<float>
  address: Address
  active: bool @default(true)

  where score >= 0
  when kind == "company" require [tax_id]
}

{
  "type": "object",
  "description": "Fatura müşterisi",
  "properties": {
    "name": { "type": "string", "minLength": 2, "maxLength": 40,
              "examples": ["Ayşe Yılmaz"], "title": "Ad Soyad" },
    "tax_id": { "anyOf": [ { "type": "string", "minLength": 10, "maxLength": 10 },
                           { "type": "null" } ],
                "description": "Vergi kimlik numarası" },
    "email": { "type": "string", "format": "email",
               "x-luma-aliases": ["e_mail"] },
    "score": { "type": "number", "minimum": 0, "maximum": 100 },
    "tags": { "type": "array", "items": { "type": "string" },
              "minItems": 1, "uniqueItems": true,
              "contains": { "const": "vip" } },
    "kind": { "type": "string", "enum": ["individual", "company"] },
    "metrics": { "type": "object", "additionalProperties": { "type": "number" } },
    "address": { "$ref": "#/$defs/Address" },
    "active": { "type": "boolean", "default": true }
  },
  "required": ["name", "tax_id", "score", "tags", "kind", "metrics", "address"],
  "additionalProperties": false,
  "allOf": [
    { "if":   { "properties": { "kind": { "const": "company" } } },
      "then": { "allOf": [ { "required": ["tax_id"] } ] } }
  ],
  "x-luma-where": [ { "expression": "score >= 0" } ],
  "x-luma-conditionals": [ … ]
}

Dikkat edilecek noktalar

• @length(10) tek argümanla verildiğinde hem minLength hem maxLength 10 olur — yani tam olarak 10 karakter.
• Union alanında annotation'lar ilgili branch'e uygulanır: uzunluk kısıtı string branch'ine gider, null branch'i dokunulmadan kalır.
• @default ve ? alanı required dışında bırakır.
• Kök nesne her zaman additionalProperties: false içerir — model schema dışı alan üretemez.
• where ve koşullu kurallar x-luma-* uzantılarıyla taşınır; bunlar gateway tarafından yok sayılır, doğrulamayı Luma yerel olarak yapar.

JSON Schema'da etiketli union

Her üye anyOf içinde eksiksiz yayılır, etiket her birinde bir const'a sabitlenir ve o üyenin required listesine katılır. Ayırt etme işini yapan da o const'tur: bir belge Receipt'tir çünkü orada kind yalnızca "Receipt" olabilir. Aşağıdaki, yukarıdaki Document union'ının gerçek çıktısıdır:

{
  "anyOf": [
    { "type": "object",
      "properties": {
        "date": { "type": "string" },
        "total": { "type": "number" },
        "invoice_number": { "type": "string" },
        "kind": { "type": "string", "const": "Invoice" }
      },
      "required": ["date", "total", "kind"],
      "additionalProperties": false },
    { "type": "object",
      "properties": {
        "date": { "type": "string" },
        "total": { "type": "number" },
        "reference": { "type": "string" },
        "kind": { "type": "string", "const": "Receipt" }
      },
      "required": ["date", "total", "kind"],
      "additionalProperties": false }
  ]
}

Etiketsiz yazımda bunların hiçbiri yoktur. doc: Invoice | Receipt alanı düz bir referans listesine dönüşür ve schema'da hangi üyenin kastedildiğini gateway'e — ya da bir doğrulayıcıya — söyleyen hiçbir şey kalmaz:

"doc": { "anyOf": [ { "$ref": "#/$defs/Invoice" }, { "$ref": "#/$defs/Receipt" } ] }

JSON Schema'da parametrik schema

Görülecek özel bir şey yok; parse zamanında açmanın bütün amacı da bu. Aşağıdaki, çıktı tipi Page<LineItem> olan bir ask için giden gerçek istek gövdesi; modelin eline dar bir object schema geçiyor ve ortada bir parametre yazıldığını hiç öğrenmiyor:

{
  "type": "object",
  "properties": {
    "items": { "type": "array", "items": { "$ref": "#/$defs/LineItem" } },
    "total": { "type": "integer" }
  },
  "required": ["items", "total"],
  "additionalProperties": false,
  "$defs": {
    "Page_LineItem": {
      "type": "object",
      "properties": {
        "items": { "type": "array", "items": { "$ref": "#/$defs/LineItem" } },
        "total": { "type": "integer" }
      },
      "required": ["items", "total"],
      "additionalProperties": false
    },
    "LineItem": {
      "type": "object",
      "properties": {
        "sku": { "type": "string" },
        "amount": { "type": "number" }
      },
      "required": ["sku", "amount"],
      "additionalProperties": false
    }
  }
}

$defs yalnızca bu kök schema'nın eriştiklerini taşır: açılımın kendisi ve onun başvurduğu LineItem. Aynı programda başka bir yerde, hiçbir isteğin uğramadığı bir yolda duran Page<Customer> gövdede yoktur — bir açılım, erişilebilir bir şey ona işaret etmedikçe istek maliyeti değildir. Parametrik schema'ların $defs budaması inene kadar bekletilmesinin sebebi buydu: budama olmadan tek bir sarmalayıcı, ödeme yapılan her çağrıda payload tipi sayısı kadar çoğalırdı.

Tam eşleme tablosu

Hangi tipi ne zaman?

schema Record {
  id: string
  amount: float | null
  status: enum["open", "closed"]
  items: LineItem[]
  meta: MetaEntry[]
}

schema Record {
  id: any             // no validation
  amount: float           // no "not found" path
  status: string          // free text
  items?: LineItem[]      // the model may skip it
  meta: map<any>        // may be rejected in strict mode
}

Query satırı için tip seçmek

v0.4.0'dan beri aynı tip sözlüğü, hiçbir modelin üretmediği veriyi de tipler. Bir query Schema[] döndürür ve onu satır satır doğrular; bir parallel over her eleman sonucunu bildirilen eleman schema'sına göre doğrular. İkisi de düşen pozisyonu adlandırır — Orders.row[0].amount must be a number., classified[2].band must be one of these values: … — yani yukarıdaki tablo hâlâ geçerlidir, ama arkasındaki muhakeme değişir.

Model çıktısı tipi bir pazarlıktır: modelin ne söyleyebileceğini şekillendirirsin ve her tercih, katılığı modelin uyum sağlayabilmesiyle takas eder. Satır tipi ise bir tariftir: şekil zaten tablo tarafından sabitlenmiştir, seninle pazarlık eden kimse yoktur ve tek soru bildirimin köprünün geri verdiğiyle örtüşüp örtüşmediğidir. Girişte hiçbir şey dönüştürülmez — bildirilen tip, sürücünün ürettiği JS değerine karşı kontrol edilir — dolayısıyla Date olarak gelen bir kolon string'i karşılamaz ve çözüm daha gevşek bir tip değil, SQL ya da köprüdür.