Skip to content

Add schema versioning infrastructure to support future migration strategies #4

@cfuehrmann

Description

@cfuehrmann

Problem

Currently, nutriterm schemas have no version tracking, making it impossible to evolve the data format safely as the tool matures toward v1.0. Without versioning infrastructure, any schema changes would break existing user workspaces.

Proposed Solution

Add comprehensive version tracking that can support multiple future migration strategies:

Schema Versioning

  • Add version identifiers to ingredients.schema.json and recipes.schema.json
  • Design versioning format to support various migration approaches (automatic, manual, hybrid)
  • Include both schema version and compatible nutriterm version ranges

Workspace Metadata

  • Track schema versions used in each workspace
  • Store creation/migration history for debugging
  • Design metadata format to support future migration tooling needs

Version Detection

  • Detect schema version mismatches during workspace loading
  • Provide clear error messages when versions are incompatible
  • Foundation for triggering future migration processes

Design Principles

  • Migration-agnostic: Versioning should work for automatic, manual, or hybrid update mechanisms
  • Forward-compatible: Design should accommodate unknown future migration strategies
  • Minimal disruption: No changes to user workflow until migrations are needed
  • Clear semantics: Version comparisons and compatibility should be unambiguous

Goals

  • Enable safe schema evolution before v1.0
  • Prevent breaking existing user workspaces
  • Create foundation that supports any future migration approach
  • Clear error reporting for version mismatches

Success Criteria

  • Schemas have clear, comparable version identifiers
  • Workspaces track their schema versions reliably
  • Version mismatches are detected and reported helpfully
  • Design supports multiple potential migration strategies
  • No regression in current functionality

Dependencies

None - this is foundational infrastructure.

Blocks

  • Future migration framework implementation

This versioning infrastructure is essential before nutriterm reaches v1.0 and must be designed to accommodate various future migration approaches.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions