Skip to content

Migrate from OpenMed 2.5 to 3.0

OpenMed 3.0 adds a versioned longitudinal Journey layer while preserving the local-first privacy boundary. Migration is an explicit data and contract operation; loading older records does not silently grant them v3 provenance, identity, consent, or review semantics.

This guide covers technical migration. It does not establish clinical validation, regulatory certification, or authorization for autonomous clinical action.

Before migration

  1. Pin the existing OpenMed package, model artifacts, tokenizer, policies, vocabularies, and database schema.
  2. Export aggregate counts and digests for the source installation.
  3. Back up the source store and test restore on an isolated system.
  4. Inventory restricted models, datasets, and vocabularies. Keep them user supplied; do not copy them into the package or release fixture.
  5. Record the intended v3 schema version, compatibility policy, storage backend, namespaces, consent policy, and retention policy.

Contract changes

V3 public and persisted Journey objects declare:

  • semantic schema version;
  • same_major compatibility policy;
  • stable opaque identifiers;
  • evidence locators bound to artifact digests and coordinate systems;
  • provenance and amendment history;
  • typed partial, unknown, conflict, unsupported, denied, and failure states; and
  • explicit consent, namespace, purpose, and review boundaries where relevant.

Do not map an absent v2 field to a fabricated v3 value. Use the appropriate typed state, preserve an explicit loss record, or require review.

Data migration sequence

  1. Discover: inspect source schemas and counts without mutating data.
  2. Plan: build a versioned mapping for artifacts, facts, identifiers, conflicts, corrections, and policy metadata.
  3. Dry run: write to a new store or isolated namespace.
  4. Validate evidence: verify offsets, coordinate systems, digests, and provenance links.
  5. Validate semantics: compare fact counts, assertion state, units, partial dates, amendments, duplicates, conflicts, and correction history.
  6. Validate identity: keep ambiguous matches unresolved and require review.
  7. Validate consent: confirm that withdrawn or unavailable consent remains denied after migration.
  8. Replay: repeat the migration against a fresh target and compare stable digests. Any duplicate effect or drift is a failure.
  9. Recover: interrupt a synthetic run, restore from the documented checkpoint, and confirm the same result.
  10. Cut over: change readers only after the isolated target passes the complete release gate.

The migration must never overwrite the only source copy. The v3 golden runner and release gate also refuse implicit replacement of existing outputs.

API and service migration

  • Continue to treat extraction results as assistive evidence, not final clinical decisions.
  • Adopt the versioned Journey resource page for facts, artifacts, conflicts, resolutions, cohorts, and datasets.
  • Handle every typed state explicitly. In particular, an empty page is not an unknown result, a denied result is not an empty result, and partial output is not success.
  • Bind pagination cursors to the full query and snapshot. Do not reuse cursors after a filter, role, purpose, consent, or namespace change.
  • Preserve idempotency keys across retries and record cancellation, checkpoint, lease, and invalidation outcomes.
  • Keep raw source values out of logs, telemetry, traces, and release evidence.

Interoperability boundaries

V3 can preserve evidence from text, FHIR R4, HL7 v2, delimited tables, and DICOM SR-derived content and can project selected facts to OMOP. This does not make every source lossless.

  • Pin the exact FHIR profiles and terminology releases used by the deployment.
  • Preserve HL7 message structure and record unsupported segments or fields.
  • Keep DICOM coordinates and derived text tied to the originating artifact digest.
  • Record table column and row coordinates explicitly.
  • Treat partial dates, post-coordinated concepts, local codes, and unsupported OMOP fields as disclosed loss or review work.
  • Re-run downstream conformance tools supplied by the deploying organization.

Model and data migration

V3 does not require a mandatory cloud model. Model artifacts may remain local after an explicit download. For every model and data asset:

  • pin the content digest, tokenizer, format, quantization, and license;
  • record whether it is used for training, evaluation, runtime, or build;
  • record whether it can be redistributed; and
  • select bundled, metadata_only, user_supplied, or out_of_process as the distribution boundary.

Non-redistributable training data cannot be used to justify a distributable artifact in the v3 release gate. Restricted evaluation corpora and vocabularies remain user supplied.

Build release evidence

After the migrated target passes local checks:

  1. Run the five-source golden Journey.
  2. Produce aggregate reports for all ten mandatory lanes.
  3. Freeze the scenario, golden output, schemas, policies, reports, and license catalog in the tagged checkout.
  4. Run the v3 Journey release gate.
  5. Verify the packet signature independently.
  6. Keep promotion as a separate authorized action.

A release is blocked by critical leakage, invalid evidence, broken provenance, non-idempotent replay, migration or recovery failures, unreviewed high-risk output, undisclosed interoperability loss, stale or incomplete performance evidence, license violations, or unresolved high/critical security findings.

Rollback

Before cutover, define the exact rollback pointer and maximum recovery time. Rollback restores the previously verified application and store view; it does not delete the failed evidence packet or rewrite history. Preserve the packet, aggregate reports, tag, commit, and migration receipt for investigation.

After rollback, confirm:

  • source and target counts and digests;
  • no duplicate external side effects;
  • consent and namespace isolation;
  • review queues and unresolved conflicts;
  • model and policy pointer integrity; and
  • query and export denial behavior.

Known limitations

  • The committed golden journey is synthetic and intentionally narrow.
  • Migration tooling cannot infer missing consent, provenance, identity, or review decisions safely.
  • A passing standards fixture does not prove compatibility with every partner system.
  • Performance evidence applies only to its recorded hardware, dataset, quantization, and concurrency.
  • Technical release evidence is not clinical validation or a medical-device certification.
  • High-risk, ambiguous, conflicting, or insufficient-evidence output requires abstention or human review and must not trigger autonomous patient-care action.

Review the v3 Journey threat model before production cutover.