Learn about versioning

Zparse offer the ability to create different versions of the same mapping.

When is it useful ?

Version control for data integration mappings is crucial for seamless, non-disruptive deployments. When you initially deploy a mapping let's call it v1 for a client, it handles a specific data schema and a set of business rules. As their data requirements evolve and they need to add new attributes, you need to develop an updated mapping, v2.

Instead of a high-risk, real-time replacement of the live v1, versioning allows you to build and test v2 in a separate, isolated environment. This approach decouples development from production. Once v2 is validated and the client is ready to transition, you can trigger a zero-downtime switch to the new version. This process is a configuration change, not a code deployment, ensuring the data ingestion pipeline remains active and ready to process the updated file format without any interruption or manual intervention.

How to version your mapping in Zparse

When you create a new mapping by default you will be in version draft. In the next screenshot you can see the version menu.

Work on your mapping and once you are ready, click on the [+] button (next to draft) and choose a name for your new version (Read next chapter if you are note sure about your version naming strategy). Click Copy button, done :)

It will automatically duplicate all node from draft version into this v1.0. You can continue working on the draft version it will not affect the v1.0 of your mapping.

At any time your can switch between version using the version menu:

If your v1.0 is live for your customer and you want to prepare a new version you can create a new version that will copy v1.0 in v1.1 and start working on your future version.

example of mapping versionning

Our Recommendations for versionning

Effective versioning is critical for managing data integration pipelines and preventing disruptions for customers. By adopting a structured versioning convention, you can streamline the development lifecycle and ensure a smooth transition between updates.

A recommended approach, inspired by Semantic Versioning, provides a clear framework:

1. Development & Initial Testing

Begin with a draft version for internal development. Once the mapping is ready for initial customer testing, version it as v0.1. Subsequent changes during this pre-release phase can increment the minor version (ex, v0.2, v0.3).

2. Go-Live

When the mapping is finalized and ready for production, designate it as v1.0. This marks the official release and the version to which you should switch the live workflow.

3. Managing Live Changes

Once in production, any update requires careful version management to avoid breaking customer workflows.

• Non breaking changes (backward compatible): For changes that won't disrupt the existing pipeline (ex: adding an optional field), increment the minor version (ex: from v1.0 to v1.1). These updates can often be deployed without mandatory customer notification, as old files will still be processed correctly.

• Breaking changes (Backward-Incompatible): For changes that would break the existing pipeline (ex: new validation rules, schema changes), increment the major version (ex: from v1.1 to v2.0). This requires coordination with the customer to ensure they are ready to switch, as their current files will no longer be compatible with the new version.

For even greater granularity, you can introduce a patch version, for example, v1.0.3. Ultimately, feel free to adapt this framework and create a naming convention that best suits your project's specific needs.

TL;DR

v1.0.4 → v{MAJOR}.{MINOR}.{PATCH}

• Increase MAJOR when breaking change
• Increase MINOR when change is backward compatible
• Increase PATCH when change is a simple bug fix

Read more about Semantic Versioning →

Changelog

Our top recommendation is to maintain a changelog, which serves as a transparent and chronological record of all changes, providing clarity on updates for both your team and customers.

Example:

📋 Changelog: Excel Parser

Version 3.0.0 (Upcoming: October 12, 2025)
✨ Breaking change (Major Update)

- Column `Y` and `Z` (introduced in `v2.2.0`) will be mandatory
- Deprecation of Column `C` rule about min lenght

Version 2.2.0 (August 22, 2025)
✨ New Features (Minor Update)

- Column `Y` added to the file format to parse your customer email contact
- Column `Z` added to the file format to parse your customer support phone number

Version 2.1.3 (August 15, 2025)
🐛 Bug Fixes (Patch)

- Fixed an issue where the parser would fail on validating canadian phone numbers
- Corrected an error that caused incorrect data type inference for numbers formatted as currency.