A Markdown version of this page, optimized for AI and LLM tools, is available at https://www.bovnar.io/index.md

unit-safe / spec v1.1 / c99

Unit-safe serialization
for science and industry.

Every value carries its width, base, and physical unit inline — no schema, just human-readable text. A bare 9.81 is never ambiguous, and a mismatched unit is a parse error.

Get Started Why Unit-safe?

bovnar — telemetry.bvnr

◆ telemetry.bvnr

# Every measurement carries a validated unit
.host   = "api.sensors.io";
.mass   = 142.6 k~g;
.sensor = {
    .pressure = <float:32,k~Pa> 101.325;
    .velocity = <float:64,m/s> 9.81;
};
.matrix = [1,2,3]/[4,5,6];

◈ BOVNAR

UTF-8 Ln 8, Col 1 unit-safe

scroll

One format, end to end — config in, decoded values out.

You saw the syntax — here's a spacecraft running on it. One format, the whole loop: config in, telemetry out. Edit the orbit; the craft encodes each measurement into a .bvnr frame and the ground station decodes it — the orbit you see is drawn only from those decoded values, a full round-trip through the format. Units, bit-widths, and types ride inside the stream; no schema required. Hover any gauge to light up the line it was decoded from.

Every frame is parsed by the C reference implementation itself, compiled to WebAssembly and running live in your browser — the exact bvnr_read() that ships in the native library, not a JavaScript re-implementation. The same engine drives all three demos and the playground below.

How it works — the full round-trip

The config on the left isn't a form — it's a real .bvnr document you can edit freely. Nothing changes until you press Apply.
When you do, it's read straight from the text. If something doesn't make sense, you get a friendly error pointing at the line, and the live view keeps running on the last good config — a bad edit can't break it.
Those values set the scene, and the demo takes it from there.
From then on, every reading is written out and read back as .bvnr, the same format you just edited — units and types travel right alongside the numbers.
So the gauges and charts show only what came back through the format, never a number taken on faith. Flip on the noise and you can watch it shrug off a garbled frame.
Hover any gauge to light up the exact line it was read from.

every number you see travels:
edit→parse→simulate→encode→(corrupt?)→parse→display

The three demos drive the C reference parser compiled to WebAssembly, so they need JavaScript and are hidden here. Nothing else on this page does: the syntax, the annotated examples and the full documentation below are plain markup. The same parser ships as a C library, a Python package and the bovnar command-line tool.

Spacecraft config editable · .bvnr

Orbit visualizer ECI · XY projection

◐ Earth (day / night) ● spacecraft (decoded pos)

Downlink frame .bvnr stream

160× noisy channel resync

frame 0 MET 0 s orbits 0.00 dropped 0 lock ACQ

With resync on, a corrupt assignment is skipped and the rest of the frame still decodes — the reader's recovery mode. Off, one bad line drops the whole frame. Flip noisy channel to compare.

Instrument config editable · .bvnr

Price ACME · USD

6× noisy feed resync

― last ┄ EMA ▲ buy · ▼ sell ▒ bid/ask

Market-data feed .bvnr tick

tick 0 rate — dropped 0 lock ACQ

resync on: a corrupt field is skipped and the rest of the tick still decodes. Off: one bad line drops the whole tick. Flip noisy feed to compare.

Blotter & ledger decoded

Ledger — exact decimal vs naïve binary float

Fees · Bovnar float_dec$0.00

Fees · naïve float32$0.00

Mark P&L · Bovnar exact$0.00

Mark P&L · naïve float32$0.00

Float error (and counting)$0.00

Same numbers, two pipelines. Bovnar's exact decimal text → integer minor units (penny-perfect). A binary-float book drifts. That gap is real money.

Reactor config editable · .bvnr

Process — jacketed reactor PID temperature loop

6× scaling mismatch noisy bus resync

▮ jacket heat ― temp · ┄ setpoint ✚ impeller ◔ pressure

PLC telemetry .bvnr frame

cycle 0 rate — dropped 0 lock ACQ

resync on: a corrupt register is skipped and the rest of the frame still decodes. Off: a bad line drops the cycle. Flip noisy bus to compare.

HMI — gauges & alarms decoded

Temperature register — raw Modbus vs self-describing Bovnar

Raw register · uint:16—

Naïve decode · assumed scale—

Bovnar · float_fix:16,q8,°C—

Verdictscaling matches

The register is a bare 16-bit integer — its Q-scaling and unit live in a manual, out of band. Toggle scaling mismatch: the naïve poller applies the wrong Q-factor and reads a false over-temperature; the Bovnar frame carries the type inline, so it can't be misread.

live parser

The real event stream.

This is the reference C reader's on_verified callback stream, running live in your browser — the unmodified C core compiled to WebAssembly, not a JavaScript re-implementation. The same events, in the same order, that bvnr_read() delivers. Bare values get the validator's synthesised default annotation; type, range, base, and unit violations surface on the separate on_error channel, exactly as the C core reports them.

The playground parses what you type with that same WebAssembly build, so it needs JavaScript and is hidden here. To get the identical event stream offline, run bovnar events yourfile.bvnr from the command-line tool.

Editor Tab indents · Shift+Tab or Esc leaves

ready

on_verified · event tree 0 events

◈ Events appear here as you type.

on_error

no errors

the core idea

The context travels with the number.

In science and industry the costly failures are rarely bad syntax — they are unit confusion: pounds-force read as newtons, feet as meters. The number parses fine; the 9.81 is right but the context is wrong. Bovnar keeps that context — width, base, and unit — inline with every value, as plain human-readable text with no external schema, and rejects a mismatched unit as a parse error rather than a silent bug.

a number, no context

9.81

Width? Base? Unit? Anyone's guess without an out-of-band schema or naming convention.

→

a value, in context

.thrust = <float:64,k~g·m·s⁻²> 9.81;

Type, width, and unit ride inline, in the same byte stream as the value. No schema, no codegen, no lookup table.

01 Bit-width

<uint:16> 443

Exact storage width, declared inline and never inferred — from a single bit to thousands. A uint:16 stays exactly 16 bits: it can't silently widen to 64, or be reinterpreted as a float.

02 Numeric base

<uint:32,_2> 11001010

Binary, hex, or decimal — the radix is declared, so 11001010 is never mistaken for a decimal value. Values whose digits include letters (e.g. hex ff) are written as quoted strings: <uint:_16> "ff".

03 Physical unit

<float:64,k~g*m*s^-2> 1.0

SI base & derived units, IEC binary prefixes, and compound expressions — validated by the parser, not by your application. Exponents accept a Unicode superscript (s⁻²) or a plain-ASCII caret (s^-2) interchangeably.

Typing it by hand? Both notations are first-class to the parser — a Unicode-superscript form (s⁻², m²) and an all-ASCII form that uses a caret for the exponent and * in place of the · separator. k~g*m*s^-2 and k~g·m·s⁻² parse to exactly the same unit. The ASCII form needs no obscure glyphs, so it's the natural choice for hand-authoring .bvnr. The writer emits Unicode superscripts by default, or the caret form when you set BVN_UNIT_ASCII_EXP.

All of it is optional: omit annotations for well-defined defaults (uint:64, float:64), or add them for full parser validation. Both modes are unambiguous — and a .bvnr file stays plain UTF-8 text you can read in any editor, no toolchain required.

syntax

The grammar of precision.

Every assignment is a declaration: the annotation is part of the value, not a note about it.

Typed Values

type · width · unit

# Integers .port = <uint:16> 443; .offset = <sint:64> -2147483648; .flags = <uint:32,_2> 11001010; # Floats with SI units .temp = <float:32,°C> 36.6; .speed = <float:64,m/s> 9.81; .force = <float:64,k~g*m/s^2> 1.0; .buffer = <uint:64,Mi~B> 16;

Structures & Arrays

nested · multidimensional

# Nested struct .sensor = { .id = <uint:16> 7; .name = "pressure_01"; .val = <float:32,k~Pa> 101.325; }; # 3×3 rotation matrix (rows separated by /) .rotation = [1.0, 0.0, 0.0]/ [0.0, 1.0, 0.0]/ [0.0, 0.0, 1.0];

<family:width,unit>

Type Annotation

Eight families: uint sint float float_fix float_dec utf8 bool datetime (datetime is spec 1.1). Width in bits. Unit in SI notation. All are optional.

k~g*m*s^-2

Compound Units

SI base and derived units, IEC binary prefixes, compound expressions. Units are validated by the parser. No external schema needed.

\x00 … \x00

Octet Streams

Raw binary embedding without Base64 overhead. Framed by null bytes. Text and binary payloads coexist in the same document.

capabilities

Built for exactness.

Type System

Strong, optional typing

Eight type families. The numeric ones take an explicit bit-width, and uint, sint, and float a numeric base. Defaults are defined, not guessed. Annotate when precision matters; omit when it doesn't.

<uint:16> 443 <float:32,_16> "1.0p+0" <sint:64> -9223372036

SI Units

First-class physical units

All seven SI base units, 22 derived SI units, and IEC binary prefixes. Compound units, exponents, and prefix enforcement are built into the grammar.

<float:64,k~g*m*s^-2> 1.0 <uint:64,Gi~B> 16 <float:32,m/s^2> 9.807

Streaming

SAX-style incremental reader

Parse from memory, file descriptor, or socket via a symmetric on_unverified / on_verified callback pair. No heap allocation during parsing itself.

bvnr_open_read_source( r, &src, NULL, &opts); bvnr_read(r);

Resilience

Error recovery & resync

Optional resync mode skips broken assignments and continues parsing. It suits log streams, unreliable transports, and long-running telemetry.

opts.continue_on_error = true; /* parser skips broken record, continues with the next */

DOM API

Tree-based access

Build a navigable DOM from any Bovnar stream, then traverse, query, and mutate it with a clean C API. Or use the Python dict-like interface.

bvn_dom_lookup(doc, ".sensor.val"); doc["sensor"]["val"] # Python

Python

Pure-ctypes + NumPy bridge

No compiled extension. No Cython. A full high-level / streaming API — plus a zero-glue NumPy bridge that loads typed arrays straight into an ndarray with the physical unit attached.

bovnar.to_numpy(arr, return_unit=True) # → (ndarray float64, 'm/s²')

quick-start

Up in minutes.

Read from memory

#include "bovnar.h"

static bool on_event(void *ud, bvnr_event_t ev,
                     bvnr_data_t *d)
{
    if (ev == ev_data)
        printf("val=%.*s\n",
               (int)d->length,
               (const char *)d->data);
    return true;
}

int main(void)
{
    const char *src =
        ".velocity = <float:64,m/s> 9.81;";
    bvnr_read_flags_t opts = {0};
    opts.on_verified = on_event;
    bvnr_reader_t *r = bvnr_reader_create();
    bvnr_open_read_mem(r, src,
                       strlen(src), NULL,
                       0, &opts);
    bvnr_read(r);
    bvnr_reader_destroy(r);
}

Write typed values

High-level write helpers accept a key string and a typed value directly. The output is emitted with the correct annotations.

#include "bovnar.h"

int main(void)
{
    char buf[256];
    bvnr_writer_t *w = bvnr_writer_create();
    bvnr_sink_t sink;
    bvnr_sink_to_mem(&sink,
                     (uint8_t *)buf,
                     sizeof(buf));
    bvnr_open_write_sink(w, &sink,
                         true, NULL);

    bool ok;
    value_unit_t u = bvn_parse_unit(
        (const uint8_t *)"m/s", &ok);
    bvnr_write_float_unit(
        w, "velocity", 64, 9.81, u);

    bvnr_write_finish(w);
    uint64_t n = bvnr_writer_bytes_written(w);
    bvnr_writer_destroy(w);
    fwrite(buf, 1, (size_t)n, stdout);
    // → .velocity = <float:64,m/s> 9.81e+0;
}

High-level API

Dict-like loads / dumps interface. Pure-ctypes — no compiled extension required.

import bovnar

data = {
    "sensor_id":   42,
    "temperature": 36.6,
    "unit":        "celsius",
}
raw = bovnar.dumps(data)

doc = bovnar.loads(raw)
print(doc["sensor_id"])    # 42
print(doc["temperature"])  # 36.6

Streaming event API

Full control over parse events. Inspect units, type annotations, and raw string representations as they arrive.

from bovnar import Reader, Event, unit_to_str

def on_event(ev, data):
    if ev == Event.DATA:
        u = data.value_unit
        if u.num_components:
            print(data.raw_str(),
                  unit_to_str(u))

src = b".velocity = <float:64,m/s> 9.81;"
Reader().read_mem(
    src, on_verified=on_event
)
# → 9.81 m/s

Typed round-trips with Quantity

loads(typed=True) wraps each typed value in a Quantity that preserves its exact text, bit-width, and unit. Pass the dict directly back to dumps() for a lossless round-trip.

import bovnar

src = b".pressure = <float:32,Pa> 101325.0;"
doc = bovnar.loads(src, typed=True)

q = doc["pressure"]
# Quantity('101325.0', FLOAT [Pa])
print(q.raw)         # '101325.0'
print(q.unit_str()) # 'Pa'

# dumps() re-emits annotation + raw text unchanged
out = bovnar.dumps(doc)
assert bovnar.loads(out, typed=True) == doc

NumPy bridge

Typed arrays load straight into a numpy.ndarray — Bovnar widths map to native dtypes (float:32 → float32) and the whole-array unit rides alongside. NumPy is an optional, lazily imported extra (pip install "bovnar[numpy]").

import bovnar, numpy as np

src = b".accel = <float:64,m/s^2> " \
      b"[9.81,0.02,-0.05]/[0.05,9.80,0.01];"
doc = bovnar.loads(src, typed=True)

a, unit = bovnar.to_numpy(
    doc["accel"], return_unit=True)
# a.shape == (2, 3)  a.dtype == float64  unit == 'm/s²'

g = np.linalg.norm(a, axis=1)   # vectorized, per row
out = bovnar.array_to_bvnr("g_mag", g, unit=unit)
# → .g_mag = <float:64,m/s²> [9.810…, 9.800…];

Build the library

Requires CMake ≥ 3.21 and a C99-conforming compiler. There are no external dependencies, at build time or runtime — not even libm.

# Clone and build
cmake -B build .
cmake --build build

# Release build
cmake -B build \
  -DCMAKE_BUILD_TYPE=Release .
cmake --build build

# Outputs:
# build/libbvnr.a
# build/libbvnr.so
# build/bovnar  (CLI)

Link & test

The test suite includes unit tests, socket-pair round-trip tests, and fuzz harnesses. Benchmarks run from the CLI with bovnar bench.

# Link your app
gcc my_app.c \
  -I include \
  -L build \
  -lbvnr \
  -o my_app

# Run tests
cd build && ctest \
  --output-on-failure

# Python tests
export LIBBOVNAR_PATH=\
  $(pwd)/build/libbvnr.so
cd python && pytest tests -v

best for

When a wrong unit is a failure.

Reach for Bovnar when units must travel with the data and the receiver may not share a schema. Every measurement is unit-safe by construction — a mismatched unit is a parse error, not a silent bug discovered in production.

Scientific instrumentation & metrology

Readings stay self-describing from the lab bench to the published dataset — width, base, and physical unit ride along with every value.

Industrial telemetry & control

Pressures, flows, and temperatures cross process boundaries without a shared contract, and dimensional mismatches are caught at the parse step.

IoT sensor networks

Heterogeneous devices emit human-readable, type-precise records that any consumer can validate on its own, no central registry required.

Long-term measurement archival

Data written today still means exactly the same thing decades from now — the meaning lives in the file, not in lost tooling.

documentation

Everything you need to ship.

Thirteen documents — from a five-minute tutorial to the formal EBNF grammar and conformance protocol. Read inline below, browse them as standalone pages, or download the full set as PDF.

Tutorial

Practical introduction for developers. Get productive with Bovnar in minutes.

Start here

FAQ

Common questions on the format, type system, units, C API, Python bindings, and operational limits.

Common questions

Specification (v1.1)

Full lexical and syntactic grammar, type system, arrays, structs, octet streams, and validation rules.

Format authority

Units & Currencies Cheat Sheet

All 180 physical units, 166 fiat currencies, and 50 cryptocurrencies. SI/IEC prefixes, compound expressions, and symbol disambiguation.

Quick reference