Data Mesh Manager

Data Contract Version Management

Introduction

The Data Contract Version Management feature helps you manage different versions of your data contracts. It enables you to:

  • Track relationships between data contracts with similar external IDs
  • Create new major versions of existing data contracts
  • View related major versions in the sidebar of contract details

We recommend using Semantic Versioning for your data contracts:

  • Major version (X.y.z): Increment when making incompatible changes
  • Minor version (x.Y.z): Increment when adding functionality in a backward-compatible manner
  • Patch version (x.y.Z): Increment when making backward-compatible bug fixes

External ID Naming Convention

For proper version tracking, structure your external IDs as follows:

base-name_vX

Where:

  • base-name is your data contract's unique identifier
  • _ is the separator (underscore is recommended)
  • vX is the major version number with a "v" prefix (e.g., v1, v2, v3)

Examples:

customer-data_v1
sales-transactions_v2
product-inventory_v3

Viewing Related Versions

The related major versions appear in the right sidebar of the data contract details page. This panel shows all data contracts that share the same base external ID but have different major versions.

Related Major Versions Sidebar

Creating a New Major Version

To create a new major version:

  1. Navigate to an existing data contract
  2. View the related major versions in the sidebar
  3. Click "Create vX" (where X is the next major version number)
  4. The system will:
  • Pre-fill the new contract with data from the most recent contract
  • Automatically increment the major version in the external ID
  • Allow you to make your incompatible changes

Show Changes

After creating a new major version, you can view the changes made compared to the previous version. This is done by clicking the "Show Changes" button in the contract details page. You can view the changes made in the new major version compared to the previous version.

This helps you understand what has changed over time and ensures that all stakeholders are aware of the modifications.

Show Changes

Additional Version Management Features

Automatic Version Suggestions

When updating a data contract, our system analyzes the changes and suggests appropriate version increments based on semantic versioning principles:

Version Suggestions

If you enabled the AI Features, the generated changelog will be used to improve version suggestions.

  • Patch: For bug fixes and minor updates
  • Minor: For new features that don't break existing implementations
  • Major: For breaking changes to the contract (behaves the same as creating a new major version)

Benefits

This feature provides several advantages:

  • Traceability: Track the evolution of your data contracts over time
  • Consistency: Maintain a consistent versioning approach across your organization
  • Efficiency: Quickly create new versions without manual copying and renaming
  • Visibility: See all related versions at a glance

Best Practices

  • Always create a new major version for breaking changes
  • Use descriptive base names in your external IDs
  • Keep the version history linear and avoid skipping versions
  • Document significant changes when creating a new version