Zserio Compatibility Guide
This document describes all possible backward incompatibilities that can occur after updating of Zserio. Users should be aware of them in order to decide whether a Zserio update will require additional changes in the application or in the Zserio schema.
The following summarizes all possible backward compatibilities that should be considered after a Zserio update:
Schema Language Compatibility
Schema language compatibility determines whether new Zserio versions can compile old schemas.
Such incompatibility can be detected by the major Zserio version. If the major Zserio version remains unchanged, then schema language compatibility will be granted.
Example
If the old Zserio version is 2.11.0 and the new Zserio version is 2.12.0, then schema language
compatibility is granted. In other words, all Zserio versions 2.*.* would keep schema language
compatibility.
Note that Zserio version can be read by the command
java -jar zserio.jar --version.
Extension API Compatibility
Extension API compatibility determines whether a Zserio extension is compatible with the Zserio core. This actually means if the Zserio core will accept the Zserio extension.
Such incompatibility is automatically detected by the Zserio core when loading the Zserio extension. Each Zserio extension must inform the Zserio core about the specific Zserio core version it requires. The Zserio core only accepts extensions that are designed for the same or an older Zserio core version, but with the same major and minor versions.
Example
If the Zserio core has version 2.11.1 and the Zserio extension expects the Zserio core 2.11.0, then
extension compatibility is granted. On the other hand, if the Zserio core has version 2.11.0 and the Zserio
extension expects the Zserio core 2.10.1, then the extension is not compatible and will be refused by the
Zserio core.
Code Generator Compatibility
Code generator compatibility determines whether code generated by a Zserio extension is compatible with code generated by older Zserio extensions.
Such incompatibility can be detected by the major Zserio extension version. Each Zserio extension must inform the Zserio core about its version. Zserio extensions with the same major version generate compatible code.
Example
If the old C++ generator has version 1.0.0 and the new C++ generator has version 1.1.0, then generated
code is compatible. On the other hand, if the old C++ generator has version 1.0.0 and the new C++ generator
has version 2.0.0, then the generated code is incompatible.
Note that versions of all available extensions can be read using the command
java -jar zserio.jar --version. The Zserio code generator version can also be found in the comment at the beginning of each generated source code.
Runtime Library
Code Generators may have an independent runtime library that contains code used by the generated code. Each runtime library has its own version, which must be the same as the code generator’s version.
Runtime library incompatibility can be detected manually or automatically implemented in the user application.
The C++ generator detects runtime library incompatibility automatically. This is implemented using a unique C++
preprocessor feature to avoid performance drops during runtime. The runtime library version is stored
in the module CppRuntimeVersion.h.
Java generator does not detect runtime library incompatibility, but the user application can implement this
check using the runtime library version stored in the module JavaRuntimeVersion.java.
Python generator does not detect runtime library incompatibility, but the user application can implement this
check using the runtime library version stored in the module __init__.py.
Binary Encoding Compatibility
Binary encoding compatibility determines whether new Zserio code generator versions serialize the data to the same binary stream as old Zserio code generator versions.
Such incompatibility can be detected by the major Zserio BIN version. If the major Zserio BIN version remains unchanged, then the binary encoding compatibility will be granted.
Note that the Zserio BIN version will only be changed very rarely, and only if it is absolutely necessary. In such cases, the Zserio compiler directive
zserio_compatibility_versioncan be used to check this incompatibility.
Example
If the old Zserio BIN version is 1.1 and the new Zserio BIN version is 1.2, then binary encoding
compatibility is granted. In other words, all Zserio BIN versions 1.* would keep binary encoding
compatibility.
Note that Zserio BIN version for each code generator can be read by the command
java -jar zserio.jar --version.
Note that binary encoding format is defined by Zserio Encoding Guide.
JSON Encoding Compatibility
JSON encoding compatibility determines whether new Zserio code generator versions export the data to the same JSON file as previous Zserio code generator versions.
Such incompatibility can be detected by the minor Zserio JSON version. If the major Zserio JSON version remains unchanged, then the JSON encoding compatibility will be granted.
Note that the Zserio JSON version will only be changed very rarely, and only if it is absolutely necessary. In such cases, the Zserio compiler directive
zserio_compatibility_versioncan be used to check this incompatibility.
Example
If the old Zserio JSON version is 1.1 and the new Zserio JSON version is 1.2, then JSON encoding
compatibility is granted. In other words, all Zserio JSON versions 1.* would keep JSON encoding
compatibility.
Note that Zserio JSON version for each code generator can be read by the command
java -jar zserio.jar --version.
Note that JSON encoding format is defined by Zserio JSON Guide.
Command Line Compatibility
Command line compatibility determines whether new Zserio versions support the same command line arguments as previous Zserio versions.
Such incompatibility can only be detected by the release notes.
Note that command line arguments will only be changed very rarely, and only if it is absolutely necessary. In such cases, old command line arguments will first be deprecated with a clear notification for users.