¶ Data Product Versioning
¶ Overview
Elementrix provides comprehensive version control for data products, enabling safe evolution of schemas and configurations. Version management ensures backward compatibility while allowing products to grow and improve.
¶ Version Lifecycle
¶ Version States
| State | Description | API Behavior |
|---|---|---|
| Draft | Work in progress | Not accessible via API |
| Active | Current production version | Default for API calls |
| Deprecated | Still available but discouraged | Returns deprecation warning |
| Retired | No longer available | Returns 410 Gone |
¶ Version Relationships
Version History Tree:
v1.0.0 (Active) ───┬── v1.1.0 (Active)
│
└── v1.2.0 (Active) ─── v2.0.0 (Draft)
│
└── v1.2.1 (Deprecated)
¶ Creating Versions
¶ Automatic Versioning
Versions are automatically created when:
- Publishing a product for the first time
- Making breaking schema changes
- Explicitly requesting a new version
¶ Manual Version Creation
- Navigate to Data Product → Version History
- Click "Create New Version"
- Select version type:
- Major (2.0.0) - Breaking changes
- Minor (1.1.0) - New features, backward compatible
- Patch (1.0.1) - Bug fixes, no schema changes
- Add version notes
- Click "Create Version"
Create New Version:
Current Version: 1.2.0
New Version:
○ Major (2.0.0) - Breaking changes
● Minor (1.3.0) - New features
○ Patch (1.2.1) - Bug fixes only
Version Notes:
[Added new fields for tracking customer preferences...]
Copy settings from current version:
☑ Copy schema
☑ Copy access controls
☑ Copy semantic mappings
☐ Copy approval workflow
[Create Version] [Cancel]
¶ Version History
¶ Viewing History
Version History: Customer Transaction History
Current Version: 2.1.0
┌────────────────────────────────────────────────────────────┐
│ Version │ Created │ Status │ Changes │
├─────────┼─────────────┼────────────┼──────────────────────┤
│ 2.1.0 │ 2026-02-10 │ ● Active │ Added fraud_score │
│ 2.0.0 │ 2026-01-15 │ ● Active │ Major schema update │
│ 1.2.1 │ 2025-11-20 │ ⚠ Deprecat│ Patch for timestamp │
│ 1.2.0 │ 2025-09-15 │ ● Active │ Added currency field │
│ 1.1.0 │ 2025-07-10 │ ⚠ Deprecat│ Added metadata │
│ 1.0.0 │ 2025-01-20 │ ⚠ Retired │ Initial release │
└─────────┴─────────────┴────────────┴──────────────────────┘
[Compare Versions] [Create Version] [View Details]
¶ Comparing Versions
Version Comparison: v2.0.0 → v2.1.0
Schema Changes:
┌────────────────────────────────────────────────────────────┐
│ Status │ Field │ v2.0.0 │ v2.1.0 │
├────────┼─────────────────┼─────────────┼──────────────────┤
│ ADDED │ fraud_score │ - │ Decimal(5,4) │
│ ADDED │ risk_category │ - │ Enum │
│ MODIF │ amount │ Decimal(10) │ Decimal(12) │
│ UNCH │ transaction_id │ UUID │ UUID │
│ UNCH │ customer_id │ UUID │ UUID │
└────────┴─────────────────┴─────────────┴──────────────────┘
Breaking Changes: No
Backward Compatible: Yes
¶ Breaking vs Non-Breaking Changes
¶ Breaking Changes (Major Version Required)
| Change Type | Example | Impact |
|---|---|---|
| Removing fields | Delete customer_name |
Existing apps fail |
| Changing data types | String → Integer | Parsing errors |
| Making optional required | Optional → Required | Validation failures |
| Renaming fields | id → identifier |
Field not found |
| Changing field order | Reorder JSON keys | May break parsers |
¶ Non-Breaking Changes (Minor/Patch Version)
| Change Type | Example | Impact |
|---|---|---|
| Adding optional fields | New notes field |
Ignored by old apps |
| Adding descriptions | Document field | No impact |
| Adding enum values | New status option | May need handling |
| Extending field length | VARCHAR(50) → 100 | No impact |
| Adding indexes | Performance only | No impact |
¶ Version Management
¶ Listing Versions
Versions can be viewed and managed through the Elementrix UI.
¶ Restoring Versions
To restore a previous version:
- Navigate to Version History
- Select the version to restore
- Click "Restore as New Version"
- This creates a new version (doesn't delete history)
¶ Deprecating Versions
Deprecate Version:
Version: 1.2.1
Current Status: Active
Deprecation Settings:
Deprecation Date: [2026-03-15]
Sunset Date: [2026-06-15] (90 days notice)
Migration Guide: [Link to documentation]
Custom Message:
[Version 1.2.1 is deprecated. Please migrate to v2.1.0.
See migration guide at: docs.company.com/migration]
☑ Notify all subscribed applications
☑ Add deprecation header to API responses
[Deprecate Version] [Cancel]
¶ Migration Guide
¶ Version Migration Checklist
-
Review Changes
- Compare schemas between versions
- Identify breaking changes
- Document required code changes
-
Update Applications
- Modify API integration code
- Update field mappings
- Handle new/changed fields
-
Test Thoroughly
- Test against staging environment
- Verify all use cases
- Check error handling
-
Deploy
- Update production configuration
- Point to new version
- Monitor for issues
-
Cleanup
- Remove deprecated version usage
- Update documentation
- Archive old code
¶ Best Practices
¶ Version Strategy
- Use semantic versioning (MAJOR.MINOR.PATCH)
- Maintain at least 2 active versions
- Provide 90-day deprecation notice
- Document all changes
¶ Communication
- Announce new versions in advance
- Provide migration guides
- Offer transition period
- Support affected teams
¶ Monitoring
- Track version usage
- Alert on deprecated version calls
- Monitor migration progress
- Collect feedback