GEUL (General Encoding Unified Language) is an artificial language and binary format for humans and AI to exchange information without ambiguity.

These documents define the GEUL v1 grammar. The current edition is a pre-publication draft and may change. The specification is released under CC0 1.0.

At a Glance

  • All data is a sequence of 16-bit words (WORD), written in big-endian order.
  • The unit of data is the record. A record begins with one TAG WORD, and that TAG WORD states the record’s type and length.
  • There are four kinds of record (Kind).
KindWhat it doesExample
ReferencePoints to a targetWikidata Q42, #7 in this document
ValueHolds a value itselfA date, a quantity, text with a language tag
EdgeBinds other records together to make a statement“Q42 is a human”, “The English name of Q42 is Douglas Adams”
MetaSpeaks about the documentSpecification edition, document ID, author, signature
  • Records are held in a single document. Like HTML, a document is divided into HEAD (Meta, plus the document-wide source SOURCE and its QUALIFIER) and BODY (Reference, Value, Edge).
  • A document is issued by an Issuer, and each version is fixed by its content hash. A published version is never changed.

Design Principles

  1. Records can be skipped without a codebook. A record’s type and length are in the 16 bits of the TAG WORD. A decoder that does not know how to interpret a record (the codebook) can still count and skip it.
  2. It holds statements, not facts. A document records who made a statement, when, and from what source, using Meta and evidence Edges.
  3. Identification is done by Reference. Targets are pointed to by ID, not by name. Names are attached by Edge.
  4. What is published is not changed. Corrections are issued as a new version. An ID inside a document points to the same target across versions.
  5. Leave space empty. Most of the bit space is left for the future. Direct codes cannot be reclaimed, so only those whose frequency has been confirmed are assigned.

Sub-documents

If you are reading for the first time, read the table from the top in order.

DocumentContents
Record StructureTAG WORD layout, Length, Codec, extended TAG
Issuer and PublicationIssuer tiers, the 2-WORD assignment table, disclosure methods, signatures, verification keys
Publication Addresses and Version ListID notation, publication addresses, format specifiers, Issuer list, version list, trust layers
Codec Specification DocumentCodebooks written with DECLARE, FIELD, ENUM, CODEC
General DocumentDOC, HEAD, BODY, END, document ID, content hash, versions and revisions
Codec IndexAll 227 assigned slots, Codec tables by Kind and family
Section LayoutThe 16 sections and slot layout, assigned and Reserved ranges
Slot MarkersABSENT, UNKNOWN-VALUE, NO-VALUE, acceptance rules
ReferenceTarget identification, LOCAL, external references, Quantifier, slot markers
ValueValue families, direct codes, text, quantity, date
MetaStructure, definition, provenance, lineage, verification, policy, IMPORT
EdgeStatement, evidence, execution, and TOULMIN families; TRIPLE, QUALIFIER, LABEL
TOULMINJudgment and execution graph family; NODE, LINK, SOURCE layouts
Example: A Wikidata ItemReading one document word by word

What Can Be Known Without a Codebook

InformationWithout a codebookBasis
KindKnownThe section w >> 9 range of the TAG WORD (Reference 0-2, Value 3-4, Edge 5-13, Meta 14-15)
Total record length, position of the next recordKnownLength in the TAG WORD
Codec numberKnownThe TAG WORD (for the Issuer format, the Issuer and codec number in the extended TAG)
Family, classPartly knownOnly the family of an Edge direct code is known from the bits. The family of Value direct codes and Issuer formats, and the Meta class, are not known from the bits. For the Issuer format, the Issuer and codec number are known. The Meta verification class is known from C >= 5 in section 15 (w >= 0x1E50)
Edge Id of an EdgeKnownThe first component of an Edge (sections 5-13) is always a LOCAL Reference
Slot markers (not stated, unknown, none)KnownWORD value 0x0000, 0x0010, 0x0020 (Reference, C < 3, L 0). Slot Markers
QuantifierKnownBy the offset C within the section: in section 0, 5 <= C < 30; in section 1, C < 30; then C % 5
TAG length per Codec, Payload start positionNot knownCodebook
Payload interpretation, roles of Edge componentsNot knownCodebook
  • A decoder without a codebook can skip through records and count them by Kind and Codec, but cannot follow the graph structure.
  • Every decoder must handle the Meta structure, definition, and IMPORT classes. These Codecs belong to the GEUL core codebook, and the decoder knows them from a built-in number table (Meta).

Codebooks are published as GEUL documents (Codec Specification Document). A decoder therefore only needs to fetch and read the specification document it requires.

Region Structure

The upper bits of the TAG WORD divide the space into regions.

PrefixRegionShareDefinition
1Far future50%Reserved (far future). Not used
01Future25%Reserved (near future). Not used
001Standard12.5%Grammar officially adopted and in operation
000Free / proposal12.5%The current grammar. When adopted, the layout stays as is and only the Prefix moves to 001

All of the current grammar is in the 000 region. Every TAG WORD in this specification begins with 000.

  • A v1 decoder rejects any TAG WORD whose Prefix is not 000. The other regions are decided by later editions.
  • The 000 region is a proposal space. No registration or protection applies at present.