Wie ein Codec seinen Payload aufbaut, legt das Codebook fest. Das Codebook von GEUL ist kein eigenes Format, sondern ein GEUL-Dokument. Zu jedem Codec gibt es genau ein Spezifikationsdokument.

Ort des Spezifikationsdokuments

Die Spezifikationsdokumente der direkten Codes veröffentlicht der GEUL-Issuer (0x00000000). Ein Spezifikationsdokument ist ein Codec-Dokument und hat keine Dokument-ID. Die Codec ID ist das TAG WORD des Codecs (nur Abschnitt und Codec-Stelle C, Length ist 0), geschrieben als 32-Bit-Wert.

/.well-known/geul/0x00000000/codecs/0x0000<TAG>/<Versions-ID>.geul
CodecTAGSpezifikationsdokument
Reference LOCAL00500x00000000/codecs/0x00000050
Value QUANTITY06600x00000000/codecs/0x00000660
Edge TRIPLE0AA00x00000000/codecs/0x00000AA0
Edge PUBLICATION0B800x00000000/codecs/0x00000B80

Der Decoder bildet die Adresse des Spezifikationsdokuments allein aus dem TAG WORD. Trifft er auf einen unbekannten Codec, lädt und liest er dieses Dokument.

  • <TAG> ist das Ziel-TAG-WORD als vierstelliger Hex-Wert (Großbuchstaben). Die Length-Stelle ist 0000. Es gibt ein Codec-Dokument pro Code. Auch das Reference-5Q-System erhält je Quantifizierungscode ein eigenes Dokument (LOCAL Identified 0050, LOCAL Generic 0060). Direkte Codes und Issuer-Codecs verwenden dieselbe Adressregel <Issuer>/codecs/<Codec ID>/ (Veröffentlichungsadresse und Versionsliste).
  • Auch Slot-Marker (0x0000, 0x0010, 0x0020) haben ein Spezifikationsdokument. Da sie keinen Payload haben, enthält es nur DECLARE und kein FIELD. Bedeutung und Annahmeregel der Marker sind im Decoder eingebaut (Schicht 0). Auch ein Codec, dessen Layout noch nicht festgelegt ist, beginnt als Spezifikationsdokument mit nur DECLARE.
  • Ein Spezifikationsdokument verwendet als DOC-ID einen CODEC-POINTER (0x00000000, 0x0000<TAG>, 0). Auch der Versionslisten-Record verwendet diesen CODEC-POINTER.
  • Regeln für Version, kanonische Adresse und Signatur sind dieselben wie bei allgemeinen veröffentlichten Dokumenten.

Codebook und Spezifikationsausgabe

  • Auch ein Codec-Dokument kann mit IMPORT-DOC importiert werden. Dann steht an der Dokumentstelle statt eines DOC-POINTER ein CODEC-POINTER. SPEC-VERSION im Dokument-HEAD bestimmt, welchem Codebook das Dokument folgt.
  • Jeder Decoder bringt das Kern-Codebook mit oder lädt es von dieser Adresse.
  • Wird ein Vorschlag (Prefix 000) zum Standard erhoben, bleibt das Layout unverändert, und nur der Prefix wechselt zu 001 (Überblick). Da sich das Ziel-TAG-WORD ändert, wird die angenommene Fassung ein neues Spezifikationsdokument mit anderer Codec ID, und das Vorschlagsdokument bleibt unveränderlich bestehen.

Vier Vokabeln

EdgeCodecAufgabe
DECLARE0x0BBLDeklariert den Payload-Aufbau eines Codecs. Ziel-TAG-WORD, 1 WORD
FIELD0x0BCLEin Payload-Feld. Zugehöriges DECLARE und Breite
ENUM0x0BDLGibt einem Codewert eines Rohwert-Felds eine Bedeutung
CODEC0x0BELBestimmt ein Kind oder einen Codec, den ein Feld annimmt
  • Das Layout der vier Edges ist im Decoder eingebaut (Schicht 0), weil ein Spezifikationsdokument ohne Codebook lesbar sein muss. Zum Lesen eines Spezifikationsdokuments ist kein weiteres Spezifikationsdokument nötig.
  • Namen (Codec-Name, Feldname, Name des Codewerts) werden alle per BIND gebunden.

FIELD

Edge Id           LOCAL
DECLARE           LOCAL (das DECLARE, zu dem dieses Feld gehört)
Breite            1 WORD: 0 = Record, n = Rohwert aus n WORD, 0xFFFF = restlicher Rohwert
  • Die Reihenfolge innerhalb des Dokuments der FIELDs, die auf dasselbe DECLARE zeigen, ist die Reihenfolge der Payload-Felder.
  • Ein Record-Feld beginnt mit einem TAG WORD und wird in der Länge seines Length gelesen.
  • Ein Rohwert-Feld ist eine vorzeichenlose ganze Zahl, die in der festgelegten Anzahl WORD gelesen wird. Werte, die eine Interpretation brauchen, etwa Vorzeichen, Dezimalstellen oder Datum, sind kein Rohwert, sondern ein Value-Record.
  • Ein restlicher Rohwert (0xFFFF) darf nur einmal vorkommen, und danach folgen nur Rohwerte fester Breite.
  • Die Edge Id eines Edge wird nicht als FIELD deklariert. Sie ist das erste Element jedes Edge und daher implizit. EDGE-ISSUER ist das erste Element nach Issuer und Codec-Nummer (EDGE-ISSUER-2WORD).
  • Die Position nach dem Lesen aller Felder muss genau mit dem Ende des Records übereinstimmen.

CODEC

Bestimmt das Format, das ein Feld annimmt. Das Ziel-WORD verwendet die Codec-Stelle des TAG WORD (Abschnitt KKKK und C) unverändert.

Length-StelleBedeutungBeispiel
0000genauer Codec0680 SIGNED-DECIMAL, 0050 LOCAL
1111Wildcard: unabhängig vom Wert C der gesamte Abschnitt KKKK (32 Plätze). Empfohlen ist der erste Platz des Abschnitts (C = 0)000F ganzer Abschnitt 0, 060F ganzer Abschnitt 3
  • Erstreckt sich ein Kind über mehrere Abschnitte, wird CODEC für jeden Abschnitt aufgeführt. Beliebige Reference sind 000F, 020F, 040F, beliebige Value sind 060F, 080F.

  • Bei Quantifizierung-unabhängig oder bei Gruppen werden die genauen Codecs aufgeführt. Wikidata-QID (Quantifizierung-unabhängig) sind fünf: 0140, 0150, 0160, 0170, 0180.

  • Hat ein Record-Feld kein CODEC, nimmt es beliebige Records an (Slot-Marker ausgenommen). Hat es eines oder mehrere, muss es eines davon sein (geschlossene Liste).

  • Wird bei einem Rohwert-Feld ein CODEC gesetzt, wird der Rohwert als dieser Value ohne TAG interpretiert.

Optionale Felder und Slot-Marker

Ein Slot-Marker ist eine Gruppe von 1-WORD-Records, die den ersten drei Plätzen 0x000L~0x002L in Reference-Abschnitt 0 zugewiesen sind. Er darf nur an einer Stelle stehen, an der die CODEC-Liste des Felds genau dieses WORD als exaktes Ziel führt.

CODEC-ZielMarkerDas Feld ist dann
0000ABSENT, nicht angegebenein optionales Feld. Es darf entfallen
0010UNKNOWN-VALUE, unbekanntnimmt die Aussage an, dass es einen Wert gibt, dieser aber unbekannt ist
0020NO-VALUE, kein Wertnimmt die Aussage an, dass es keinen Wert gibt
  • Annahmeregel: Ein Marker ist nur gültig, wenn dasselbe WORD als exaktes Ziel in der CODEC-Liste des Felds steht. Wildcards (000F, 060F …) und Felder ohne CODEC („beliebiger Record“) nehmen keine Marker an. An den Record-Stellen von HEAD und BODY sowie an der Edge-Id-Stelle ist er invalid.
  • Wird ein optionales Feld ausgelassen, steht an seiner Stelle ein einzelnes WORD 0x0000 (ABSENT). Auch ein optionales Feld belegt seine Stelle immer. Daher hat ein Record nur eine Schreibweise, und die Zerlegung ergibt sich allein aus der Position.
  • Ein Marker hat einen eigenen Reference-Code, überschneidet sich nicht mit anderen Records, und auch ein Decoder ohne Kenntnis der Spezifikation überspringt ihn als 1-WORD-Record.
  • Die drei Marker sagen Verschiedenes. ABSENT ist eine Aussage über das Dokument (diese Stelle wurde nicht gefüllt) und behauptet daher nichts über die Welt. UNKNOWN-VALUE behauptet, dass es einen Wert gibt (∃x), NO-VALUE, dass es keinen Wert gibt (¬∃x, innerhalb einer einschränkenden Bedingung). Auslassen heißt nicht „kein Wert“, sondern „nicht angegeben“.
  • Was ein Marker bedeutet, legt die Codec-Spezifikation fest, die ihn annimmt (TRIPLE, QUALIFIER).

Beispiel: Spezifikationsdokument von TRIPLE

Der BODY von 0x00000000/codecs/0x00000AA0.

EdgeInhaltName (BIND)
#1 DECLAREZiel 0AA0TRIPLE
#2 FIELDFeld von #1, Recordpredicate
#3 FIELDFeld von #1, Recordsubject
#4 FIELDFeld von #1, Recordobject
#5 FIELDFeld von #1, Rohwert 1 WORDrank
#6~#8 ENUMCodewerte 0, 1, 2 von #5normal, preferred, deprecated
#17 CODEC#5 wird als UNSIGNED-INTEGER (0620) interpretiert
#18, #22, #23, #19, #24 CODEC#4 ist beliebige Reference (000F·020F·040F) oder beliebiger Value (060F·080F)
#20, #21 CODEC#4 nimmt auch UNKNOWN-VALUE (0010) und NO-VALUE (0020) an
#25~#27 CODEC#2 ist beliebige Reference (000F·020F·040F)
#28~#30 CODEC#3 ist beliebige Reference (000F·020F·040F)

Mit diesem einen Dokument zerlegt ein Decoder einen TRIPLE-Record in Felder, zeigt ihn mit Feldnamen an und prüft, ob das Format stimmt.

Beispiel: Spezifikationsdokument von QUANTITY

Bei Value QUANTITY (0660) sind alle vier Felder Records.

FeldCODEC
amount0610 SIGNED-INTEGER, 0620 UNSIGNED-INTEGER, 0630 BINARY-FLOAT (nur endliche Werte), 0670 FRACTION, 0680 SIGNED-DECIMAL, 0690 UNSIGNED-DECIMAL
unit000F·020F·040F beliebige Reference, 0000 optional
lower0610·0620·0630·0670·0680·0690 (wie amount), 0000 optional
upper0610·0620·0630·0670·0680·0690 (wie amount), 0000 optional

Regeln

  • Ein Spezifikationsdokument enthält genau ein DECLARE. Das Ziel des DECLARE ist gleich dem TAG WORD der Codec ID.
  • Dasselbe Ziel wird in einem Dokument nicht zweimal deklariert.
  • Varianten mit unterschiedlichem Feldaufbau werden nicht über Verzweigungen ausgedrückt. Jeder Codec wird einzeln deklariert.
  • Layouts mit mehr als einem variablen Rohwert oder mit einer Rohwert-Breite, die vom Wert eines anderen abhängt, sind nicht deklarierbar. Solche Teile werden in einen Record eingepackt.
  • Ein Spezifikationsdokument wird wie andere Dokumente nach Versionen veröffentlicht. Das binäre Layout eines Codecs wird jedoch nicht überarbeitet. Um es zu ändern, wird ein neuer Codec zugewiesen.

Offene Probleme

  • Die Zuordnung vom SPEC-VERSION-Wert (in v1 0x0001) zur Version des Codebook-Dokuments. Ein Abstammungs-Meta, das die angenommene Fassung mit der Vorschlagsfassung verbindet.