Skip to main content
FlowPilot tracks two different version numbers. Keeping them straight avoids confusion when you read a flow or debug a resolve response.

​
Two version counters

The content version is bumped by the editor’s migrations as the component model evolves. The wire format version stays at 1 because the on-the-wire JSON shape the SDK parses has not changed in a way that breaks older SDKs. They are not the same number, and that is expected.

​
Editor migrations (content version)

When the editor loads a flow whose version is below 9, it applies migrations in sequence until it reaches the current version. Each migration is small and runs on load (never on save unless you then save the draft). If a flow is somehow ahead of the migration registry (no migration path found), the editor logs a warning and stamps it as the current version without transforming it.

​
Removed and rewritten types

Migrations strip or rewrite types that are no longer in the schema:
  • Stripped from the layout tree on load: carousel, video, chart, spacer, divider (and the old placeholder lottie). The parent stays; only the removed node and its descendants go.
  • Rewritten into a composition of current primitives: checkbox and chip become styled stacks; card becomes a styled stack with surface defaults; legacy button-only prop names map to the canonical ones.
lottie and comparisonChart are supported component kinds in the current schema. The strip in the 3 to 4 migration applied to the earlier placeholder versions of these kinds; the real primitives were added later. See the Component reference for the current list.

​
SDK compatibility (wire format version)

Both SDKs check the resolve response’s schema_version against the highest version they support (1.0.0 in the current iOS and Expo SDKs). They compare the major component only.
  • Same major version: the flow renders. If the minor or patch is newer than the SDK, the SDK renders best-effort and logs a warning. Any component or node type the build does not recognize is skipped rather than failing the whole screen.
  • Higher major version: the SDK throws unsupportedSchemaVersion with the message “Flow requires schema X, but SDK only supports up to Y. Please update the app.” This is the signal that the wire format changed in a way the installed SDK genuinely cannot parse.
This is why additive changes (new component kinds, new props) are safe for old apps: they fall under the same major version and are skipped if unknown. A major bump is reserved for breaking format changes and would require an app update. An unsupported schema version is one of the error codes a FlowPilot SDK can surface (unsupportedSchemaVersion on iOS, UNSUPPORTED_SCHEMA_VERSION on Expo). See error handling for iOS or Expo for how each delivers it (the iOS never-throwing overloads return it as a FlowResult error rather than throwing).

​
Notes

  • The migration chain is what lets you publish over many months without breaking old drafts: opening an old flow upgrades it in the editor.
  • The exact per-version field-level changes beyond the descriptions above are not enumerated here; the migration descriptions above are taken verbatim from the migration registry.