GBLN A typed, bounded record format The type travels with the value

Before the argument, the facts

Two version numbers, and they are not the same claim. The specification is at 1.0 and marked final: the grammar, the type system and the parsing rules are settled, and a file written against them will read the same in five years. The tooling is at 0.9.0, which is the core, the command line and the bindings, and that number is the honest one for software that has not yet had its first public release. The Verbund runs on it: every ticket, every knowledge entry and every roadmap hop behind this site is a GBLN record, which is either a recommendation or a conflict of interest depending on your temperament. So does ZERVO+, whose backup archives are described by a GBLN manifest read before a single byte is unpacked, and which carries its own reader for the format rather than taking on a JSON dependency to describe itself.

The source is at ProVivianVossNet/gbln, Apache-2.0, with the specification, the Rust core, the C FFI and every binding in one tree: one clone brings the lot, which is the arrangement a format wants if it would like to be picked up by somebody who has not met it before.

The argument, in seven steps

• OneThe type is in the fileBeside the value, not in a schema kept somewhere else.
• TwoThe bound is in the types32 is thirty-two characters, and the parser knows it before it reads one.
• ThreeThree rules, one character aheadThe next character decides the structure. No backtracking, no ambiguity.
• FourTypes where you want themStart untyped, add types field by field, mix both in one file.
• FiveTwo forms, one meaningAn editable source and a compact wire form, with nothing lost between them.
• SixWhat it costs in bytesLevel with JSON minified, and a third of it once compressed.
• SevenOne core, fourteen languagesRust and a C FFI, with twelve bindings that all behave the same.

Then, for reference

• TableEvery typeRange, width and what each one is for.
• NumbersThe benchmark in fullFour formats, one hundred records, and the caveat that matters.
• EdgesWhere it stopsWhat the format leaves to somebody else, and why.

A schema kept elsewhere is a schema kept badly

The usual arrangement puts the data in one file and its rules in another, and asks everybody involved to keep the two in step. They do, mostly, until the afternoon somebody adds a field in a hurry. GBLN puts the type where the value is, so the pair cannot drift apart: there is nowhere for them to drift to.

    :| config.gbln, for people and for git
    server{
        host<s64>(api.example.com)
        port<u16>(8080)
        workers<u8>(4)
    }
        

Three things are declared and all three are checked as the file is read. host is a string of at most sixty-four characters. port is an unsigned sixteen-bit number, so nought to sixty-five thousand five hundred and thirty-five, and a port of seventy thousand is refused at the gate rather than four hours later by something further down the pipe. workers fits in a byte.

The gain is not that these checks exist. Every ecosystem has a validator somewhere. It is that they are not a separate step somebody can forget to run, and that the answer to "what shape is this file" is the file.

Which raises the next question: a type says what a value is. What says how much room it will take?

The next character decides everything

A record is one of two shapes and the character after the identifier says which. An angle bracket opens a typed terminal value; a brace opens a container. That is the whole of it, and it is why a parser needs to look exactly one character ahead and never has to change its mind.

    identifier<type>(value)   :| terminal: one value, checked against its type
    identifier{ … }            :| container: further records inside
        

The third rule is the comment. :| runs to the end of the line and is stripped before anything else happens, which is why the sequence is reserved and cannot appear anywhere else. It is also, read sideways, a face keeping a straight one, and it is the format's own mark. A comment is after all the one place in a file where a program is entitled to have an opinion and keep it to itself.

What follows from three rules is duller than it sounds and more useful than it looks. There is no significant whitespace to get wrong, no quoting mode to escape out of, no construct that means one thing here and another there. Two parsers written independently agree, which is a lower bar than it ought to be and one that several popular formats do not clear.

Determinism is a fine thing for a machine. What does it ask of a person starting out?

Nothing insists you decide today

The type is optional. A field may carry one, and a field beside it may not, in the same file, at the same nesting level, with no ceremony about the difference. So a first draft can be written as quickly as JSON and tightened afterwards, field by field, wherever it turns out to matter.

    service{
        name(orders)              :| untyped, and perfectly legal
        port<u16>(8080)            :| typed, because this one has bitten before
        region<s2>(de)             :| two characters, no more
    }
        

This is the part that is genuinely unusual. JSON has no types to add. Protobuf and its relatives want them everywhere before you may write anything at all. GBLN lets the strictness follow the understanding, which is the order those two things actually arrive in.

One file, then, for people. Is it also the file that goes over the wire?

Level with JSON, and a third of it compressed

One hundred employee records, nested, measured as files rather than argued about. The wire form before compression comes to 49,276 bytes against JSON minified at 49,466: a difference of about a hundred and ninety bytes, which is to say none. Compressed, the same records are around 16,500 bytes, a third of the JSON.

One hundred nested employee records, the same data in every format, sizes taken off the files. The compressed figure is XZ, which JSON would also benefit from; the comparison there is between a format that ships with the compression arranged and one where you arrange it yourself.

Now the part that a marketing page would leave out. Against minified JSON the byte saving is essentially nothing, and the format's own README says so in as many words. What is bought for those same bytes is the type check, the bound and the deterministic parse. The argument is reliability at the same price, not a smaller file.

The token figure belongs to a different question. In a model context, where structure is repeated and every repetition is charged, the compact form runs about eighty-six per cent below JSON. That is a claim about prompts and retrieval systems rather than about disks, and it is the reason the format exists at all.

Fine on one machine. What about the other twelve languages in the building?

Fourteen implementations would be fourteen dialects

A format with an implementation per language has a specification in name and a committee in practice: each parser is a little more forgiving than the last, in a slightly different direction, and the file that works everywhere is the intersection nobody documented. GBLN has one core in Rust and a C FFI beside it, and twelve bindings that call into it rather than reimplementing it.

The count is worth a sentence because the project's own README gets it wrong: it says thirteen and then lists fourteen. The directory settles it, and this page follows the directory. It is a small thing, and a page about a format that refuses unvalidated data would look silly repeating a number it had not checked.

Six platform targets, each in two architectures: FreeBSD, Linux, macOS and Windows on x64 and ARM64.

Every type, and what it is for

The full set, from the specification. Nothing here is inferred: a type either appears in the grammar or it does not exist.

Four formats, one hundred records

In the source form, which is the one under version control, GBLN comes to 66,273 bytes against JSON at indent two on 79,394: seventeen per cent smaller, with the types included. TOON and YAML are smaller again in that column, and carry neither types nor bounds.