Compatibility matrix

The matrix shows which wire formats each library can write, which the target edition permits, and which each reader supports. The names are illustrative rather than actual Vortex versions or editions:

• Format A and Format B have distinct wire IDs and contracts, with Format A introduced first.

• Library 1 reads and writes only Format A.

• Library 2 reads and writes both formats through one array implementation.

• Edition 1 permits only Format A, whereas Edition 2 permits both formats.

Both readers are assumed to support all other components in the file. Unsupported means that the writer has no implementation for that format, whereas Forbidden means that the target edition excludes it. Allowed means both requirements are met, but the writer must still construct an array that the format can represent. Reader results apply only after a successful write.

Writer	Target edition	Format	Write result[1]	Library 1 reader	Library 2 reader
Library 1	Edition 1	Format A	Allowed	Reads	Reads[2]
Library 1	Edition 1	Format B	Unsupported and forbidden	N/A	N/A
Library 1	Edition 2[3]	Format A	Allowed	Reads	Reads[2]
Library 1	Edition 2[3]	Format B	Unsupported	N/A	N/A
Library 2	Edition 1	Format A	Allowed[4]	Reads	Reads[2]
Library 2	Edition 1	Format B	Forbidden	N/A	N/A
Library 2	Edition 2	Format A	Allowed[4]	Reads	Reads[2]
Library 2	Edition 2	Format B	Allowed[4]	Unknown ID	Reads

The serializer selects a format from the array’s structure, after which the writer checks whether the target edition permits it. The format column shows that selection, not a separate writer setting. Edition 2 permits both formats, so a writer targeting it can still produce Format A for Library 1 to read.

Compatibility checks

The diagram follows an array from memory to storage and back through the serializer and reader plugins. It assumes correct implementations, edition checks enabled, and full decoding with allow_unknown disabled.

The writer selects a plugin by the array’s in-memory ID, whereas the reader selects a plugin by the stored wire ID. In either direction, the plugin can adapt the array structure while preserving values, data types, and nulls. The diagram groups related checks, although in the implementation component checks occur at several points during writing and reading.

If the serializer returns a forbidden ID, the write fails without retrying a different permitted ID. When the target requires a different encoding, the array must be recompressed before serialization. See Format selection.

The matrix assumes valid serialized data, whereas the diagram also shows the reader rejecting data that violates the stored ID’s contract. Format compatibility does not prevent I/O errors.

The component checks cover arrays and their children, layouts, extension types, and stored aggregates. The reader needs implementations for the components the file uses, not every component its edition permits. See Unknown IDs for missing implementations and the exceptions available with allow_unknown.

For the compatibility guarantee and minimum reader versions, see Versioning. The design explains the invariants behind these outcomes.

---

[1]

An input array can require a format that the target edition forbids. A serializer can adapt metadata, buffers, or children without recompression, but compatibility can require a different encoding. In that case, the array must be recompressed before serialization or the write fails.

[2] (1,2,3,4)

Library 2 reads Format A into its own array implementation, adapting the structure only if necessary. A library upgrade alone does not require an array conversion.

[3] (1,2)

Library 1 needs Edition 2’s declaration to select it. Registering the declaration does not add support for Format B, so Library 1 still writes only Format A.

[4] (1,2,3)

The default compressor filters schemes by their declared output wire IDs, but general per-writer scheme configuration is not implemented. The planned configuration would select compatible behavior before estimation, sampling, and full compression, avoiding recompression solely to meet the edition. These cells still require the writer to construct a permitted representation. See Compression for the current behavior and planned work.