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.
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
| Typ | CBOR | Inhalt |
|---|---|---|
| nil, boolean | Simple Values 22, 20, 21 | |
| Ganzzahl | Haupttyp 0/1; Tag 2/3 jenseits von 64 Bit | Bignum-Bytes |
| Gleitkomma | Haupttyp 7 | die kürzeste von halber, einfacher und doppelter Genauigkeit, die den Wert exakt hält; NaN und die Unendlichkeiten in halber |
| Dezimalzahl | tag 4 | [exponent, mantissa] |
| Bruch | tag 30 | [numerator, denominator] |
| Zeichenkette | Haupttyp 3 | UTF-8 |
| bytes | Haupttyp 2 | rohe Bytes, kein Base64 |
| Liste | Haupttyp 4 | Elemente |
| map | Haupttyp 5 | Paare |
| uri | tag 32 | Text |
| uuid | tag 37 | 16 rohe Bytes |
| ip | Tag 52 (IPv4), Tag 54 (IPv6), RFC 9164 | eine Adresse: ihre rohen Bytes; ein Präfix: [länge, bytes], ohne abschließende Null-Bytes |
| alles andere | private Tags 200–221 | siehe 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
| Tag | Typ | Umschließt |
|---|---|---|
| 200 | Zeichen | den Codepoint als Ganzzahl |
| 201 | symbol | Text |
| 202 | keyword | Text |
| 203 | Tupel | Array |
| 204 | array | Array |
| 205 | geordnete Map | map |
| 206 | Menge | Array |
| 207 | sortierte Menge | Array, in kanonischer Reihenfolge |
| 208 | struct | [name, field, …, extras?] |
| 209 | Datum | Tage seit 1970-01-01 |
| 210–212 | Zeit, Zeitpunkt, Dauer in Mikrosekunden | die Formen von DXN 0.2: gelesen, nie geschrieben |
| 213 | regex | das Muster; mit Flags [muster, flags] |
| 214 | eigenes Tag | [name, value] |
| 215 | zusätzliche Felder | eine Map — immer nur das letzte Element eines Structs |
| 216 | bits | [bytes, bit count] |
| 217 | local-datetime | Nanosekunden seit 1970-01-01T00:00:00 nach der Wanduhr |
| 218 | Zeit | Nanosekunden seit Mitternacht |
| 219 | datetime | Epoch-Nanosekunden in UTC; bei anderem Offset [epoch-nanosekunden, offset-minuten] |
| 220 | Dauer | eine Feld-Bitmaske, dann die vorhandenen Felder |
| 221 | objectid | 12 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.
| Bit | Feld der Dauer | Regex-Flag |
|---|---|---|
| 0 | Jahre | i |
| 1 | Monate | m |
| 2 | Wochen | s |
| 3 | Tage | u |
| 4 | Stunden | x |
| 5 | Minuten | f |
| 6 | Nanosekunden (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"
%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.
%{
"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