|
| 1 | +# Editions |
| 2 | + |
| 3 | +Vortex defines an evergrowing set of serializable array encodings, once written this can be read back by any future |
| 4 | +version of vortex. |
| 5 | +**Editions** are used to keep track of these encodings and talk about groups of encodings. |
| 6 | + |
| 7 | +The edition `core2026.07.0` (coming soon) is the first such edition containing all encodings currently |
| 8 | +enabled by the writer. |
| 9 | +Editions are additive so an edition that comes after a previous one contains all the encodings from the previous one |
| 10 | +and more. |
| 11 | +The writer can be configured with a set of different editions (e.g. `core2026.07.0` and `unstable2026.05.0` all stable |
| 12 | +encoding released before July 2026 and all unstable encodings from May 2026). |
| 13 | + |
| 14 | +Editions can be used to constrain your minimum required vortex reader, since latest version over vortex across all |
| 15 | +editions is the earliest version of vortex required to read that file. |
| 16 | + |
| 17 | +## Resolving an unknown-encoding error |
| 18 | + |
| 19 | +If a read failed with an unknown encoding ID and pointed you here, the reader met an encoding |
| 20 | +it does not support. Find the encoding ID in the [registry](#edition-registry) below: |
| 21 | + |
| 22 | +1. **The ID is listed under an edition.** The file is newer than your Vortex build. Upgrade to |
| 23 | + at least that edition's required Vortex release and the file will read. |
| 24 | +2. **The ID is not listed anywhere.** The file was written outside the editions system, with a |
| 25 | + custom, third-party, or experimental encoding. Ask the producer of the file how to read it, |
| 26 | + or register the encoding with your session before reading. Tools that only inspect or |
| 27 | + relocate data (rather than query it) can opt in to `allow_unknown`, which decodes |
| 28 | + unrecognised encodings into inert placeholders. |
| 29 | + |
| 30 | +## Writing with an edition |
| 31 | + |
| 32 | +The default the writer targets a `core` edition lagging the latest vortex release by a few version giving delay before |
| 33 | +writing the latest vortex encodings to disk. |
| 34 | +Every file you write carries the read-forever guarantee. If a file would contain an encoding |
| 35 | +outside the targeted edition, the write fails immediately; edition violations never surface as |
| 36 | +someone else's read error later. |
| 37 | + |
| 38 | +Two knobs exist when the default is not what you want: |
| 39 | + |
| 40 | +- **Pin an older edition** when files must stay readable by deployments running older Vortex. |
| 41 | +- **Opt in to additional edition families.** Editions come in independently versioned, |
| 42 | + additive families — `core` today, with families for more specialised encoding groups (for |
| 43 | + example spatial encodings) possible later. A writer targets at most one edition per family |
| 44 | + and may emit any encoding in their union; each encoding belongs to exactly one family. |
| 45 | + |
| 46 | +You can also opt out of editions entirely to write custom or experimental encodings. Doing so |
| 47 | +is an explicit choice that gives up the standardization guarantee — only readers that know your |
| 48 | +encodings can read those files. |
| 49 | + |
| 50 | +## How editions change |
| 51 | + |
| 52 | +A published edition is frozen — its encoding list never grows or shrinks. New encodings are |
| 53 | +staged in a **draft** edition and become guaranteed only when that draft is frozen as the next |
| 54 | +edition; each encoding's registry entry records the edition it joined in. In the future an |
| 55 | +encoding may be *deprecated*, meaning writers stop emitting it — but readers keep decoding it |
| 56 | +indefinitely, so deprecation never invalidates existing files. |
| 57 | + |
| 58 | +## Edition registry |
| 59 | + |
| 60 | +Coming soon.. |
0 commit comments