Skip to content

fix(formulus): record the authored form version on observations #950

Description

@r0ssing

Problem

Observations never record the version of the form they were filled in with. Every new observation is stored as form_version = "1.0", whatever the bundle's schema.json says.

#909 makes FormService read the authored version (schemaVersion, then version, then the 1.0 fallback) for display. The persistence path doesn't carry a version at all, as traced in the comments on #909:

  • formulus/src/webview/FormulusInterfaceDefinition.ts: submitObservation, PersistObservationInput, and FormInitData have no form-version field.
  • formulus/src/services/attachmentStorage.ts: persistObservationWithAttachments calls deps.saveObservation({ formType, data }) without a version.
  • formulus/src/database/repositories/WatermelonDBRepo.ts: record.formVersion = input.formVersion || '1.0' therefore always falls back.
  • formulus/src/services/FormService.ts: addNewObservationImpl hardcodes formVersion: '1.0'.
  • ODE Desktop form preview has the same gap (desktop/src/lib/observation.ts defaults to 1.0.0).

Synkronus already stores and returns form_version end to end, so only the clients are wrong.

Why it matters

Analysts need to know which form version produced each record. Without it, they can't tell observations collected before a question or choice list changed from those collected after. We're about to let AI assistants edit forms through ODE Desktop's ode CLI, with bumping the form version as a required step. That is only meaningful once the version is actually recorded.

Expected behavior

  1. New observations: record the version of the form the session was opened with. Use the same resolution as fix(formulus): use form schema versions instead of calling every form v1.0 #909: schema.json root schemaVersion, then version, then "1.0".
  2. Edited observations: keep the originally recorded version. updateObservation already leaves formVersion untouched, which matches the documented behaviour ("When editing an observation, the form version used to create it is used").
  3. Bridge: resolve the version on the host side, from the FormSpec that opened the session, instead of trusting a value sent by the WebView. This avoids changing the bridge contract. If the bridge must change after all, bump FORMULUS_INTERFACE_VERSION and run pnpm run sync-interface.
  4. ODE Desktop form preview: persists the same resolved version.
  5. Formplayer: currently reads only formSchema.version for drafts and sticky values. Align it with the same resolution, or document that version is the canonical key.

Done when

  • A new observation from a form whose schema.json has "version": "3" syncs with form_version = "3", from both Formulus and Desktop preview.
  • Forms without a version still produce "1.0".
  • Editing an existing observation keeps its original form_version.
  • docs/docs/reference/form-specifications.md → Form Versioning states which key to use and how the version is recorded (see the doc mismatch raised in docs: trace one observation from a form to Synkronus and back #912).
  • Tests cover new, edited, and versionless forms.

Depends on, or should land together with, #909.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions