Every publish creates a numbered version of a form, and every record remembers the version it was captured against. That much is covered in the data model. This page answers the question that follows: when you publish version 4, what happens to the records captured under versions 1 through 3?
The short answer: nothing happens to the records. What changes is how they are presented.
Two kinds of change
When you publish, the platform compares the new version against each earlier one and sorts the difference into one of two kinds:
| Change | Kind |
|---|---|
| Add a field | Compatible |
| Remove a field | Compatible |
| Edit a label, help text, or hint | Compatible |
| Make a field required or optional | Compatible |
| Add or remove choices in a list | Compatible |
| Group fields onto a page, or move them off one | Compatible |
| Change a formula, a visibility rule, a default value, or whether a field is hidden | Compatible |
| Change a field's data type (say, text to number) | Breaking |
| Change how a field is answered (say, dropdown to toggle buttons) | Breaking |
Compatible means records captured under the earlier version still read correctly under the new one. The dashboard and the mobile app show them together with new records, as one dataset under the newest version.
Breaking means the new version changed what a field means or how it is captured. Records captured earlier stay on their own versions — still visible, still readable, marked so you can tell them apart. They are not errors, and nothing needs fixing; they are simply history captured under a different shape.
The classification is deliberately cautious. When a change could misread old data, the platform calls it breaking and keeps the versions apart.
Fields are matched by identity, not by name
The comparison tracks each field as a thing, not as a name. If you delete a field and later add a new one with the same name, those are two different fields — answers captured in the old one do not connect to the new one. The form builder warns you when an edit looks like this, so you can undo the delete instead if reconnecting the data is what you wanted.
The same idea applies to list choices: the choice's label is the stored value. Renaming a published choice from "Fair" to "Average" does not rename old answers — records that said "Fair" still say "Fair". The builder warns about this too.
When a record moves to a newer version
Records are never rewritten in place. A record adopts a newer version number only when someone actually edits it under that version:
- A dispatched record that is resubmitted from the field carries the version it was filled under.
- An API update sent with
"schema": "current"checks the whole record against the newest version and moves it there when it fits. - A mobile draft — work not yet submitted — moves up to the newest compatible version when it is opened. A draft on a version with breaking changes stays on its own version, with a note explaining why.
Removed list choices
Removing a choice from a list is compatible, and old answers are not orphaned. A record whose stored answer is no longer among the current choices keeps showing that answer, subtly marked as no longer offered. The answer stays valid — including for a required field — until the user genuinely changes it; from that point only the current choices are offered.
This lets you retire a choice without breaking the records that used it.
Where you see all this
- Before you publish — the publish dialog shows a preview: compatible changes say existing records will appear under the new version; breaking changes say which field caused it and that records stay on their versions. See forms.
- In the records views — records from compatible versions appear together; a filled version badge marks records not compatible with the current version. See records.
- In version history — each version lists what changed since the one before, in plain language, with a compatible-or-breaking badge.
- On the device — compatible older records open under the newest form; others open under the form they were captured with, with a banner. See the mobile app.
- In the API and webhooks — record writes are checked against the right version, and the
form.publishedevent carries a machine-readable summary of the change. See the API conventions and webhooks.
The honest limits
Breaking changes keep datasets apart on purpose — there is no tool yet that maps old records onto a new shape across a breaking change. If you expect to report across a change, prefer compatible edits: add a new field rather than changing an existing field's type.