kaiv

The hub for data formats

Every format meets in the middle.

kaiv preserves what JSON, YAML, TOML, XML, CBOR, Avro, Protocol Buffers, and ASN.1 can each say — in one self-describing text form that is simpler than any of them: one line per value, typed, addressed, and validatable by a finite automaton. Pass your data through the hub, or live in it.

Any JSON you have becomes kaiv you can read — and write. It is a superset of .env: keys, sections, arrays, plain text all the way down:

$ kaiv import config.json | kaiv fmt
.!kaiv

(/server)
host=api.example.com
!int
port=8443
!bool
tls=true
()

/server/@tags;=prod;eu

That authored form compiles to the canonical machine artifact — .daiv, one self-contained line per field, type and address included. Registries store it, validators certify it, humans rarely need to look at it:

$ kaiv import config.json | kaiv build
.!daiv
!str'/server::host=api.example.com
!int'/server::port=8443
!bool'/server::tls=true
!str'/server/@tags::0=prod
!str'/server/@tags::1=eu

The two are the same document — kaiv fmt renders any canonical file back in the authored syntax, so the readable form is never more than one command away:

$ kaiv fmt config.daiv
.!kaiv

(/server)
host=api.example.com
!int
port=8443
!bool
tls=true
()

/server/@tags;=prod;eu

The canonical form is the hub — the same document leaves as TOML, XML, YAML, CBOR, Avro, Protocol Buffers, or ASN.1 DER:

$ kaiv export --toml config.daiv
[server]
host = "api.example.com"
port = 8443
tls = true
tags = ["prod", "eu"]

Schemas are inferred from the data you already have, and validation errors name the field, the value, the constraint, and the line:

$ kaiv validate bad.daiv server.saiv
kaiv: ConstraintViolationError: /server::port=99999 (type !int) violates /^-?[0-9]+$/ ..num [1,65535] (line 3)

Values carry what no mainstream format can say — physical units and per-value provenance. One line, five attributions: type, unit, source, time, address:

!float:km/h?gps@20260717T120000Z'/car::speed=120.5

!float :km/h ?gps @20260717T120000Z ' /car::speed = 120.5
 type   unit  src        when            address      value

That is the densest line kaiv can produce, and its whole legend is one page of regular grammar — fixed forever in the spec, not a decoder shipped alongside the data.

And because every line answers for itself, grep is a typed query tool:

$ grep "^!int" config.daiv
!int'/server::port=8443

Values are single-line and nothing is ever escaped — multi-line text travels readable as the !text type, whose |:| separators become real newlines only on export:

$ kaiv import haiku.json | kaiv build
.!daiv
!text'::basho=old pond|:|a frog jumps in|:|sound of water
$ kaiv import haiku.json | kaiv build | kaiv export --json
{"basho":"old pond\na frog jumps in\nsound of water"}

Units are part of the type — bits and bytes included, canonicalized to one spelling, and never silently converted. The famously ambiguous one is refused, with directions:

$ kaiv unit Mbps
Mb/s
$ kaiv unit KB
kaiv: KB is ambiguous: write kB (1000 B) or KiB (1024 B)

The standard type libraries resolve from the registries the toolchain defaults to:

$ curl -s https://t.kaiv.io/std/core.taiv | head -5
.!taiv 1 std/core

// Integer — decimal string with numeric ordering
/^-?[0-9]+$/ ..num
&int=

The same canonical form every time. The same grammar for data, schema, and type library. Only the format at the edge changes.

Coming From…

Nobody arrives from nowhere. Each guide maps the format you already know onto kaiv, recipe by verified recipe — what maps, what you gain, what changes, and an honest section on when to stay where you are:

Your schemas come along too: JSON Schema, XSD, Protocol Buffer, Avro Schema, and GraphQL SDL definitions convert to kaiv schemas under a sound-weakening contract — every emitted constraint is implied by yours, and anything kaiv cannot express is dropped with a comment, never invented, never silently ignored.

What Is kaiv?

kaiv (pronounced “cave”) is a structural type system for data at rest — a ladder of four layers that each stand alone:

• A data format — authored .kaiv compiles to canonical .daiv: flat, ordered, one typed line per value, no nesting, no escaping, no recursion. A regular grammar — the simplest class there is — so parsing is a finite automaton and validation runs in constant memory, properties that admit certification for safety-critical runtimes.
• A type system — one primitive (str) refined by patterns, orderings, and ranges; named types in libraries; physical and currency units as part of the type; per-value provenance a schema can require.
• A schema language — written in the same line grammar as the data it constrains, inferred from examples, compiled to a validation contract.
• A registry — type libraries, schemas, and units published at permanent addresses, cached forever, where the name is the version.

Across the eight formats it converts, kaiv is the union of what each can express individually — the constraint discipline of XSD and ASN.1, the schema-first conviction of Protocol Buffers and Avro, the readability of JSON and TOML — while remaining a single, hand-editable text form. Not a union of what each optimizes for: kaiv is text, and spends bytes where the binary formats spend decoders — the wire formats keep their wire jobs; kaiv keeps the record. Coverage is total for JSON, YAML, TOML, Protocol Buffers, and GraphQL, near-total for Avro and data-interchange XML, and about 95% for ASN.1, with the remainder documented, not hidden.

The name is the design goal. The caves of Lascaux are readable seventeen thousand years on — no decoder ring, no proprietary software; the image is in the medium and the medium is permanent. A .daiv file works the same way: plain text, fully self-describing, as readable in 2040 as today. Write once, read forever — the registries make it a platform contract when they leave alpha.

Quick Start

The reference toolchain is one install away:

cargo install kaiv-cli

Then bring whatever data you have — JSON on stdin will do:

$ echo '{"greeting":"hello, cave"}' | kaiv import --json | kaiv fmt
.!kaiv

greeting=hello, cave

From here, pick the guide for the format you know — each one is a working session, every example a verified transcript of the kaiv tool.

Documentation

Status

kaiv is in alpha. The specification above is the current draft of the 1.0 format; the reference implementation on crates.io implements conformance Levels 0–3 — the full pipeline, the validator, eight import/export formats, five schema converters, schema inference, units, provenance, and collation — and cargo test runs the conformance suite. Every example on this page and in the guides is a verified transcript of the released tool.

In performance and code quality, kaiv is a solid beta. Officially, though, it is in alpha — for two reasons:

1. The eternalink promise. The standard libraries might still get a touch-up here and there: the url type in std/net, for example, is pinned to RFC 3986 exactly — but if an edge case shows up, we want to fix it before std/net becomes an eternalink. Published artifacts can never change, so the promise must not be made a day early.
2. Spec finalization. The spec's core ideas are stable, but as the text is polished for publication we reserve the right to refine syntax before setting it in stone.

Once the spec is finalized, carved in stone, and published, and the standard libraries (types and units) are finalized with it, the registries move from the kaiv.io alpha hosts — where no permanence is promised — to their permanent, immutable homes (ktaiv.com, ksaiv.com, kfaiv.com, kdaiv.com), the write-once, read-forever contract switches on, and kaiv officially becomes beta. We hope community feedback will help us get there faster.