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.
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
ingredients.schema.jsonandrecipes.schema.jsonWorkspace Metadata
Version Detection
Design Principles
Goals
Success Criteria
Dependencies
None - this is foundational infrastructure.
Blocks
This versioning infrastructure is essential before nutriterm reaches v1.0 and must be designed to accommodate various future migration approaches.