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

> Chronicle Wire is an Apache-2.0 serialisation library from OpenHFT that abstracts the wire format so the same API can read and write human readable text or compact binary, with schema evolution as the design goal. It targets configuration files, in-memory state persistence and fast inter-process messaging between JVMs.

**OpenHFT/Chronicle-Wire** — A Low Garbage Java Serialisation Library that supports multiple formats

- Repository: https://github.com/OpenHFT/Chronicle-Wire
- Website: http://chronicle.software
- Stars: 606 · Forks: 134
- Language: Java
- License: Apache-2.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/openhft-chronicle-wire

## 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.

```xml
<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.

```java
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.

## 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.

## FAQ

### What formats does Chronicle Wire support?

The text formats include YAML as a subset of mapping structures, JSON and CSV as supersets, with XML planned. The binary formats include binary YAML, typed data without fields, raw untyped fieldless data and Trivially Copyable Objects for the lowest latency.

### How does Chronicle Wire handle schema changes?

The documentation says it makes reasonable attempts to handle optional fields, fields in a different order, unexpected fields that can be parsed or ignored, more or less data than expected, and reading a different type than the one written, with automatic updates of fixed length fields where possible.

### What is ReadAnyWire for in Chronicle Wire?

ReadAnyWire reads any format, so it is the option to use when the format of the incoming data is not known in advance. In the wire type table its human readable and self describing columns are marked as either.

### How do I add Chronicle Wire to a Java project?

Add the net.openhft:chronicle-wire dependency to your Maven or Gradle build. The library requires Java 8 or newer, and the version placeholder in the documentation has to be replaced with the release you intend to use.

### What licence is Chronicle Wire released under?

The project is licensed under Apache-2.0, and the repository is published under the OpenHFT organisation with the default branch named ea.

## Sources

- [License: Apache-2.0](https://github.com/OpenHFT/Chronicle-Wire/blob/ea/LICENSE)
- [OpenHFT/Chronicle-Wire on GitHub](https://github.com/OpenHFT/Chronicle-Wire)
- [Project website](http://chronicle.software)
- [README](https://github.com/OpenHFT/Chronicle-Wire/blob/ea/README.md)
- [Releases](https://github.com/OpenHFT/Chronicle-Wire/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/openhft-chronicle-wire