Chronicle Wire lets one Java object speak YAML, JSON, CSV and binary

The API is the same, the format is the variable

Chronicle Wire is described as a high-performance, zero-GC serialisation library built on top of the Chronicle stack, and its central idea is stated plainly: it abstracts the underlying wire format so you can use human readable text or compact binary interchangeably while keeping a common API. The typical use cases listed are configuration files, persistence of in-memory state, and extremely fast IPC between JVMs. The key features list names multiple wire formats in YAML, JSON, CSV and binary variants, schema evolution with optional field handling, low-latency and low-allocation serialisation of Marshallable POJOs, automatic conversion between formats, and integration with other Chronicle components. A design principle underneath is the separation of describing what data you want to store and retrieve from how it should be rendered and parsed, which is what makes the same object class work in a human edited YAML file and in a fixed width binary buffer.

The wire type table is the API you will actually use

Choosing a format is done through the WireType enum, and the documentation tabulates every option with three columns that matter: whether the format is human readable, whether it is self describing, and its size and latency profile. TextWire is enum TEXT, human readable, not self describing, and described as more compact than JSON, and it is YAML based. YamlWire and YamlWire's YAML_ONLY variant and CSVWire are all human readable and not self describing, and CSVWire is also described as YAML based. JSONWire and JSON_ONLY are human readable with microsecond latencies, with the former using a 4-bit length prefix and the latter using new lines between messages. BinaryWire comes in three flavours, BINARY, BINARY_LIGHT and FIELDLESS_BINARY, all not human readable, all self describing, and all described as having better performance than YAML at half the latency, with BINARY_LIGHT behaving the same as BINARY and FIELDLESS_BINARY carrying no field metadata. RawWire writes just the data without metadata and is described as more compact than BinaryWire. ReadAnyWire has a dash in the readable and self describing columns, meaning it can be either, and it reads any format. That last one is the practical answer to the question of what happens when you do not know the format of the bytes in front of you.

Schema evolution is a list of specific behaviours, not a promise

The documentation is unusually concrete about what changing a schema does to old data, and this is the section to read before committing. Chronicle Wire states that it should make reasonable attempts to handle optional fields, fields in a different order, and fields the consumer does not expect, optionally parsing them or ignoring them. It also covers more or less data than expected in field-less formats, and reading a different type to the one that was written, which is what you need when an enum or an object is stored by name. Fixed length fields can be updated automatically where possible using a bound data structure, and dynamic updates of enums or objects passed by name are supported. Efficiency is conditional on the other side of that trade: the library is efficient where fields arrive in the expected order, are the expected type, and where field names or numbers are not needed at all, and where self-describing types are unnecessary and random access of data values is supported. In other words, the format that is friendliest to a reader is not the format that is fastest to consume, and the same library gives you both.

Text and binary differ in more than the bytes on the wire

The text formats are a subset of mapping structures for YAML, supersets for JSON and CSV, with XML planned. The options for text are field names as in JSON or field numbers as in FIX, optional fields with default values that can be dropped, and then two features listed as planned rather than shipped: zero-copy access to fields, and thread-safe operations in text. That last point is the important one for anyone planning to use text formats in a concurrent system. The binary formats are richer. They include binary YAML, typed data without fields, raw untyped fieldless data, and Trivially Copyable Objects described as the lowest latency option. Binary options include field names or field numbers, variable width, optional fields with a default value that can be dropped, fixed width data with zero copy support, and thread-safe operations. Chronicle Wire also supports debug and transparent combinations, such as self-describing data with zero copy support. Format discovery is mechanical: for text the first byte should be in the ASCII range, adding an ASCII whitespace if needed, and for binary the first bytes should have the top bit set.

Configuration is the case the library is designed around

The documentation devotes a section to why configuration concerns are conflated, and the answer is that you often want to use the formats interchangeably. Configuration includes aliased type information, which supports easy extension by adding new classes or versions and cross-platform use through type aliasing. By supporting types, a configuration file can bootstrap itself, and you control how the configuration file is decoded. The listed situations are sending the configuration of a server to a client or the other way round, storing the configuration of a data store in its header, being able to create any object or component in a configuration, saving a configuration after it has been changed, and sharing data in memory between processes in a thread-safe manner. That last two are the ones that pull a serialisation library towards being a configuration system, and they are the reason a self-describing format is worth its overhead in a file a human may edit.

The build is Maven, and the API is two calls

The dependency is added the usual way, and the version is a placeholder in the documentation, which is a hint to check the release naming before you pin it.

<dependency>
    <groupId>net.openhft</groupId>
    <artifactId>chronicle-wire</artifactId>
    <version>REPLACE_WITH_VERSION</version>
</dependency>

Gradle users get the same coordinates in one line. The simple example then shows the shape of the API: allocate elastic on-heap bytes, apply a wire type to them, and write.

Bytes<?> bytes = Bytes.allocateElasticOnHeap();
Wire wire = WireType.TEXT.apply(bytes);

wire.write("message").text("Hello World");
System.out.println(bytes.toString());

The pattern to notice is that the wire type is applied to a buffer, so the same buffer can later be read with a different type, which is what makes converting between formats possible. A buffer can be a byte array, a ByteBuffer, off-heap memory, or even an address and length obtained from some other library, so Chronicle Wire can sit on top of memory it does not own. The library requires Java 8, and support for C++, ruby and python is stated to be available in Chronicle Queue Enterprise rather than in this project, which is a detail worth checking before you plan a mixed-language deployment.

Editorial conclusion

Chronicle Wire suits Java teams that need one serialisation API across text and binary formats, particularly for configuration, persisted state and low latency IPC between JVMs, and it suits anyone whose data model changes and must still be readable by older readers. It does not suit teams that want a plain object mapper with no format concept, and it does not suit applications that cannot accept a JVM dependency in the wire format path. Before adopting it, add the Maven dependency, try the simple Bytes and WireType example, and confirm the version you pick matches the chronicle-2026.x release naming rather than assuming the old 2.x scheme, since both appear in the release history.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. OpenHFT/Chronicle-Wire on GitHub
3. Project website
4. README
5. Releases