joetjen.net
EN DE
Datenformat

Das Binärformat

.dxnb ist DXN in CBOR (RFC 8949) kodiert: ein Umschlag aus drei Bytes, dann ein selbstbeschreibendes CBOR-Element. Typen, die CBOR schon kennt, nutzen dessen Haupttypen oder registrierte Tags; der Rest nutzt einen kleinen Block privater Tags. Jeder Wert nimmt die kleinste Darstellung, die ihn exakt erhält.

Format 1.0

Der Umschlag

Jede .dxnb-Datei beginnt mit den Bytes 44 58 — den Buchstaben DX — und einem Versionsbyte, derzeit 01. Anders als die Textkopfzeile ist der Umschlag Pflicht: Er kostet drei Bytes und lässt Werkzeuge die Datei an ihren ersten Bytes erkennen. Eine Endmarke folgt nicht; ein CBOR-Element weiß, wo es endet.

[1 2 3]
44 58 01        "DX", version 1
83 01 02 03     array(3): 1, 2, 3

Kommentare und verworfene Werte haben keine Binärform: Sie sind verschwunden, bevor es einen Wert zu kodieren gibt.

Typabbildung

TypCBORInhalt
nil, booleanSimple Values 22, 20, 21
GanzzahlHaupttyp 0/1; Tag 2/3 jenseits von 64 BitBignum-Bytes
GleitkommaHaupttyp 7die kürzeste von halber, einfacher und doppelter Genauigkeit, die den Wert exakt hält; NaN und die Unendlichkeiten in halber
Dezimalzahltag 4[exponent, mantissa]
Bruchtag 30[numerator, denominator]
ZeichenketteHaupttyp 3UTF-8
bytesHaupttyp 2rohe Bytes, kein Base64
ListeHaupttyp 4Elemente
mapHaupttyp 5Paare
uritag 32Text
uuidtag 3716 rohe Bytes
ipTag 52 (IPv4), Tag 54 (IPv6), RFC 9164eine Adresse: ihre rohen Bytes; ein Präfix: [länge, bytes], ohne abschließende Null-Bytes
alles andereprivate Tags 200–221siehe unten

Kleinste heißt: rohe Bytes, wo ein Typ im Kern Bytes ist — eine UUID, eine ObjectId, eine IP-Adresse —, Ganzzahlen, wo er eine Anzahl ist — Datum, Zeit, Dauer —, und überall die kürzesten Ganzzahl- und Längenformen von CBOR, nie die Textform, die ein Wert in .dxn hat. Ganzzahlen jenseits von 64 Bit nutzen die Bignum-Tags, nie eine Gleitkommazahl, und Zeiten und Zeitpunkte sind ganzzahlige Nanosekunden, nie eine Gleitkommazahl, die sie verlieren würde.

Private Tags

TagTypUmschließt
200Zeichenden Codepoint als Ganzzahl
201symbolText
202keywordText
203TupelArray
204arrayArray
205geordnete Mapmap
206MengeArray
207sortierte MengeArray, in kanonischer Reihenfolge
208struct[name, field, …, extras?]
209DatumTage seit 1970-01-01
210–212Zeit, Zeitpunkt, Dauer in Mikrosekundendie Formen von DXN 0.2: gelesen, nie geschrieben
213regexdas Muster; mit Flags [muster, flags]
214eigenes Tag[name, value]
215zusätzliche Feldereine Map — immer nur das letzte Element eines Structs
216bits[bytes, bit count]
217local-datetimeNanosekunden seit 1970-01-01T00:00:00 nach der Wanduhr
218ZeitNanosekunden seit Mitternacht
219datetimeEpoch-Nanosekunden in UTC; bei anderem Offset [epoch-nanosekunden, offset-minuten]
220Dauereine Feld-Bitmaske, dann die vorhandenen Felder
221objectid12 rohe Bytes

Der Block liegt im Bereich mit einem Zusatzbyte, abseits der dicht belegten niedrigen Nummern. Er ist nicht bei der IANA registriert und daher nur unter DXN-Dokumenten kollisionsfrei. Ein Tag ändert nie seine Bedeutung: Als die Zeiten von Mikro- auf Nanosekunden wechselten, bekamen die neuen Formen neue Tags, und ein Leser liest die alten — die Tags 210 bis 212 von DXN 0.2 und seine UTC-Zeitstempel unter CBOR-Tag 1 in Mikrosekunden — weiterhin als das, was sie bedeuteten.

Structs sind binär immer positionell — [name, feld-1, feld-2, …] —, denn Feldnamen helfen nur menschlichen Lesern. Die Textform mit Schlüsseln gibt es allein für sie. Der Name trägt die Schema-Version, "Point(2)", wenn das Struct eine hat. Zusätzliche Felder folgen den deklarierten als eine einzige Map unter Tag 215, mit einfachen Zeichenketten als Schlüsseln, wo der Schlüssel ein Name ist; Tag 215 kommt sonst nirgends vor.

Bit-Belegung

Die Bitmaske einer Dauer zeigt, welche Felder folgen, niedrigstes Bit zuerst; jedes vorhandene Feld folgt als vorzeichenbehaftete Ganzzahl, in Bit-Reihenfolge. Ein Regex trägt seine Flags ebenso als ein Byte. Bit 7 ist in beiden reserviert und muss 0 sein.

BitFeld der DauerRegex-Flag
0Jahrei
1Monatem
2Wochens
3Tageu
4Stundenx
5Minutenf
6Nanosekunden (Sekunden eingerechnet)r

Byte für Byte

Jede der folgenden Ausgaben ist das, was dextrin für den Text darüber schreibt.

%{x: 1}
44 58 01        envelope
A1              map(1)
D8 CA 61 78     tag 202 (keyword) "x"
01              1
19.99M
44 58 01        envelope
C4 82           tag 4 (decimal), array(2)
21              exponent -2
19 07 CF        mantissa 1999
[1.5 0.1 NaN]
44 58 01                        envelope
83                              array(3)
F9 3E 00                        1.5, half precision
FB 3F B9 99 99 99 99 99 9A      0.1, double precision
F9 7E 00                        NaN, half precision
%Point(2)[1 2 label: "a"]
44 58 01                     envelope
D8 D0 84                     tag 208 (struct), array(4)
68 50 6F 69 6E 74 28 32 29   "Point(2)"
01 02                        1, 2
D8 D7 A1                     tag 215 (extra fields), map(1)
65 6C 61 62 65 6C            "label"
61 61                        "a"
Mit geladenem %{Point: %schema{x: :integer, y: :integer}}
%Point{y: 2, x: 1}
44 58 01                     envelope
D8 D0 83                     tag 208 (struct), array(3)
68 50 6F 69 6E 74 28 31 29   "Point(1)" — the latest version loaded
01 02                        x = 1, y = 2, in schema order
@datetime "2024-01-01T12:30:00Z"
44 58 01                        envelope
D8 DB                           tag 219 (datetime)
1B 17 A6 39 04 62 68 D0 00      1704112200000000000 ns, UTC
@datetime "2024-01-01T14:30:00+02:00"
44 58 01                        envelope
D8 DB 82                        tag 219 (datetime), array(2)
1B 17 A6 39 04 62 68 D0 00      the same instant in ns
18 78                           offset 120 minutes
@duration "P1Y2M10D"
44 58 01        envelope
D8 DC 84        tag 220 (duration), array(4)
0B              bitmask 0000 1011: years, months, days
01 02 0A        1, 2, 10
@regex(i) "^a+$"
44 58 01        envelope
D8 D5 82        tag 213 (regex), array(2)
64 5E 61 2B 24  "^a+$"
01              flags 0000 0001: i
@regex "^a+$"
44 58 01        envelope
D8 D5           tag 213 (regex), no flags
64 5E 61 2B 24  "^a+$"
@objectid "507f1f77bcf86cd799439011"
44 58 01                                    envelope
D8 DD                                       tag 221 (objectid)
4C 50 7F 1F 77 BC F8 6C D7 99 43 90 11      bytes(12)
@ip "10.0.0.0/8"
44 58 01        envelope
D8 34 82        tag 52 (IPv4), array(2)
08              prefix length 8
41 0A           bytes(1): 10, zero bytes left off
@bits {"oA==" 3}
44 58 01        envelope
D8 D8 82        tag 216 (bits), array(2)
41 A0           bytes(1): 1010 0000
03              3 bits: 101

Wertteilung

Zwei optionale CBOR-Erweiterungen verkleinern Dokumente, die sich wiederholen. Encoder dürfen sie nutzen; Decoder müssen sie akzeptieren.

  • String-Referenzen — Tag 256 öffnet einen Bereich, Tag 25 verweist auf die n-te darin bereits gesehene Zeichenkette. Gedacht für wiederholte Symbole, Keywords und Struct-Namen.
  • Geteilte Werte — Tag 28 markiert ein Element als teilbar, Tag 29 verweist per Index auf ein markiertes Element. Funktioniert für jeden Wert: eine Map, eine Liste, ein Struct.

Teilen spart nur Bytes; es erzeugt nie Identität. Ein Decoder liefert für jeden Verweis eine unabhängige Kopie, das Ergebnis gleicht also einem Dokument, das alles ausschreibt. Ein Verweis auf ein noch nicht gesehenes Element oder einer, der einen Zyklus bildet, macht das Dokument ungültig: .dxnb-Werte sind immer Bäume.

Eine Adresse, dreimal verwendet — 129 Bytes, mit Teilen 75
%{
  "hq"       => %{"street" => "1 Main St", "city" => "Springfield"}
  "billing"  => %{"street" => "1 Main St", "city" => "Springfield"}
  "shipping" => %{"street" => "1 Main St", "city" => "Springfield"}
}
44 58 01                    envelope
A3                          map(3)
67 "billing"
D8 1C A2 …                  tag 28: the address map, marked (its strings too)
62 "hq"
D8 1D 04                    tag 29: marked item 4 — the map
68 "shipping"
D8 1D 04                    tag 29: marked item 4