iKv Format
iKv stores a named tree of objects, arrays, strings, signed integers, double-precision floating-point numbers, booleans, and null values. The same logical tree can be represented as text or binary.
Versions
| Version |
Text tag |
Binary magic |
Notes |
| iKv1 |
ikv1 |
iKv1 |
Sequential binary root encoding |
| iKv2 |
ikv2 |
iKv2 |
Indexed binary object root with lazy top-level loading |
Generic read functions inspect the input and select the correct loader. Generic writes use iKv2. Use ikv::Version::v1 only when an older consumer requires it.
Data model
| iKv type |
C++ API type |
Meaning |
| null |
ikv::nullValue |
No scalar payload |
| string |
ikv::stringValue |
Length-delimited byte string; text uses quotes |
| integer |
ikv::intValue |
Signed 64-bit integer |
| float |
ikv::realValue |
IEEE-754 double |
| boolean |
ikv::booleanValue |
true or false |
| object |
ikv::objectValue |
Key/value mapping |
| array |
ikv::arrayValue |
Ordered values, optionally typed |
Root model
Normal document roots are named objects:
iKvxx supports object and array roots in memory. The indexed iKv2 binary writer requires an object root. The C++ wrapper rejects scalar root construction.
Object semantics
- Keys are strings.
- Assigning the same key again replaces its value.
- Object order is not a stable semantic property. Do not depend on write order.
- Missing-key lookup returns a null handle in iKvxx.
Array semantics
Arrays retain insertion order. An array has an element-type marker:
null marker: mixed/untyped; each binary item carries its own type tag.- Scalar or object marker: typed; binary items omit repeated type tags.
- Text parsing infers a common type when all non-null elements agree, otherwise the array becomes mixed.
See Text Format and Binary Format for wire details.
Compatibility rules
- Readers validate text version tags and binary version fields.
- iKv1 and iKv2 share the same logical types and text grammar.
- iKv2 binary top-level keys are indexed and loaded on first lookup.
- Unknown, malformed, truncated, or version-mismatched binary input is rejected.
- Explicit version output is available through all write/encode methods.