joetjen.net
EN DE
Datenformat

Das Datenformat DXN

DXN — Data eXchange Notation — ist ein Datenmodell in zwei Schreibweisen: .dxn, eine Textform zum Lesen und Bearbeiten, und .dxnb, eine Binärform auf CBOR-Basis. Beide tragen dieselben 31 Typen, von exakten Dezimalzahlen bis zu Mengen, Structs und Zeitstempeln, und lassen sich verlustfrei ineinander überführen.

Format 1.0

Ein erster Blick

Ein DXN-Dokument ist ein einzelner Wert. Dieses hier ist eine Map, die den Großteil des Formats auf einmal nutzt:

user.dxn
@dxn "1.0"
%{
  id:      @uuid "550e8400-e29b-41d4-a716-446655440000"
  name:    "Ada Lovelace"
  active:  true
  score:   19.99M
  tags:    @{:admin :staff}
  meta:    @ordered %{created: @datetime "1990-01-01T00:00:00Z"}
  address: %Point[51.05, 13.74]
  result:  {:ok, 200}
  handle:  @regex(i) "^[a-z0-9_]{3,20}$"
}
  • @dxn "1.0" ist eine optionale Kopfzeile mit der Formatversion.
  • %{…} ist eine Map; name: ist ein Keyword-Schlüssel. Kommas sind überall optional.
  • 19.99M ist eine exakte Dezimalzahl, keine Gleitkommazahl — der Typ für Geldbeträge.
  • @{…} ist eine Menge, {…} ein Tupel, @ordered %{…} eine Map, deren Reihenfolge zu ihrem Wert gehört.
  • %Point[…] ist ein Struct, nach Position geschrieben; ein Schema gibt seinen Feldern Namen und Typen.
  • @uuid "…", @datetime "…" und @regex(i) "…" sind eine UUID, ein Zeitpunkt in UTC und ein regulärer Ausdruck — Werte eigenen Typs, keine Zeichenketten. Jeder solche Typ ist ein Tag vor seinem Wert.

Dasselbe Dokument als .dxnb braucht 216 statt 320 Bytes und wird wieder zu exakt demselben Wert dekodiert.

Gestaltung

  • Ein Modell, zwei Kodierungen. Jeder Wert hat eine Text- und eine Binärform, und der Weg hin und zurück ist verlustfrei.
  • Exakte Zahlen. Ganzzahlen haben beliebige Genauigkeit; Dezimalzahlen und Brüche sind exakt und bleiben es auch binär. Nichts wird normalisiert: 1.50M bleibt 1.50M, 2/4 bleibt 2/4.
  • Absicht in der Syntax. Ein Tupel ist keine Liste, eine geordnete Map keine Map, eine Menge keine Liste ohne Duplikate — der Unterschied steht im Dokument, statt nebenbei vereinbart zu werden.
  • Eine Schreibweise pro Wert. Jenseits von Zahlen, Zeichenketten, Zeichen, Namen und Sammlungen ist jeder Typ ein Tag: @date "2024-01-01", @uuid "…", @regex "…". Datum und Uhrzeit sind ISO-8601-Zeichenketten unter ihrem Tag.
  • Robust bei Unbekanntem. Ein Struct oder Tag, das ein Leser nicht kennt, wird trotzdem gelesen — als undurchsichtiger Wert, den er unverändert weitergeben kann. Ebenso Felder, die ein neuerer Schreiber einem Struct hinzugefügt hat, das der Leser kennt.
  • Schemas in derselben Notation. Ein .dxns-Schema ist ein DXN-Dokument; eine zweite Sprache gibt es nicht. Schemas tragen Versionen, sodass Daten, die gegen ein altes geschrieben wurden, lesbar bleiben.
  • Vergleichbar über Sprachen hinweg. Jeder Wert hat eine kanonische Textform und jeder Fehler eine Kategorie, sodass sich Implementierungen gegeneinander prüfen lassen.
  • Vertraut für Elixir-Augen. Maps, Tupel, Keywords und ?c-Zeichen sind so geschrieben, wie Elixir sie schreibt.

Eckdaten

EigenschaftWert
Endungen.dxn Text, .dxnb binär, .dxns Schema
Medientypenapplication/vnd.dxn, application/vnd.dxnb, application/vnd.dxns; jeder Typ mit dem Suffix +dxn ist Text
TextkodierungUTF-8
Textkopf@dxn "1.0" — optional, vor dem Wert; ein Leser akzeptiert jedes 1.x
BinärDX, ein Versionsbyte, dann ein CBOR-Element (RFC 8949) — siehe Binärformat
Kommentare# bis zum Zeilenende; nur im Text
GrammatikPEG, geschrieben in Aether — siehe Grammatik

Ein Programm, das einen Inhalt ohne Typangabe erhält, kann billig prüfen, ob sich das Dekodieren lohnt. Binärform erkennt es an DX und einem Versionsbyte. Text und Schemas erkennt es, wenn nach Leerraum, Kommentaren und einer optionalen Kopfzeile als erstes Zeichen % steht — eine Map, ein Struct oder ein Schema-Dokument. Listen und Skalare bleiben absichtlich unerkannt: Mit [, ", Ziffern und true beginnt JSON genauso. Ein Ja heißt, dass sich das Dekodieren lohnt, nie, dass es gelingt.

Was sich mit dextrin 0.3 geändert hat

Die Formatversion ist weiterhin 1.0, und sie bleibt 1.0, bis die Bibliotheken, die es umsetzen, 1.0.0 erreichen. Bis dahin ändert sich das Format zwischen Releases ohne neue Versionsnummer, und 0.3 ist ein solches Release. Die Bibliotheken sagen das selbst: Sie sind in starker Entwicklung und vor 1.0.0 nicht für den Produktiveinsatz gedacht.

  • Sigils sind entfallen. Aus ~D[2024-01-01] wird @date "2024-01-01", aus ~T[…] wird @time "…", aus ~U[… 12:30:00Z] wird @datetime "…T12:30:00Z" und aus ~r/^a/i wird @regex(i) "^a". Ein Sigil ist ein Syntaxfehler.
  • Zeitstempel und Zeitpunkt mit Offset sind ein Typ, datetime: ein Zeitpunkt mit seinem Offset, Z für UTC. Das neue local-datetime ist eine Uhrzeit ohne Offset. Zeiten, Zeitpunkte und Dauern tragen Nanosekunden.
  • Drei neue Typen: @objectid, @ip und @bits. Eine ObjectId darf Map-Schlüssel sein, es gibt also jetzt neun Schlüsseltypen — siehe Map-Schlüssel.
  • Ein Name darf aus Segmenten mit Punkten bestehen: acme.billing/invoice, %Foo.Bar/Baz{…}.
  • .dxnb hat neue private Tags, 216 bis 221, und schreibt jeden Wert in seiner kleinsten exakten Form. Ein Leser von 0.2 lehnt die neuen Tags ab, daher werden zuerst die Leser ausgerollt; ein Leser von 0.3 liest weiterhin alles, was 0.2 geschrieben hat. Siehe Binärformat.
  • Die Schemasprache DXNS hat eine eigene Referenz und viele neue Typformen. {:one-of …} heißt jetzt, dass genau eine Variante passt — {:any-of …} hat die alte Bedeutung —, und ein unbekannter refine-Schlüssel oder ein refine-Argument der falschen Art lässt sich nicht mehr kompilieren. Siehe Schemas.
  • Die Spezifikation nennt jetzt Medientypen und wie sich ein Inhalt erkennen lässt, und sie führt vier Fehlerkategorien für Änderungen an einem Dokument — siehe Konformität.

Implementierungen

Diese Seiten beschreiben das Format. Die folgenden Bibliotheken lesen und schreiben es; ihre API steht jeweils in der eigenen Dokumentation.

NameSpracheRolle
dextrinElixirDie Referenzimplementierung, auf Hex: Text, Binär und Schemas, dazu ein Dokumenttyp, der Kommentare behält, wenn eine Datei bearbeitet oder formatiert wird
node-dextrinJavaScriptDieselben Dokumente für Node.js, auf npm als @joetjen/dextrin
php-dextrinPHPDieselben Dokumente für PHP, auf Packagist als joetjen/dextrin
dextrin für PraxisPraxisDie Portierung nach Praxis, Teil des Praxis-Repositorys; nicht eigenständig veröffentlicht
ichorElixirDer Grammatik-Compiler, der den Textparser von dextrin erzeugt

dextrin steht bei 0.3.3, mit einem schnelleren Parser, neu erzeugt von Ichor 0.7.3; node-dextrin und php-dextrin stehen bei 0.3.2, mit demselben Verhalten. Die vier Implementierungen folgen derselben Spezifikation, und die Dextrin Conformance Suite prüft, dass sie übereinstimmen — siehe Konformität.

dextrin bringt außerdem Kommandozeilen-Tasks mit. Für Dokumente: mix dextrin.validate, encode, decode und format, das Kommentare behält. Für Schemas: mix dextrin.check prüft einen Baum von .dxns-Dateien — Syntax, Kompilieren, Dateiablage und Namen — und meldet jedes Problem als datei:zeile; mix dextrin.docs schreibt dazu eine HTML-Dokumentation, jeder Verweis ein Link; und mix dextrin.compat prüft Schema-Versionen in der CI.

Auf diesen Seiten

  • Textformat — Dokumente, Trenner, Kommentare, Bezeichner, Tags und Verwerfen.
  • Werte — alle 31 Typen, ihre Schreibweise und welche Map-Schlüssel sein dürfen.
  • Binärformat — Umschlag, CBOR-Abbildung, private Tags und Wertteilung.
  • Schemas — .dxns-Dokumente: Typformen, Einschränkungen, Struct-Schemas, Shapes, zusätzliche Felder und Versionen.
  • Konformität — die kanonische Form, Fehlerkategorien und die Suite, die die Implementierungen daran misst.
  • Grammatik — die formale Grammatik und wo die Referenzimplementierung noch davon abweicht.