Versioning and extensibility of the .meb standard
Status:
[x]ready — version 3.0.0
1. Standard steward
The .meb standard is the property of MEBsystem sp. z o.o., NIP 6312727689. All changes to the structure, semantics and validation rules are introduced exclusively by MEBsystem sp. z o.o. Other parties may use the standard without restriction, but may not publish modifications as versions of the .meb standard.
Bug reports and change proposals are accepted through the standard's repository.
2. Versioning scheme
The standard version is stored in meta.version as semver MAJOR.MINOR.PATCH.
| Level | When it changes | Example |
|---|---|---|
| MAJOR | Changes that break backward compatibility | 1.0.0 → 2.0.0 |
| MINOR | New fields, objects or enum values — backward compatible | 1.0.0 → 1.1.0 |
| PATCH | Documentation fixes, corrections with no effect on the structure | 1.0.0 → 1.0.1 |
What is a breaking change (MAJOR)
A change requires incrementing MAJOR when:
- a required field is removed
- the type of an existing field is changed
- the semantics of an existing field are changed in an incompatible way
- a new required field is added
- the meaning of an existing enum value is changed
What is not a breaking change (MINOR)
- adding a new optional field
- adding a new enum value (see §4)
- adding a new catalog object
- changing a field from required to optional
PATCH
PATCH changes do not affect the structure or semantics of the file. Implementations do not have to react to a change of the PATCH number.
3. Implementation behavior on an unknown version
The implementation compares the version in meta.version with the highest supported version.
| Situation | Required behavior |
|---|---|
| file MAJOR > supported MAJOR | MUST reject the file with an error |
| file MAJOR = supported MAJOR, file MINOR > supported MINOR | MUST load the file, ignoring unknown fields; SHOULD inform the user |
| file PATCH different from the supported one | irrelevant — loads normally |
| file MAJOR < supported MAJOR | SHOULD load the file (backward compatibility mode) |
The error message on rejection due to an unknown MAJOR MUST contain the file version and the version supported by the implementation.
4. New enum values
Adding a new value to an existing enum field is a MINOR change — it does not require incrementing MAJOR.
An implementation MUST NOT return a critical error on encountering an unknown enum value. Recommended behavior:
- skip the operation containing the unknown value
- log a warning with the field name and the value encountered
- continue processing the remaining data
Exhaustive matching on enum values is the implementer's choice — the standard does not require handling all values, but it does require graceful degradation on unknown values.
5. Deprecation policy
A field or value marked as deprecated:
- Remains in the standard for exactly one MAJOR version
- Is removed in the next MAJOR version
- Is recorded in the changelog with the version that introduced the deprecation and the version of the planned removal
An implementation encountering a deprecated field SHOULD log a warning. It MUST NOT reject a file solely because a deprecated field is present.
A deprecated field never becomes required.
6. Vendor extensions (x_)
General rule
Implementations may add their own fields with the x_ prefix to a .meb file. x_ fields are purely informational — they serve to store metadata specific to the given software.
Permitted uses
- internal IDs from the source software's database
- rendering hints (display color, visibility in the viewer)
- session data (last edited node, zoom level)
- technical comments irrelevant to production
Absolute prohibitions
x_ fields MUST NOT:
- duplicate or override fields defined in the standard
- change the interpretation of any standard field
- contain geometric data or production operations
- be required to read the file correctly
An implementation that reads the file MUST be able to produce a correct cabinet while ignoring all x_ fields entirely.
Name format
x_{vendor}_{name}Examples of valid names:
"x_systemex_project_db_id": "PRJ-00412",
"x_cabinetpro_last_edited_node": "node_007",
"x_acme_display_color": "#3a7bd5"The vendor prefix should be a unique identifier of the software — it minimizes the risk of collisions between independent implementations.
Name collisions
The standard does not maintain a registry of vendor prefixes. In a name collision between two implementations, the responsibility for resolving it lies with those implementations — the standard does not define a resolution mechanism.
7. Backward compatibility — rules for MEBsystem sp. z o.o.
When introducing MINOR changes, MEBsystem sp. z o.o. MUST:
- ensure that a file compliant with version
N.xremains valid in versionN.(x+1) - not change the meaning of existing required fields
- not change the allowed values of existing enums (only add)
When introducing MAJOR changes, MEBsystem sp. z o.o. SHOULD:
- publish a migration path describing each breaking change
- maintain support for the previous MAJOR version for at least 12 months from the publication of the new one
- provide a tool or instructions for converting files from the old version to the new one