joetjen.net
EN DE
Datenformat

Schemas

Ein .dxns-Schema ist ein gewöhnliches DXN-Dokument: eine Map von Namen auf Struct-Schemas, Shapes und benannte Typen. Es sagt einem Leser, wie die Felder eines Structs heißen, in welcher Reihenfolge sie stehen, was sie enthalten dürfen, welche fehlen dürfen — und welche Version des Schemas es ist. Die Schemasprache heißt DXNS.

Format 1.0

Ein Schema-Dokument

customer.dxns
%{
  Percentage: {:refine :float %{min: 0.0, max: 100.0}}
  Tag:        {:refine :string %{min-length: 1, max-length: 20}}

  Address: %schema{
    street: :string
    city:   :string
    zip?:   :string
  }

  Customer: %schema{
    name:    :string
    address: Address
    loyalty: Percentage
    tags?:   {:list-of Tag}
  }
}

Address und Customer sind Struct-Schemas. Percentage und Tag sind benannte Typen — wiederverwendbare Namen für einen Typausdruck, auf die man genau wie auf einen Struct-Namen verweist.

Gelesen mit geladenem customer.dxns
%Customer{name: "Ada", address: %Address{street: "1 Main St", city: "Springfield"}, loyalty: 12.5}
%Customer(1){name:"Ada",address:%Address(1){street:"1 Main St",city:"Springfield"},loyalty:12.5}

Typformen

Ein nacktes Keyword nennt einen Typ: eines pro DXN-Typ, :integer, :string, :datetime, :objectid und so weiter, dazu :any für jeden Wert und :never für keinen. :bits nimmt Bits und Bytes, :bytes nur ganze Bytes. Einige weitere Keywords sind Kurzformen: :int32, :int64, :uint32 und :uint64 für Ganzzahlen in diesem Bereich, :float32 für eine Gleitkommazahl, die einfache Genauigkeit exakt hält, :number für jede Zahl und :timestamp für einen Zeitpunkt in UTC. Alles andere ist ein Tupel oder ein Struct:

FormPasst auf
Address, ns/Nameein Struct-Schema, eine Shape oder einen benannten Typ, per Name
{:list-of T}, {:set-of T}, {:sorted-set-of T}, {:array-of T}diese Sammlung, jedes Element ein T
{:list-items A {:repeat B 0 nil}}eine Liste Element für Element: ein A, dann beliebig viele B — siehe unten
{:tuple-of A B C}ein Tupel aus genau diesen Plätzen
{:tuple-of-all T}ein Tupel beliebiger Länge, jedes Element ein T
{:map-of K V}, {:ordered-map-of K V}jeder Schlüssel ein K, jeder Wert ein V
{:enum a b …}, {:const v}eines der angegebenen Literale; genau v
{:one-of A B}genau eine Variante passt — keine oder zwei sind eine Ablehnung
{:any-of A B}, {:all-of A B}eine oder mehrere Varianten; jede Variante
{:not T}alles, was kein T ist
{:nilable T}nil oder T, kurz für {:any-of :nil T}
{:if I T E}ein Wert, der ein I ist, muss ein T sein, jeder andere ein E
{:refine T %{…}}ein T, das die Einschränkungen erfüllt — siehe unten
{:tagged acme.money T}das eigene Tag @acme.money um ein T
{:case field %{v => T, :else => U}}der Typ, den der Wert eines Nachbarfelds wählt — siehe Shapes
{:doc T %{description: "…"}}ein T mit Anmerkungen — Titel, Beschreibung, Beispiele, Abkündigung oder freie Metadaten; ändert nichts daran, was es nimmt
{:generic [t] body}, {:of Name T}ein benannter Typ mit Parametern und eine Verwendung davon — siehe benannte Typen
%shape{…}eine einfache Map mit diesen Feldern
%schema(N){…}ein Struct-Schema, Version N

{:list-items …} beschreibt eine Liste der Reihe nach. Jeder Teil ist ein Typ für ein Element, {:repeat T min max} für zwischen min und max Elemente — max nil für keine Grenze — oder {:repeat {:group A B} min max} für mehrere Elemente zusammen. Die Liste passt, wenn jedes Element aufgenommen ist. Ein Repeat nimmt so viele Elemente, wie er kann, und gibt sie einzeln zurück, sodass jede Implementierung dieselben Entscheidungen trifft.

job.dxns
%{
  Job: %schema{
    id:      {:any-of :integer :uuid}
    retries: {:one-of {:refine :integer %{max: 3}} {:refine :integer %{min: 2}}}
    command: {:list-items :string {:repeat :string 0 nil}}
    tags:    {:refine {:list-of :string} %{unique: true, min-count: 1}}
    host?:   {:not {:enum "localhost"}}
  }
}
Gelesen mit geladenem job.dxns
%Job{id: 7, retries: 1, command: ["ls" "-l"], tags: ["a"]}
%Job{id: 7, retries: 3, command: ["ls"], tags: ["a"]}
%Job{id: 7, retries: 1, command: [], tags: ["a"]}
%Job{id: 7, retries: 1, command: ["ls"], tags: ["a" "a"]}
%Job{id: 7, retries: 1, command: ["ls"], tags: ["a"], host: "localhost"}
%Job{id: "7", retries: 1, command: ["ls"], tags: ["a"]}
%Job(1){id:7,retries:1,command:["ls" "-l"],tags:["a"]}
schema/type-mismatch: field "retries" does not match its declared type
schema/type-mismatch: field "command" does not match its declared type
schema/type-mismatch: field "tags" does not match its declared type
schema/type-mismatch: field "host" does not match its declared type
schema/type-mismatch: field "id" does not match its declared type

3 wird abgelehnt, weil beide Varianten des one-of es nehmen. Dem leeren Kommando fehlt das Element, das list-items zuerst verlangt. ["a" "a"] ist nicht eindeutig, "localhost" ist, was das not ausschließt, und "7" ist weder eine Ganzzahl noch eine UUID — eine Zeichenkette wird nie umgewandelt, damit sie passt.

Einschränkungen

Ein Wert für {:refine T %{…}} muss zu T und zu jeder Einschränkung in der Map passen. Die Schlüssel, nach der Art Wert, für die sie gelten:

Gilt fürSchlüssel
Zahlen, Datum, Zeiten, Dauernmin, max, exclusive-min, exclusive-max — gegen einen Wert derselben Art; NaN liegt außerhalb jedes Bereichs
Zahlenmultiple-of; für Gleitkommazahlen finite und float32; für Dezimalzahlen min-precision, max-precision, min-exponent, max-exponent
Zeichenketten, Keywords, Symbole, Bytes, Bitsmin-length, max-length — Codepoints eines Texts, Bytes von Bytes, Bits unter :bits; min-bytes, max-bytes (UTF-8); pattern
Zeichenkettenformat; encoding (base64, base64url, base32, base16), media-type und content — eine Zeichenkette, die ein DXN-Dokument eines bestimmten Typs enthält
Ganzzahlen, Bytesbits — nur die in der Liste genannten Bits dürfen gesetzt sein; für Bytes auch encodes und encodes-seq, ein oder mehrere .dxnb-Dokumente eines bestimmten Typs
Sammlungenmin-count, max-count; contains mit min-contains, max-contains; unique, unique-by
Zeitpunkteoffsets; before-now, after-now und within, die die Uhr befragen
Zeiten, Zeitpunkte, Dauernresolution — kein Teil feiner als :second, :millisecond, :microsecond oder :nanosecond
IP-Adressenversion 4 oder 6; prefix true oder false

format nimmt einen aus einer geschlossenen Menge von 22 Namen: date, time, datetime, local-datetime, duration, uuid, ipv4, ipv6, hostname, idn-hostname, email, idn-email, uri, uri-reference, iri, iri-reference, uri-template, json-pointer, relative-json-pointer, semver, mac und host-port. Ein Format, für das DXN ein Tag hat, prüft der Leser dieses Tags; jedes andere eine Grammatik, die die Spezifikation angibt, sodass jede Implementierung es gleich prüft.

Eine Einschränkung lehnt einen Wert ab, für den sie nicht gilt — eine Länge an einer Ganzzahl, einen Bereich an einer Zeichenkette — und löst nie einen Fehler aus. Alles andere fällt beim Kompilieren des Schemas auf: ein unbekannter Schlüssel, ein falsch geschriebener, ein Argument der falschen Art, min-contains ohne contains und ein benannter Typ, der sich selbst erreicht, ohne dass etwas dazwischen liegt.

%{Name: {:refine :string %{min-lenght: 1}}}
%{Name: {:refine :string %{min-length: -1}}}
%{Name: {:refine {:list-of :integer} %{min-contains: 2}}}
%{A: {:nilable A}}
schema/compile: named type "Name": min-lenght is no refine constraint (DXNS.md §2)
schema/compile: named type "Name": min-length takes a non-negative integer, not -1
schema/compile: named type "Name": min-contains and max-contains count the items a contains matches
schema/compile: named type "A": reaches itself with no field or collection between (A -> A); it describes no value

Das Literal eines Enums ist der Wert selbst, verglichen über seine kanonische Form: {:enum 1} nimmt 1 und nicht 1.0.

Mit geladenem %{E: %schema{v: {:enum 1}}}
%E{v: 1}
%E{v: 1.0}
%E(1){v:1}
schema/type-mismatch: field "v" does not match its declared type

Struct-Schemas

Der Rumpf eines %schema{…} zählt die Felder direkt auf, und die Reihenfolge, in der sie stehen, ist die Reihenfolge der Felder — die, die positionelle Structs und die Binärform verwenden. Ein doppelt benanntes Feld ist ein Fehler. Ein Schlüssel mit ? am Ende markiert ein optionales Feld; das ? gehört nicht zum Namen. Ein Feld, das mehr als einen Typ braucht, nutzt %field{type: …, default: …, description: …}. Der Kopf enthält nur die Version: %schema(3){…} ist Version 3, ein Schema ohne ist Version 1.

User: %schema(3){
  name:  :string
  email: %field{type: :string, description: "where mail goes"}
  role?: %field{type: {:enum :admin :staff :guest}, default: :guest}
  id?:   :uuid
}

Optional heißt, das Feld darf fehlen, nicht, dass es nil sein darf: Ein vorhandenes optionales Feld muss zu seinem Typ passen wie jedes andere, nil wird also abgelehnt, außer der Typ ist {:nilable T}. Im Text fehlt ein abwesendes Feld einfach. Die Binärform füllt jede Position, deshalb schreibt ein Encoder für ein fehlendes Feld seinen Standardwert, wo es einen hat, und lehnt sonst ab, schema/missing-field, statt ein nil zu schreiben, das der Leser ablehnen würde.

Shapes und Cases

Eine %shape{…} ist ein benannter, unversionierter Typ für eine einfache Map. Ihr Rumpf wird wie der eines %schema geschrieben — Felder der Reihe nach, ? für optional, %field{} für einen Standardwert —, aber sie passt nur auf eine einfache Map, nie auf ein Struct. Ein deklariertes Feld wird über seinen Namen gefunden, gleich wie sein Schlüssel geschrieben ist; andere Schlüssel sind zusätzliche und bleiben erhalten. Ein fehlendes Feld erhält beim Dekodieren seinen Standardwert.

{:case field %{wert => typ, :else => typ}} ist der Typ, den ein Nachbarfeld wählt: Der Wert von field im selben Schema oder in derselben Shape wird mit jedem Schlüssel verglichen, wie ein Enum vergleicht, und :else gilt, wenn keiner gleich ist.

envelope.dxns
%{
  Envelope: %schema{
    type:    :string
    payload: {:case type %{"order.placed" => OrderPlaced, :else => :any}}
  }
  OrderPlaced: %shape{
    order-id: :integer
    currency: %field{type: :string, default: "EUR"}
    gift?:    :boolean
  }
}
Gelesen mit geladenem envelope.dxns
%Envelope{type: "order.placed", payload: %{order-id: 42}}
%Envelope{type: "order.placed", payload: %{order-id: "42"}}
%Envelope{type: "ping", payload: [1 2 3]}
%Envelope(1){type:"order.placed",payload:%{currency:"EUR",order-id:42}}
schema/type-mismatch: field "payload" does not match its declared type
%Envelope(1){type:"ping",payload:[1 2 3]}

Benannte Typen und andere Dateien

Jeder Eintrag auf oberster Ebene, der kein %schema{} ist, ist ein benannter Typ. Ein benannter Typ darf auf die anderen im selben Dokument verweisen, in beliebiger Reihenfolge: Ein Leser kompiliert sie alle, bevor er Verweise zwischen ihnen auflöst. Er darf auch auf sich selbst verweisen, solange jeder solche Kreis über ein Feld oder die Elemente einer Sammlung führt. {:nilable A} innerhalb von A prüft denselben Wert noch einmal und beschreibt nichts, deshalb lässt es sich nicht kompilieren.

Ein benannter Typ darf Parameter nehmen: {:generic [t] body} deklariert ihn, und {:of Name T} verwendet ihn mit T anstelle von t. Ein %schema kann nicht generisch sein, denn ein Struct reist unter einem Namen; ein Schema darf in seinen Feldern ein Generic verwenden.

thread.dxns
%{
  Thread:  %schema{comments: {:of Page Comment}}
  Page:    {:generic [t] %shape{items: {:list-of t}, next?: :string}}
  Comment: %shape{text: :string, replies?: {:list-of Comment}}
}
Gelesen mit geladenem thread.dxns
%Thread{comments: %{items: [%{text: "hi", replies: [%{text: "yes"}]}]}}
%Thread{comments: %{items: [%{text: "hi", replies: [%{text: 1}]}]}}
%Thread(1){comments:%{items:[%{replies:[%{text:"yes"}],text:"hi"}]}}
schema/type-mismatch: field "comments" does not match its declared type

ns/Name verweist auf ein Schema oder einen Typ in einer anderen Datei, und ein Feld vom Typ geo/Address nimmt ein Struct namens geo/Address, nicht eines namens Address. Wie ein Leser die Datei findet, ist seine Sache, aber einer, der Namen zu Dateien auflöst, folgt einer Konvention, sodass ein Satz Schema-Dateien jeder Implementierung dient. Für Foo.Bar/Baz in Version N, auf jedem Suchpfad der Reihe nach:

AblageVersion 1Version N
VerzeichnisseFoo/Bar/Baz.dxns, Foo/Bar/Baz-v1.dxnsFoo/Bar/Baz-vN.dxns
ein Verzeichnis pro NameFoo/Bar/Baz/v1.dxnsFoo/Bar/Baz/vN.dxns
flachFoo.Bar.Baz.dxns, Foo.Bar.Baz-v1.dxnsFoo.Bar.Baz-vN.dxns
Namensraum-Dateider Eintrag Baz in Foo.Bar.dxnsdieselbe Datei, über ihr %schema(N)

Der erste Suchpfad, der den Namen hat, entscheidet. Die Version einer Datei ist die ihres Schemas, eine Version in zwei Dateien wird abgelehnt, mit beiden Namen, und jede gefundene Version wird geladen, sodass ein älteres Struct den Materializer erreicht.

customer.dxns, mit geo.dxns mit %{Address: %schema{city: :string}} im Suchpfad
%{Customer: %schema{name: :string, home: geo/Address}}

%Customer{name: "Ada", home: %geo/Address{city: "Dresden"}}
%Customer{name: "Ada", home: %Address{city: "Dresden"}}
%Customer(1){name:"Ada",home:%geo/Address(1){city:"Dresden"}}
schema/type-mismatch: field "home" does not match its declared type

Durchsetzung

Ohne Schema ist ein Struct ein undurchsichtiger Wert, nie ein Fehler. Kennt ein Leser das Schema, muss jeder Wert dieses Structs seine Pflichtfelder haben und jedes vorhandene Feld einen Wert seines deklarierten Typs. Ein Wert passt nur auf seinen deklarierten Typ, und nichts wird umgewandelt, damit er passt: Eine Ganzzahl ist keine Zeichenkette und eine Map kein Struct — ein Feld vom Typ Address nimmt ein Address-Struct und sonst nichts. Ein Verstoß ist ein Fehler eigener Art, verschieden von einem Parse-Fehler.

Gelesen mit geladenem %{Money: %schema{amount: :decimal, currency: {:enum :usd :eur :gbp}}}
%Money{amount: 9.99M, currency: :eur}
%Money[9.99M :eur]
%Money{amount: 9.99M, currency: :chf}
%Money{currency: :eur}
%Money[9.99M]
%Money(1){amount:9.99M,currency::eur}
%Money(1){amount:9.99M,currency::eur}
schema/type-mismatch: field "currency" does not match its declared type
schema/missing-field: missing required field "amount"
schema/field-count: expected 2 positional field(s), got 1

Zusätzliche Felder

Ein Struct garantiert seine deklarierten Felder und darf mehr tragen. Code, der sich auf ein Struct verlässt, kann nur auf die deklarierten zählen; der Rest sind seine zusätzlichen Felder, die ein Leser behält und zurückschreibt, statt sie zu verwerfen. So gelangen die Felder eines neueren Erzeugers unbeschadet durch einen älteren Dienst.

  • Im Text sind sie Einträge: die nicht deklarierten Einträge eines Structs mit Schlüsseln und die Einträge nach den Elementen eines positionellen Structs — siehe Structs.
  • In .dxnb reisen sie als eine abschließende Map unter Tag 215 — siehe private Tags.
  • Ein zusätzliches Feld verdeckt nie ein deklariertes: Derselbe Name auf beide Arten ist schema/shadowed-field. Sein Schlüssel folgt der Regel für Map-Schlüssel.
  • Jeder Leser muss ein striktes Dekodieren anbieten, das zusätzliche Felder an einem Struct mit bekanntem Schema ablehnt: schema/undeclared-field. Ein Konfigurationslader liest strikt, um Tippfehler in einer handgeschriebenen Datei zu finden; ein Nachrichtenkonsument nicht.
Mit dem Money-Schema von oben
%Money{amount: 9.99M, currency: :eur, note: "gift"}
%Money[9.99M :eur note: "gift"]
%Money{amount: 9.99M, currency: :eur, "amount" => 1}
%Money{amount: 9.99M, currency: :eur, note: "gift"}   # strict
%Money(1){amount:9.99M,currency::eur,note:"gift"}
%Money(1){amount:9.99M,currency::eur,note:"gift"}
schema/shadowed-field: struct "Money" names "amount" twice: an extra field never shadows a declared one
schema/undeclared-field: struct "Money" carries "note", which its schema does not declare

Deshalb ist ein DXNS-Typ nie geschlossen. Ob unbekannte Felder abgelehnt werden, entscheidet der Leser, nicht der Typ, sodass dasselbe Schema einem Konfigurationslader und einem Nachrichtenkonsumenten dient. Und ein geschlossener Typ würde aus jedem hinzugefügten Feld eine inkompatible Änderung machen: Jeder ältere Leser würde jede neuere Nachricht ablehnen.

Schema-Versionen

Jedes .dxns-Dokument beschreibt eine Version jedes Schemas, das es enthält. Ein Leser lädt beliebig viele Dokumente und hält jedes Schema nach Name und Version, sodass Point in den Versionen 1, 2 und 3 nebeneinander geladen sein kann. Eine bereits geladene Version noch einmal zu laden ist ein Fehler, schema/duplicate-version: Zwei Dokumente, die beide Point Version 2 sein wollen, sind ein Versehen, kein Update. Eine geladene Version zu ersetzen — der Austausch im laufenden System — ist ein eigener Vorgang, und eine dort genannte, nicht geladene Version ist schema/not-loaded.

# point-v1.dxns
%{Point: %schema{x: :integer, y: :integer}}

# point-v2.dxns
%{Point: %schema(2){x: :integer, y: :integer, label?: :string}}

Jedes Struct, das ein Encoder gegen ein Schema schreibt, trägt die neueste geladene Version, %Point(2){…} — und %Point(1){…}, wenn Version 1 die einzige ist —, damit ein Leser nie raten muss. Ein Struct ohne Version, meist von Hand geschriebener Text, wird als die neueste gelesen. Ein Struct-Verweis in einem Schema nennt keine Version: Ein Feld vom Typ Point nimmt jede Version, und das Tag des eingebetteten Structs entscheidet, wie es gelesen wird.

Das Struct sagtDer Leser
keine Version oder die neueste geladeneliest es exakt mit dem neuesten Schema; in .dxnb muss die Anzahl der Elemente stimmen
eine neuere Version als jede geladeneliest es gegen die neueste, die er hat: Text nach Namen, unbekannte Felder als zusätzliche; .dxnb nach Position, Elemente jenseits seiner eigenen Felder fallen weg
eine ältere Version, die geladen istliest es mit dem Schema dieser Version und reicht es an den Materializer; ohne einen schema/no-materializer
eine ältere Version, die nicht geladen istschema/unknown-version — ohne das Schema des Schreibers gibt es keine Feldnamen
Ein älterer Leser, nur mit point-v1.dxns
%Point(2){x: 1, y: 2, label: "origin"}
%Point(1){x:1,y:2,label:"origin"}

Ein Leser darf pro Schema einen Materializer registrieren: eine Funktion, die aus einem dekodierten Struct den Wert der Anwendung baut. Sie wird für jedes Struct ihres Schemas aufgerufen, gleich welcher Version, mit dem Namen, der Version, mit der die Felder gelesen wurden, und den Feldern; sie hebt ältere Versionen an, und ihr Ergebnis wird gegen die neueste Version geprüft — eine Ablehnung oder ein abgewiesenes Ergebnis ist schema/materializer.

Jede Implementierung bietet eine Prüfung der Versionsdisziplin für die CI. Sie vergleicht die Schemas des vorigen Release mit den aktuellen, schlägt fehl, wenn sich der Inhalt einer Version ohne neue Version geändert hat oder die neueste Version eines Schemas gesunken ist, und listet, was der Materializer anheben muss. In dextrin ist das mix dextrin.compat:

$ mix dextrin.compat schemas-old/ schemas/
Point 1 -> 2: added label
OK: no version discipline problems