Versioning
The contract
Section titled “The contract”manifest.json → formatVersion is the only version a reader has to branch on.
It increases only when a conforming reader of the previous version would get
the file wrong.
Changes that do NOT bump the version
Section titled “Changes that do NOT bump the version”- New keys in any JSON object.
- New entries in the archive.
- New values in an open set — thread catalogue identifiers, entry
roles, parameter sub-objects. - New optional per-object fields whose absence has a defined default.
All of these are safe precisely because of the first compatibility rule: readers ignore what they do not recognise. A reader written against version 1 today will still open version 1 files written years from now, with the features it knows about intact and the rest ignored.
Changes that DO bump the version
Section titled “Changes that DO bump the version”- Removing or renaming an existing key.
- Changing the meaning, unit or coordinate system of an existing value.
- Changing the container in a way an existing reader cannot parse.
There is no minor version number. A file either declares a formatVersion you
support, or it does not.
Additive growth in practice
Section titled “Additive growth in practice”Version 1 has already grown this way. The document model gained groups, a
directionLocked flag per object, and a series of parameter sub-objects for
features that did not exist when the format was published. The manifest gained
the gallery summary fields. None of it moved the version, and a reader from the
first day still opens today’s files.
That is the intended behaviour, not a loophole — and it is why these pages
describe the shape of document.json → params rather than enumerating it.
Revision history
Section titled “Revision history”| formatVersion | Date | Changes |
|---|---|---|
| 1 | 2026-07-11 | Initial public specification. |
Additive clarifications to version 1 are edited into these pages in place. A breaking change adds a row here and bumps the number in every file written afterwards.
Reporting a discrepancy
Section titled “Reporting a discrepancy”If a .hoop file written by StitchPencil disagrees with anything on this site,
the file is right and this text is wrong — the specification documents the
format, it does not define it retroactively. Discrepancies are worth reporting;
they get fixed here.