A Value is a record that holds a value itself. The Codec sets how the Payload is interpreted.

Layout

TAG WORD          000K KKKC CCCC LLLL      sections 3·4 (0x060L~0x09FL)
[Length extension TAG]
[Codec extension TAG]  for an Issuer format
Payload
  • LLLL is the total WORD count including the TAG WORD, minus 1. 1 to 14 WORDs are a direct length, and 15 WORDs or more use an extended length.
  • For an Issuer format, the Codec extension TAG holds the Issuer (width set by the Codec: 2/4/16 WORDs) and a 2 WORD codec number. The codec number is set by the Issuer.
  • A decoder knows the Kind, Length, Issuer, and codec number even without knowing the format.

Families

A Value number does not denote a family. Direct codes do not express the family in their bits, and Issuer formats have no family rule either. A family is a grouping by subject.

FamilyDirect codes
NUMERIC0x060L~0x067L
DECIMAL0x068L~0x069L
TIME0x06AL~0x071L, 0x081L
TEXT0x072L~0x07AL
BINARY0x07BL~0x080L
  • Numeric values such as vectors, tensors, complex numbers, fractions, and intervals are NUMERIC. As an exception, BIT-VECTOR is BINARY. Language codes are TEXT.
  • An Issuer-format record carries a Codec extension TAG (Issuer and codec number). If the Payload is long (15 WORDs or more in total), a Length extension TAG is used.

Direct codes

CodecNameFamilyDescription
0x060LBOOLNUMERICfalse or true
0x061LSIGNED-INTEGERNUMERICTwo’s complement integer in the minimum number of WORDs
0x062LUNSIGNED-INTEGERNUMERICUnsigned integer in the minimum number of WORDs
0x063LBINARY-FLOATNUMERICIEEE 754 binary16/32/64/128
0x064LCOORDINATE-EARTHNUMERICEarth (WGS 84) latitude and longitude with uncertainty (unit Reference)
0x065LCOORDINATE-GEONUMERICCelestial body Reference with latitude and longitude, and uncertainty (unit Reference)
0x066LQUANTITYNUMERICNumeric amount (integer, BINARY-FLOAT, decimal, fraction), unit Reference, lower and upper bounds
0x067LFRACTIONNUMERICFraction that preserves notation (numerator and denominator records, not reduced)
0x068LSIGNED-DECIMALDECIMALC × 10^E, signed coefficient
0x069LUNSIGNED-DECIMALDECIMALC × 10^E, unsigned coefficient
0x06ALGREGORIAN-DATETIMENumber of days since 1970-01-01 (Gregorian calendar)
0x06BLCIVIL-TIME-NANOSECONDSTIMENanoseconds since midnight
0x06CLPOSIX-TIMESTAMP-SECONDSTIMESeconds since the Unix epoch
0x06DLDURATION-SECONDSTIMEElapsed time (seconds)
0x06EL/0x06FLEDTFTIMEISO 8601-2 extended date string (year and month precision, uncertainty, intervals)
0x070L/0x071LGEDCOM-DATETIMEGEDCOM 7 date string (other calendars such as Julian)
0x072L/0x073LUTF8-TEXTTEXTUTF-8 string with no language
0x074L/0x075LURITEXTRFC 3986 URI
0x076L/0x077LLANGUAGE-BCP47-CODETEXTBCP 47 language tag
0x078L/0x079LUTF8-LANGUAGE-TEXTTEXTLanguage-tagged text
0x07ALLANGUAGE-SHORT-CODETEXT1 WORD compressed language code
0x07BLUUIDBINARYRFC 9562 UUID
0x07CLSHA-256-DIGESTBINARYSHA-256 result
0x07DLSHA1-DIGESTBINARYSHA-1 result (for identification, such as git object IDs)
0x07EL/0x07FLOPAQUE-BYTESBINARYByte sequence of unknown meaning and format. Even/odd bytes
0x080LBIT-VECTORBINARYN bits stored MSB-first after the bit count
0x081LDURATION-NANOSECONDSTIMEElapsed time (nanoseconds)
  • Codecs paired as even/odd are variable-length byte sequences. The even code is for an even byte count, the odd code for an odd byte count (Record and TAG WORD).
  • Direct codes occupy 0x060L~0x081L with no Reserved gaps. 0x082L~0x09CL are Reserved, and 0x09DL~0x09FL are VALUE-ISSUER-2WORD·4WORD·16WORD.

Issuer formats

A format not among the direct codes is placed as a codec number under the Issuer of the body that established the format. Conventional formats with no establishing body go under ADHOC (0x00000002). GEUL’s own formats (OPAQUE-BYTES, BIT-VECTOR, DURATION-NANOSECONDS) are direct codes.

IssuerExample formats
ADHOC 0x00000002BFLOAT16, integer and real vectors, tensors, complex numbers, fractions, intervals, quaternions, BLAKE3
IETF 0x00000007Relative URI, CRC32C, IPv4 and IPv6 addresses
IEEE 0x0000000DIEEE 754 decimal32/64/128, POSIX nanosecond timestamps, MAC addresses
KHRONOS 0x0000000ERGBA8, BGRA8 pixels
ONNX 0x00000010, OCP 0x00000011FP8, FP4
BIPM 0x00000013TAI timestamps
NIST 0x00000015SHA-512, SHA3-256
GPS 0x00000016GPS timestamps
  • A decoder that does not know the format knows the Issuer and codec number and skips by Length.
  • The codec document is placed under the codecs/ of that Issuer by the record’s codec number. Example: IETF CRC32C is 0x00000007/codecs/0x0000C000/ (Publishing addresses and version list).
  • For large values such as images and video, referencing them by URI and SHA-256 is recommended rather than embedding them directly.
  • Works inside a byte sequence follow their original license. Record the source and license in Meta.

Format groups

Each group is described below. The layout, interpretation, validity, and examples of each format are in the per-format documents.

GroupFamilyFormats
numericNUMERICBOOL, integers, floating point, coordinates, QUANTITY, FRACTION
decimalDECIMALSIGNED-DECIMAL, UNSIGNED-DECIMAL, IEEE 754 decimal32/64/128
timeTIMEDates, times of day, timestamps, elapsed time, EDTF, GEDCOM dates
textTEXTUTF-8 text, language-tagged text, URI, language codes
binaryBINARYUUID, digests, CRC, network addresses, unknown byte sequences, bit vectors
vectorNUMERICInteger and real dense vectors, points and bounding boxes, RGBA and BGRA pixels
tensorNUMERICDense and packed tensors with format, rank, and shape attached
etcNUMERICComplex numbers, fractions, closed intervals, quaternions
  • The vector, tensor, and etc groups are all Issuer formats (ADHOC, KHRONOS) of the NUMERIC family.

numeric

The basic number formats of the NUMERIC family. They are placed in the direct codes 0x060L~0x067L.

  • These are BOOL, signed and unsigned integers, IEEE 754 binary floating point, Earth (WGS 84) and celestial coordinates, QUANTITY that bundles an amount, unit, and bounds, and FRACTION, a fraction in its original notation.
  • Integers are written in the minimum number of WORDs the value fits.
  • Small scalar Issuer formats (BFLOAT16, FP8, FP4) have only codec numbers assigned and no detailed specification (open problem in Value).
  • Vectors, tensors, complex numbers, reduced fractions (RATIONAL-I64), and intervals are also in the NUMERIC family, but being Issuer formats they are placed in the vector, tensor, and etc groups.

decimal

The DECIMAL family is for exact decimal number formats. They are placed in the direct codes 0x068L~0x069L.

  • The direct codes SIGNED-DECIMAL and UNSIGNED-DECIMAL are written as C × 10^E and hold the digits of the original notation as they are. 1.20 (C=120, E=−2) and 1.2 (C=12, E=−1) are different records. Value equality and preservation of the quantum is an open problem of SIGNED-DECIMAL.
  • The DPD and BID encodings of IEEE 754 decimal32/64/128 are formats of the IEEE Issuer (0x0000000D).

time

The TIME family is for date and time formats. They are placed in the direct codes 0x06AL~0x071L and 0x081L (DURATION-NANOSECONDS).

PrecisionFormat
Date (Gregorian calendar)GREGORIAN-DATE
Year and month, uncertainty, intervalsEDTF
Original notation of other calendars (Julian, etc.)GEDCOM-DATE
Time of dayPOSIX, TAI, GPS timestamps
Elapsed timeDURATION-SECONDS, DURATION-NANOSECONDS
  • A date that can be written as GREGORIAN-DATE is not written as EDTF.
  • The nanosecond timestamps and the TAI and GPS formats are formats under the Issuers of their standards bodies (IEEE, BIPM, GPS).

text

The TEXT family is for text and string identifier formats. They are placed in the direct codes 0x072L~0x07AL.

  • A string with no language is UTF8-TEXT; text with a language, such as a name, title, or sentence, is UTF8-LANGUAGE-TEXT.
  • Language codes (LANGUAGE-SHORT-CODE, LANGUAGE-BCP47-CODE) are also in the TEXT family.
  • Variable-length byte sequences use an even/odd Codec pair. If the least significant bit is 1, the byte count is odd and the lower byte of the last WORD is 0x00 padding (Record and TAG WORD).

binary

The BINARY family is for byte sequence formats. They are placed in the direct codes 0x07BL~0x080L.

  • UUID, SHA-256, SHA-1, unknown byte sequences (OPAQUE-BYTES), and bit vectors (BIT-VECTOR) are direct codes. The other digests, CRC32C, and IPv4, IPv6, and MAC addresses are Issuer formats.
  • Fixed-size values (UUID, digests, addresses) have a set size, so there is no even/odd pair.
  • Public media such as images and video are placed as formats of the IANA Issuer (0x00000008). Codec numbers are assigned as even/odd pairs and the Payload is a byte sequence. The Length upper bound is 2^32−1 WORDs. For large values, referencing them by URI and SHA-256 is recommended rather than embedding them directly.
  • Works inside a byte sequence follow their original license. Record the source and license in Meta.

vector

Vector formats are Issuer formats of the NUMERIC family. Integer and real dense vectors and points and bounding boxes go under ADHOC (0x00000002) codec numbers 0x00000500~0x0000050C, and pixel formats under KHRONOS (0x0000000E).

  • The elements of a dense vector are stored contiguously in big-endian.
  • Being Issuer formats, the Codec extension TAG carries the Issuer 2 WORDs and the codec number 2 WORDs.

tensor

Tensor formats are Issuer formats of the NUMERIC family. They are placed at ADHOC (0x00000002) codec numbers 0x00000600~0x00000601.

  • DESCRIBED-DENSE-TENSOR holds the element format, rank, shape, and a C-contiguous dense payload.
  • DESCRIBED-PACKED-TENSOR holds the packed format, rank, shape, and a payload packed low-bit-first within an octet.

etc

Other number formats are Issuer formats of the NUMERIC family. They are placed at ADHOC (0x00000002) codec numbers 0x00000700~0x00000704.

  • These are complex numbers (COMPLEX64, COMPLEX128), the normalized fraction (RATIONAL-I64), the binary64 closed interval, and the binary32 quaternion.

Text

Text with a language and text without one are different values. “Paris” (string) and “Paris” (French) are not equal.

FormatWhere to use
UTF8-TEXTStrings with no language, such as identifiers, codes, file names, and external IDs
UTF8-LANGUAGE-TEXTText with a language, such as names, titles, and sentences
UTF8-LANGUAGE-TEXT
TAG WORD          0000 0111 100P LLLL   (P = text has odd bytes)
[Length extension TAG]
Language          LANGUAGE-SHORT-CODE or LANGUAGE-BCP47-CODE record
Text              UTF-8 bytes (last 0x00 if odd)
  • Text is well-formed UTF-8 and is preserved as is. Normalization is left to the side that compares and indexes.
  • A name common to several languages uses the language mul, and an undetermined language uses und. A string with no linguistic content is UTF8-TEXT.

Example: "Douglas Adams"@en (13 bytes, odd)

0799  0761 656E  446F 7567 6C61 7320 4164 616D 7300
TAG   lang en    D o  u g  l a  s ␠  A d  a m  s (padding)

Decimals and quantities

An exact decimal is written as C × 10^E. The exponent E is 32 bits, and the coefficient C is two’s complement in the minimum number of WORDs. The digits of the original notation are held as they are: 1.20 is C=120, E=−2, and 1.2 is C=12, E=−1. The two notations denote the same number but are separate records with different bytes. An encoder does not normalize the notation arbitrarily. The value equality of the two records and the meaning of the quantum (significant digits) are an open problem (SIGNED-DECIMAL).

QUANTITY holds an amount, a unit, and bounds in a single value.

TAG WORD          0000 0110 0110 LLLL
[Length extension TAG]
Amount            numeric Value record (integer, BINARY-FLOAT, decimal, fraction)
Unit              Reference record (unit item), 0x0000 if unitless
Lower bound       numeric Value record, 0x0000 ABSENT if omitted
Upper bound       numeric Value record, 0x0000 ABSENT if omitted
  • The unit is part of the value. The unit is not detached and written elsewhere (if detached, one cannot tell whether 652 is km or m).
  • A value converted to SI units is not held. It can be computed from the unit and the conversion table.
  • 0x0000 is ABSENT, the marker that an optional field is omitted (Codec spec document).

Example: 652 km, range [651, 653] (km = Wikidata Q828224)

066E 0011                    TAG (extended length 17 WORDs)
0683 0000 0000 028C          amount 652
0142 000C A340               unit Q828224
0683 0000 0000 028B          lower bound 651
0683 0000 0000 028D          upper bound 653

Dates

PrecisionFormat
Date (Gregorian calendar)GREGORIAN-DATE
Year and month, uncertainty (1971~), intervalsEDTF
Original notation of other calendars (Julian, etc.)GEDCOM-DATE
Time of dayPOSIX, TAI, GPS timestamps
  • A date that can be written as GREGORIAN-DATE is not written as EDTF.

Open problems

  • Public media formats (JPEG, PNG, MP4, MOV, etc.) are placed as codec numbers of the IANA Issuer (0x00000008). How to manage the mapping table between media types and codec numbers.
  • The final list of Value direct codes. To be decided by measuring Value frequency in samples of statutes and business conversations (candidates: amounts, percentages, date intervals).
  • Detailed specification and placement of the 7 small scalars (ADHOC BFLOAT16, the four ONNX FP8, OCP FP8-E8M0FNU·FP4-E2M1FN). Whether to move them to direct codes has not been decided. For now only codec numbers are assigned.