The codebook determines how a Codec lays out its Payload. The GEUL codebook is not a separate format but a GEUL document. One Codec has one specification document.

Location of the Specification Document

The specification document of a direct code is published by the GEUL Issuer (0x00000000). A specification document is a Codec document and has no document ID. The Codec ID is the TAG WORD of that Codec (only the section and the Codec position of C, with Length 0) written as 32 bits.

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

A decoder builds the address of the specification document from the TAG WORD alone. When it meets an unknown Codec, it fetches and reads that document.

  • <TAG> is the 4-digit hex (uppercase) of the target TAG WORD. The Length position is 0000. There is one Codec document per code. The Reference 5Q scheme also has a separate one for each quantifier code (LOCAL Identified 0050, LOCAL Generic 0060). Direct codes and Issuer Codecs use the same address rule <Issuer>/codecs/<Codec ID>/ (Publication addresses and version lists).
  • Slot markers (0x0000, 0x0010, 0x0020) also have specification documents. They have no Payload, so they contain only DECLARE and no FIELD. The meaning of a marker and its acceptance rule are built into the decoder (Layer 0). A Codec whose layout is not yet decided also starts as a specification document containing only DECLARE.
  • A specification document places a CODEC-POINTER (0x00000000, 0x0000<TAG>, 0) in DOC-ID. The version list record also uses this CODEC-POINTER.
  • The rules for versions, canonical addresses, and signatures are the same as for ordinary published documents.

Codebook and Specification Edition

  • A Codec document can also be brought in with IMPORT-DOC. In that case, the document slot takes a CODEC-POINTER instead of a DOC-POINTER. The SPEC-VERSION in the document HEAD determines which codebook the document follows.
  • Every decoder either builds in the core codebook or fetches it from this address.
  • When a proposal (Prefix 000) is adopted as a standard, the layout stays the same and only the Prefix changes to 001 (Overview). Since the target TAG WORD changes, the adopted version becomes a new specification document with a different Codec ID, and the proposal document remains immutable.

Four Vocabularies

EdgeCodecWhat it does
DECLARE0x0BBLDeclares the Payload layout of one Codec. The target TAG WORD, 1 WORD
FIELD0x0BCLOne Payload field. The DECLARE it belongs to, and its width
ENUM0x0BDLGives a meaning to one code value of a raw-value field
CODEC0x0BELDesignates one Kind or Codec that a field accepts
  • The layouts of the four Edges are built into the decoder (Layer 0), because a specification document must be readable without a codebook. Reading a specification document requires no other specification document.
  • All names (Codec names, field names, code value names) are bound with BIND.

FIELD

Edge Id           LOCAL
DECLARE           LOCAL (the DECLARE this field belongs to)
Width             1 WORD: 0 = record, n = n WORDs of raw value, 0xFFFF = remaining raw value
  • The order within the document of the FIELDs that point to the same DECLARE is the Payload field order.
  • A record field starts with a TAG WORD and reads as many WORDs as its Length.
  • A raw-value field is an unsigned integer read for a fixed number of WORDs. A value that needs interpretation, such as a sign, a fraction, or a date, is not a raw value but a Value record.
  • The remaining raw value (0xFFFF) can appear only once, and only fixed-width raw values may follow it.
  • The Edge Id of an Edge is not declared as a FIELD. It is implicit, because it is the first element of every Edge. For EDGE-ISSUER it is the first element after the Issuer and Codec number (EDGE-ISSUER-2WORD).
  • The position reached after reading the fields in order must coincide exactly with the end of the record.

CODEC

It designates the format a field accepts. The target WORD uses the Codec position of the TAG WORD (section KKKK and C) as it is.

Length positionMeaningExample
0000Exact Codec0680 SIGNED-DECIMAL, 0050 LOCAL
1111Wildcard: regardless of the C value, the whole section KKKK (32 slots). Using the first slot of the section (C = 0) is recommended000F all of section 0, 060F all of section 3
  • When a Kind spans several sections, list a CODEC for each section. Any Reference is 000F, 020F, 040F, and any Value is 060F, 080F.

  • For a quantifier-agnostic set or a bundle, list the exact Codecs. The Wikidata QID (quantifier-agnostic) is five: 0140, 0150, 0160, 0170, 0180.

  • If a record field has no CODEC, it accepts any record (except slot markers). If it has one or more, it must be one of them (a closed list).

  • If a CODEC is placed on a raw-value field, that raw value is interpreted as that Value without a TAG.

Optional Fields and Slot Markers

A slot marker is a set of 1 WORD records assigned to the first three slots 0x000L~0x002L of Reference section 0. It can appear in a slot only when the field’s CODEC list names that WORD as an exact target.

CODEC targetMarkerThe field is
0000ABSENT, not writtenan optional field. It can be omitted
0010UNKNOWN-VALUE, unknownaccepts the assertion that a value exists but is unknown
0020NO-VALUE, noneaccepts the assertion that no value exists
  • Acceptance rule: A marker is valid only when the same WORD is an exact target in the field’s CODEC list. Wildcards (000F, 060F …) and fields with no CODEC (“any record”) do not accept markers. In the HEAD and BODY record slots and in the Edge Id slot, a marker is invalid.
  • To omit an optional field, write a single WORD 0x0000 (ABSENT) in its slot. An optional field also always occupies its slot. So a record has exactly one notation, and decomposition is determined by position alone.
  • A marker has its own Reference code, so it does not collide with other records, and a decoder that does not know the specification skips it as a 1 WORD record.
  • The three markers mean different things. ABSENT is a statement about the document (this slot was not filled), so it asserts nothing about the world. UNKNOWN-VALUE asserts that a value exists (∃x), and NO-VALUE asserts that no value exists (¬∃x, within a qualifying condition). Omission means “not written”, not “no value”.
  • What a marker means is determined by the specification of the Codec that accepts it (TRIPLE, QUALIFIER).

Example: TRIPLE Specification Document

This is the BODY of 0x00000000/codecs/0x00000AA0.

EdgeContentName (BIND)
#1 DECLAREtarget 0AA0TRIPLE
#2 FIELDa field of #1, recordpredicate
#3 FIELDa field of #1, recordsubject
#4 FIELDa field of #1, recordobject
#5 FIELDa field of #1, raw value 1 WORDrank
#6~#8 ENUMcode values 0, 1, 2 of #5normal, preferred, deprecated
#17 CODEC#5 is interpreted as UNSIGNED-INTEGER (0620)
#18, #22, #23, #19, #24 CODEC#4 is any Reference (000F·020F·040F) or any Value (060F·080F)
#20, #21 CODEC#4 also accepts UNKNOWN-VALUE (0010) and NO-VALUE (0020)
#25~#27 CODEC#2 is any Reference (000F·020F·040F)
#28~#30 CODEC#3 is any Reference (000F·020F·040F)

With this one document, a decoder splits a TRIPLE record into fields, displays it with field names, and checks that its form is correct.

Example: QUANTITY Specification Document

In Value QUANTITY (0660), all four fields are records.

FieldCODEC
amount0610 SIGNED-INTEGER, 0620 UNSIGNED-INTEGER, 0630 BINARY-FLOAT (finite values only), 0670 FRACTION, 0680 SIGNED-DECIMAL, 0690 UNSIGNED-DECIMAL
unit000F·020F·040F any Reference, 0000 optional
lower0610·0620·0630·0670·0680·0690 (same as amount), 0000 optional
upper0610·0620·0630·0670·0680·0690 (same as amount), 0000 optional

Rules

  • A specification document has exactly one DECLARE. The target of the DECLARE equals the TAG WORD of the Codec ID.
  • The same target is not declared twice in one document.
  • A variant with a different field composition is not expressed as a branch. Declare it separately for each Codec.
  • A layout with two or more variable raw values, or one in which the width of a raw value depends on another value, cannot be declared. Wrap such a part in a record.
  • A specification document is published with versions like other documents. However, the binary layout of a Codec is not revised. To change it, assign a new Codec.

Open Problems

  • The mapping from the SPEC-VERSION value (v1 is 0x0001) to the codebook document version. A lineage Meta that links the adopted version to the proposed version.