Skip to content

Versioning and compatibility

The .pemr format is designed to remain stable over time while allowing the applications to evolve.

Versioning ensures that bundles created by one version of the software can still be safely opened by newer versions.

Why versioning is necessary

Medical records may exist for many years. During that time:

  • the applications may evolve
  • the database schema may change
  • new features may appear

Without versioning, an older bundle could become unreadable.

The .pemr format therefore includes explicit version metadata that allows applications to determine how a bundle should be handled.

Where version information is stored

Version information is stored in manifest.json.

Typical fields include:

{
  "bundleVersion": "1",
  "schemaVersion": "1",
  "appVersion": "1.2.0"
}

bundleVersion

The bundle version defines the structure of the .pemr format itself.

This includes things like:

  • directory structure
  • required files
  • bundle conventions

schemaVersion

The schema version defines the structure of the database (db.sqlite).

It indicates how tables and fields are organized.

appVersion

The application version indicates which version of the software created the bundle.

This is useful for debugging and migration logic.

Compatibility policy

CareFlow Kids and CareView Family follow a simple compatibility policy.

Forward compatibility

Newer versions of the applications should be able to open older bundles.

If a schema update is required, the application performs a migration of the database.

Backward compatibility

Older applications versions may not be able to open bundles created by newer versions.

If the bundle format or schema is too new, the application will refuse the import and display an error message.

Migration process

When a bundle with an older schema is opened:

  1. The application reads manifest.json
  2. It checks the schemaVersion
  3. If needed, it runs a database migration
  4. The schema is updated to the current version

This ensures that older records remain usable.

Stability principle

The .pemr format is designed with a stability-first philosophy:

  • changes should be rare and deliberate
  • migrations should be safe and reversible
  • older records should remain usable for many years

Maintaining long-term access to patient data is a core design goal of the system.

Summary

Versioning ensures that:

  • .pemr bundles remain usable over time
  • database schemas can evolve safely
  • applications can detect incompatible bundles

This mechanism allows the ecosystem to evolve while preserving the long-term integrity of medical records.