Schema & Validation

Schema tanımı

schema Invoice {
  invoice_number: string
  total: float
}

Alanlar satır başına bir tane yazılır. Sondaki virgül isteğe bağlıdır; alanları aynı satıra koymak sözdizimi hatasıdır.

Schema seviyesi metadata

schema Invoice
  @desc("Satış faturası")
  @prompt("Fatura alanlarını eksiksiz çıkar; bulunmayanları null yap.") {
  invoice_number: string
  total: float
}

@prompt nasıl kullanılır

import schema from "std/schema"

schema InvoiceExtract
  @desc("Fatura Markdown'ından çıkarılan yapılandırılmış veri")
  @prompt("Aşağıdaki Markdown'dan InvoiceExtract schema'sına uygun JSON üret. Alan açıklamalarını extraction talimatı olarak kullan. Bulunmayan değerleri uydurma; nullable alanlarda null, array alanlarda [] kullan.") {
  invoice_number: string | null
  items: InvoiceItem[]
}

agent Extractor {
  fn extract(markdown: string) -> InvoiceExtract {
    instruction = schema.prompt(InvoiceExtract)
    result = ask "{instruction}\n\nFATURA MARKDOWN:\n{markdown}" -> InvoiceExtract
    return result
  }
}

Bu ayrım bilinçlidir: extraction talimatı schema ile birlikte versiyonlanır ama prompt'un hangi noktasına gireceğine sen karar verirsin.

Field annotation referansı

Alan annotation'ları alan tanımının arkasına yazılır ve zincirlenebilir. Uzun zincirler @ ile başlayan devam satırlarına bölünebilir.

Sık karıştırılan üç ayrım

1. Değer aralığı ≠ liste uzunluğu

2. @contains array içindir

tags: string[] @contains("vip")
numbers: int[] @contains(2)

// To search for a substring in a scalar string:
name: string @valid(x => contains(x, "Ayşe"))

// @contains cannot be used on a scalar
// string — the parser rejects it:
name: string @contains("Ayşe")
// @contains usage: @contains(value)

3. @length(n) tam uzunluktur

tax_id: string @length(10)      // exactly 10 characters (minLength = maxLength = 10)
name: string @length(2, 40)   // between 2 and 40 characters

@fmt değerleri

@valid

@valid deterministik bir lambda alır: @valid(x => expression). Desteklenen biçimler:

// ✓ correct
code: string | null
  @valid(x => x == null || regex.matches(x, "^[A-Z]{3}-[0-9]+$"))

// ✗ blows up when null arrives
code: string | null @valid(x => regex.matches(x, "^[A-Z]{3}-[0-9]+$"))

@alias ve @default

schema Profile {
  email: string @title("E-posta") @example("ada@example.com") @alias("e_mail") @alias("mail")
  active: bool   @default(true)
  old_code?: string @deprecated("Yerine new_code kullanılmalı")
}

• Gelen veride e_mail varsa değer email'e taşınır ve alias anahtarı silinir.
• Hem kanonik ad hem alias birlikte gelirse hata: Profile.email cannot be given by its canonical name and an alias at the same time.
• Birden fazla alias birlikte gelirse hata: Profile.email was given more than one alias: e_mail, mail
• Bir alias, schema'daki gerçek bir alanın adı olamaz ve iki alan aynı alias'ı paylaşamaz.
• @default ile doldurulan değer sonrasında normal tip doğrulamasından geçer.

Otomatik doğrulamalar

Hiçbir annotation yazmasan bile aşağıdaki kontroller her schema için çalışır:

Özel alan: sources

sources: string[] adında bir alan tanımlarsan, içindeki her değerin programda tanımlı bir context kimliği olması zorunlu tutulur. Bu, modelin kaynak uydurmasını engellemenin doğrudan yoludur.

context contract = file("docs/contract.md")
context spec     = file("docs/spec.md")

schema Answer {
  summary: string
  sources: string[1..3]     // only "contract" or "spec" is allowed
  confidence: float [0..1]
}

input document: file ile verilen dosyalar da context kimliği sayılır.

Hatalar toplanarak raporlanır

Bir doğrulama turunda bulunan tüm hatalar biriktirilip tek seferde bildirilir — böylece model retry'da hepsini birden düzeltebilir:

Error: A.f.v.name must be at least 2 characters.
A.f.v.age must be an integer.
A.f.v.email must be in email format.
A.f.v.tags must contain unique items.
A.f.v.score must be at most 100.
A.f.v.role must be one of these values: admin, user.
A.f.v.extra is not defined in the schema.

@feedback ile mesajları özelleştirme

Varsayılan hata mesajları modele geri gönderilir. Modelin ne yapması gerektiğini daha net anlatmak istediğinde @feedback kullan.

schema Order {
  subtotal: float
  tax: float
  total: float @feedback("Toplam, ara toplam ile KDV'nin tam toplamı olmalı")

  where total == subtotal + tax @feedback("total == subtotal + tax sağlanmıyor")
}

Error: A.f.v: total == subtotal + tax sağlanmıyor

Error: BadRows.row[0]: total must equal subtotal + tax

where — deterministik invariant'lar

where, alanlar arasındaki ilişkiyi doğrular. Tek bir alanın kendi kısıtı için annotation, alanlar arası tutarlılık için where kullanılır.

pure fn totalAmount(items: LineItem[]) -> float {
  total = reduce item in items with 0 => acc + item.amount
  return total
}

schema Invoice {
  items: LineItem[1..100]
  total_amount: float

  where totalAmount(items) == total_amount @feedback("Kalem toplamı fatura toplamıyla eşleşmeli")
}

Kayan nokta karşılaştırması

import num from "std/numeric"

schema LineItem {
  quantity: float
  unit_price: float
  total: float

  where num.approximatelyEqual(quantity * unit_price, total, 0.01)
}

schema LineItem {
  quantity: float
  unit_price: float
  total: float

  // 0.1 * 3 == 0.30000000000000004
  where quantity * unit_price == total
}

where quantity == null || unit_price == null
   || num.approximatelyEqual(quantity * unit_price, total, 0.01)
  @feedback("a * b toplamına uymuyor")

pure fn lineItemConsistent(quantity: float | null, unit_price: float | null, total: float | null) -> bool {
  if quantity == null {
    return true
  }
  if unit_price == null {
    return true
  }
  if total == null {
    return true
  }
  return num.approximatelyEqual(quantity * unit_price, total, 0.01)
}

schema LineItem {
  quantity: float | null
  unit_price: float | null
  total: float | null

  where lineItemConsistent(quantity, unit_price, total)
}

Nullable alanlarla where

schema InvoiceItem {
  quantity: float | null
  unit_price: float | null
  total: float | null

  where quantity == null || unit_price == null || total == null || num.approximatelyEqual(quantity * unit_price, total, 0.01)
    @feedback("quantity * unit_price toplamına uymuyor")
}

Nullable alanlar için önce "veri yoksa geç" koşullarını yazıp sonra asıl invariant'ı ekle. || soldan sağa kısa devre yapar. @feedback alt satıra alınabilir; where'in kendisi alınamaz.

@severity — üçüncü durum

v0.8.0'a kadar doğrulanmış bir değer iki durumdan birindeydi: ya schema'yı karşılıyordu ya da koşu duruyordu. @severity("warn") üçüncüsünü ekliyor — geçerli ama şerhli. Değer kabul ediliyor, koşu devam ediyor; kuralın bulduğu şey değerle birlikte bir finding olarak yol alıyor.

Varsayılan error, yani @severity geçmeyen bir schema tam olarak eskisi gibi davranır. Küme kapalı: error ve warn, başka değer yok. Kendi tier sözlüğün — review, reject, sayısal bir skor — kuralda değil, finding'leri okuyan kodda yaşar.

Nereye yazılır

Alanda @severity, ardından geldiği @valid kuralını niteler; where satırında o invariant'ı niteler. Yalnızca bu iki yer geçerli ve ikisi de parse zamanında denetlenir.

schema Scored {
  // kural koşuyu durdurmadan düşebilir
  score: int @valid(x => x >= 0) @severity("warn")

  // iki kural, yalnızca ikincisi soft
  ratio: float @valid(x => x <= 1) @valid(x => x > 0) @severity("warn")
}

schema Line {
  qty: int
  total: int

  where total == qty * 5 @severity("warn")
}

Sonuçlarda onurlandırılır, girdilerde yok sayılır

Aynı schema bir yerde modelin cevabını, başka bir yerde bir tool'un argümanını tarif edebilir. Severity yalnızca schema'nın bir özelliği değildir — değerin bir sınırın hangi tarafında denetlendiğine bağlıdır.

Sebep, bu iki yolun kurduğu cümlenin farkı. Şerhli bir sonuç "bu veri şüpheli, sebebi de bu" der — ne yapılacağına program karar verir. Şerhli bir girdi ise "senin yan etkili kodunu, sözleşmesini ihlal ettiğini bildiğimiz veriyle çağırıyoruz" derdi; bu, Luma'nın kurallarını kapatmaya harcadığı sessiz bozulma sınıfının ta kendisi.

Error: Sink.take.s.score does not satisfy its @valid rule: x => x >= 0

ask yolunda soft kural da retry hakkı alır

Soft ihlal bir omuz silkme değildir. ask yolunda tıpkı sert bir ihlal gibi retry döngüsüne girer: düşen kurallar yollarıyla birlikte modele geri söylenir ve model düzeltme şansını alır. İlk sekiz mesaj alıntılanır, kalanı sayılır ((+3 more)).

Fark yalnızca sondadır. Denemeler tükendiğinde sert ihlal koşuyu durdurur, soft ihlal durdurmaz: son değer kabul edilir ve finding, kabul edildiği deneme numarasını kaydeder. Retry yalnızca beslenecek bir modelin olduğu yerde vardır — diğer sonuç yollarında soft ihlal doğrudan "kabul edildi ve şerhlendi"ye düşer. Bu, @feedback'in zaten taşıdığı asimetrinin aynısıdır.

Finding'leri okumak

Şerhin programa ulaşma yolu std/findings. İki fonksiyon da şerhli değeri alır ve pure değil, io'dur:

import findings from "std/findings"

schema Scored {
  score: int @valid(x => x >= 0) @severity("warn")
}

schema Audit {
  score: int
  flaws: int
  first_rule: string
}

agent Maker {
  fn make(value: int) -> Scored {
    return { score: value }
  }
}

agent Auditor {
  uses maker: Maker

  fn audit() -> Audit {
    shaded = maker.make(-7)
    flaws = findings.of(shaded)
    return { score: shaded.score, flaws: length(flaws), first_rule: flaws[0].rule }
  }
}

Error: findings is io and cannot be used inside @valid or where rules: findings.count

Finding'ler operasyon başına yaşar. parallel over altında her eleman kendisininkini toplar ve sonuçlar girdi sırasında birleşir; böylece bir şerh asla yanlış satıra düşmez.

Şerhli değeri onu inceleyen bir şeye vermek

Şerhli bir değer, soft kuralını ihlal ettiği şema ile tiplenmiş bir parametreden geçemez. Bu bilinçli, ama gerçek bir soru bırakıyor: işi şerhli değerlere bakmak olan yardımcıyı nasıl yazacaksın? Parametreyi any tiplemek çalışır ve şerh geçişte korunur — ama diğer bütün alanların tip kontrolünü de bırakır.

Tipli yol, sınırın gerçekte neyi kabul ettiğini söylemek: aynı şekle sahip, sert kuralları koruyan ve yalnızca incelenen soft kuralı dışarıda bırakan bir aday şema.

schema Document {
  amount: int @valid(x => x >= 0) @severity("warn")
  name: string @length(2, 40)
}

// Aynı şekil. @length duruyor; incelenen kural dışarıda.
schema DocumentCandidate {
  amount: int
  name: string @length(2, 40)
}

agent Reviewer {
  fn review(doc: DocumentCandidate) -> Report {
    flaws = findings.of(doc)
    return { amount: doc.amount, flaws: length(flaws), rule: flaws[0].rule }
  }
}

Değer geçer, findings.of şerhlerini vermeye devam eder, ve doc.amount ile doc.name tipli kalır — @length o sınırda hâlâ dayatılır. Vazgeçtiğin şey tam olarak tek bir kuraldır, yazılı olarak, önemli olduğu yerde.

r = reviewer.review(doc)   // böyle
return { amount: r.amount }

return reviewer.review(doc)   // böyle değil

Kimsenin okumadığı şerh de duyurulur

Okumak isteğe bağlı olduğu için, okunmamış bir finding sessizce kabul edilmiş bir değer demektir — @severity'nin yapmasına yalnızca görünür olduğu için izin verilen şeyin tam tersi. Bu yüzden koşu susmaz. Finding üretilip hiç okunmadıysa koşu, üreten her operasyonu ve sayısını adlandıran bir uyarıyla standart hataya biter:

Warning: 1 finding accepted but never read: Maker.make.return (1). Read them with findings.of(...) from std/findings.

Bu bir uyarıdır, hata değil: çıkış kodu 0 kalır, çünkü koşuyu durdurmak özelliğin amacını bozardı. Finding'leri oku, koşu sessizleşir. Bu, çıplak çağrı satırının yaptığı pazarlığın aynısıdır — dil izin verir ve bu konuda susmayı reddeder.

Tavan

İki yüz bin satır dönen bir query, kural sayısıyla çarpıldığında finding'leri sınırsız biriktirebilirdi. Bu yüzden operasyon başına 1000'lik bir tavan var. Sonrasında ihlaller saklanmak yerine sayılır ve findings.capped adlı bir işaret kaydı kaç tanesinin kesildiğini tam olarak söyler:

Findings cap reached (1000); 412 more soft violations were not recorded.

Ne sınırsız büyür ne de izsiz küçülür — sayı her zaman kayıttadır.

when — koşullu kurallar

when, bir discriminator alanına göre başka alanları zorunlu veya yasak yapar. Bu bir workflow if'i değildir — schema doğrulaması ve JSON Schema üretimi içindir.

where kind != "calc" || amount != null
  @feedback("calc işleminde amount zorunludur")

schema Operation {
  kind: enum["calc", "text"]
  calc?: CalcInput
  text?: string

  when kind == "calc" require [calc] forbid [text]
    @feedback("Calc işleminde calc alanı zorunludur")

  when kind == "text" require [text] forbid [calc]
    @feedback("Text işleminde text alanı zorunludur")
}

else when / else zincirleri

schema Envelope {
  payload: Payload

  when payload.kind == "calc" require [payload.calc] forbid [payload.text]
    @feedback("Calc payload'ında calc alanı zorunludur")
  else when payload.kind == "text" require [payload.text] forbid [payload.calc]
  else require [payload.text]
    @feedback("Diğer payload türlerinde text alanı zorunludur")
}

• when yeni bir grup başlatır; else when ve else önceki gruba katılır.
• Bir grupta ilk eşleşen dal uygulanır; hiçbiri eşleşmezse else dalı çalışır.
• Nokta ile nested alan yolu kullanılabilir: payload.calc.
• Bir else, öncesinde when olmadan yazılamaz.
• Kurallarda geçen tüm alan adları schema'da mevcut olmalıdır, yoksa parse hatası alınır.

Koşullu default'lar

schema Operation {
  kind: enum["calc", "text", "other"]
  currency?: string
  description?: string

  when kind == "calc" default [currency = "TRY"]
  else when kind == "text" default [currency = "TEXT", description = "Metin işlemi"]
  else default [currency = "GENEL"]
}

Koşullu default yalnızca alan eksikse uygulanır; mevcut değer ezilmez. Doldurulan değer sonrasında normal tip doğrulamasından geçer. Default'lar, zorunluluk kontrollerinden önce çalışır.

JSON Schema'ya yansıması

Koşul field == constant biçimindeyse JSON Schema if/then/else yapısı üretilir:

"allOf": [
  { "if":   { "properties": { "kind": { "const": "company" } } },
    "then": { "allOf": [ { "required": ["tax_id"] } ] } }
]

when mi, tagged union mı?

Yukarıdaki her şey tek bir schema'nın içindeki koşullu zorunluluğu anlatır: başka bir alan belirli bir değeri taşıdığı için zorunlu, yasak ya da önceden dolu hale gelen alan. when bunun içindir ve bu iş için doğru araç olmayı sürdürür.

Aynı kurallar ikinci ve epeyce farklı bir işi de taşıyordu: "bu nesne şu şekillerden tam olarak biri" demeyi — bir kind enum'ı, şekil başına bir dal alanı, dal başına bir require/forbid çifti. Artık bu işin kendi deklarasyonu var:

schema Invoice {
  invoice_number: string
}

schema Receipt {
  reference: string
}

schema Document = Invoice | Receipt tagged by kind

Fark biçimsel değil. Zarfta dışlayıcılık senin yazdığın bir invariant'tır: bir dalın when kuralını unut, iki dalı birden taşıyan nesne sorunsuzca doğrulanır — eksik kuralı gösteren hiçbir şey yoktur. Tagged union bu biçimde yanlış olamaz, çünkü dışlayıcılık tipin kendisidir: değer tek bir üyeyi ve etiketini taşır, onu tüketen match ise her üyeyi adlandırmak zorundadır. Birini atlarsan program hiç çalışmaz — parse sırasında Match for tagged union 'Document' must handle member 'Receipt'. ile reddedilir.

Buradan hiçbir şey eksilmiyor. Zarf eskisi gibi doğrulanır ve dallar kendi başına birer schema değilse ya da dalın yanında başka alanlar duracaksa hâlâ doğru cevaptır; union üyesi de kendi where, when ve annotation'larını korur, bir Document Invoice olarak geldiğinde bunlar tam güçte çalışır. Deklarasyonun kendisi, match ve etiketin ne tuttuğu için → Tip Sistemi · Etiketli union.

Schema composition

schema User {
  id: string
  email: string @fmt("email")
}

schema AuditFields {
  created_at: string @fmt("date-time")
  created_by: string
}

schema Admin = User + AuditFields

Her payload'a tek sarmalayıcı

Composition, ikisi de zaten var olan iki schema'yı birleştirir. Yeniden kullanım probleminin öbür yarısı, payload'ı değişirken biçimi tekrar eden schema'dır — Page, Result, Envelope. Elle yazıldığında bu, payload tipi başına bir kopya demektir:

schema LineItem {
  sku: string
}

schema Customer {
  name: string
}

schema Page<T> {
  items: T[]
  total: int
  next_cursor: string | null
}

schema Report {
  lines: Page<LineItem>
  customers: Page<Customer>
}

schema LineItemPage {
  items: LineItem[]
  total: int
  next_cursor: string | null
}

schema CustomerPage {
  items: Customer[]
  total: int
  // next_cursor was added on the left only
}

Bugün iki taraf da aynı değerleri doğruluyor. Fark, next_cursor'ın eklendiği gün ortaya çıkar: solda tek hamlede bütün payload'lara iner, sağda düzenlemeyi yapan kişinin aklına geldiği yerlere iner. Atlanan kopyayı kimse bildirmez, çünkü ortada bozuk bir şey yoktur — CustomerPage gayet geçerli bir schema'dır, yalnızca olması gereken sarmalayıcıdan başka bir schema'dır. Kayma dediğimiz şey budur ve onu baştan imkânsız kılan tek şey tanımın tek olmasıdır.

Doğrulama sırası

Bir nesne doğrulanırken adımlar tam olarak şu sırayla çalışır. Sıra önemlidir: örneğin default'lar zorunluluk kontrolünden önce dolar, where ise en sona kalır çünkü tüm alanların geçerli olduğunu varsayar.

Bu sıraya üç giriş noktası vardır ve hepsi aynı adımları çalıştırır; yani aşağıdaki her kural — annotation'lar, when, where, composition — modele hiç değmemiş veri için de aynen geçerlidir. Yalnızca hata yolu öneki değişir:

  1  alias çözümleme      alias → kanonik ad taşıma
  2  @default doldurma     eksik alanlara sabit değer
  3  koşullu default'lar   when/else default [ … ]
       │
  4  her alan için
       ├─ alias çakışma kontrolü
       ├─ zorunluluk kontrolü        "X.y missing."
       ├─ tip doğrulaması            (nested schema'lar özyinelemeli)
       ├─ sources context kontrolü (alan adı "sources" ise)
       ├─ koleksiyon kuralları       minItems · maxItems · unique · uniqueBy · contains
       ├─ değer kuralları            fmt · length · match · range  (her eleman için)
       └─ @valid ifadeleri           null değerlerde de çalışır
       │
  5  bilinmeyen alan kontrolü  "X.k is not defined in the schema."
  6  when require / forbid     grup içinde ilk eşleşen dal
  7  where invariant'ları
       ↓
  tüm hatalar birleştirilip tek seferde raporlanır

Schema reflection

Schema'lar compile-time tanımlardır; runtime'da değiştirilemezler. Ancak std/schema ile deterministik olarak okunabilirler — prompt üretmek, katalog çıkarmak veya JSON Schema'yı dışa aktarmak için:

import schema from "std/schema"

name        = schema.name(Invoice)                 // "Invoice"
description = schema.description(Invoice)          // the @desc text or null
instruction = schema.prompt(Invoice)               // the @prompt text or null
fields      = schema.fields(Invoice)               // field descriptors
field       = schema.field(Invoice, "invoice_number")
var         = schema.hasField(Invoice, "seller.name")
rules       = schema.rules(Invoice)                // where + conditional rules
parts       = schema.components(Admin)             // ["User", "AuditFields"]
catalog     = schema.catalog([Invoice, Receipt])
js          = schema.toJsonSchema(Invoice)

Tam imza listesi ve dönüş şekilleri için → Standard Library · std/schema.

schema Invoice {
  invoice_number: string
}

schema Receipt {
  reference: string
}

schema Document = Invoice | Receipt tagged by kind

agent Extractor {
  fn extract(kind: string, text: string) -> Document {
    switch kind {
      case "Invoice" { ask "Fatura alanlarını çıkar:\n{text}" -> Invoice }
      default { ask "Dekont alanlarını çıkar:\n{text}" -> Receipt }
    }
  }
}