Skip to content

Commit be5ff31

Browse files
akoclaude
ako
and
claude
committed
docs: expand version compatibility page with BSON differences and version gates
Rewrite the version compatibility documentation to cover: - Accurate feature matrix split by 9.x/10.x/11.0+/11.6+ requirements - BSON structural differences across versions (view entities, page parameters, design properties, association storage) - Widget template versioning with MPK augmentation explanation - Version gate directive syntax (-- @Version:) for MDL scripts - Nightly test coverage across 10.24, 11.6, 11.8 - Known error codes when features are used on incompatible versions Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 5e166e0 commit be5ff31

File tree

1 file changed

+123
-29
lines changed

1 file changed

+123
-29
lines changed

‎docs-site/src/appendixes/version-compatibility.md‎

Lines changed: 123 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,20 @@
11
# Mendix Version Compatibility
22

3-
Supported Mendix Studio Pro versions and MPR format mapping.
3+
Supported Mendix Studio Pro versions, BSON format differences, and known limitations.
44

55
## Supported Versions
66

7-
mxcli supports Mendix Studio Pro versions **8.x through 11.x**.
7+
mxcli supports Mendix Studio Pro versions **9.x through 11.x**. Development and nightly testing targets three versions:
88

9-
| Studio Pro Version | MPR Format | Status |
10-
|-------------------|------------|--------|
11-
| 8.x | v1 | Supported |
12-
| 9.x | v1 | Supported |
13-
| 10.0 -- 10.17 | v1 | Supported |
14-
| 10.18+ | v2 | Supported |
15-
| 11.x | v2 | Supported (primary development target) |
16-
17-
> **Note:** Development and testing is primarily done against **Mendix 11.6**. Other versions are supported but may have untested edge cases.
9+
| Studio Pro Version | MPR Format | Nightly Tested | Status |
10+
|-------------------|------------|----------------|--------|
11+
| 9.x | v1 | No | Read-only support |
12+
| 10.0 -- 10.17 | v1 | No | Supported |
13+
| 10.18 -- 10.23 | v2 | No | Supported |
14+
| 10.24 (LTS) | v2 | **Yes** | Supported |
15+
| 11.0 -- 11.5 | v2 | No | Supported |
16+
| 11.6 | v2 | **Yes** | Primary development target |
17+
| 11.8 | v2 | **Yes** | Latest tested |
1818

1919
## MPR Format Versions
2020

@@ -32,31 +32,125 @@ mxcli supports Mendix Studio Pro versions **8.x through 11.x**.
3232

3333
The library auto-detects the format. No configuration is needed.
3434

35-
## Widget Template Versions
35+
## Feature Availability by Version
36+
37+
Not all MDL features work on all Mendix versions. The BSON document structure changes across versions, and some features were introduced in specific releases.
38+
39+
### Core Features (all supported versions)
3640

37-
Pluggable widget templates are versioned by Mendix release. The embedded templates cover:
41+
| Feature | Minimum Version | Notes |
42+
|---------|----------------|-------|
43+
| Domain models (entities, attributes, associations) | 9.0 | Full CRUD support |
44+
| Microflows (60+ activity types) | 9.0 | Including loops, splits, error handling |
45+
| Nanoflows | 9.0 | Client-side flows |
46+
| Pages (50+ widget types) | 9.0 | Built-in widgets |
47+
| Enumerations | 9.0 | CREATE/ALTER/DROP |
48+
| Security (module roles, access rules) | 9.0 | Full support |
49+
| Navigation | 9.0 | Profiles, menus, home pages |
50+
| Workflows | 9.0 | User tasks, decisions, parallel splits |
3851

39-
| Mendix Version | Template Set |
40-
|---------------|--------------|
41-
| 10.6.0 | DataGrid2, ComboBox, Gallery, and others |
42-
| 11.6.0 | Updated templates for current widgets |
52+
### Features Requiring Mendix 10.x+
4353

44-
When creating pages with pluggable widgets, the library selects the template matching the project's Mendix version, falling back to the nearest earlier version if an exact match is not available.
54+
| Feature | Minimum Version | Notes |
55+
|---------|----------------|-------|
56+
| Business events | 10.0 | Event service definitions |
57+
| Pluggable widgets (ComboBox, DataGrid2, Gallery) | 10.0 | Requires widget templates |
58+
| Image collections | 10.0 | CREATE/DROP IMAGE COLLECTION |
4559

46-
## Feature Availability by Version
60+
### Features Requiring Mendix 11.0+
61+
62+
These features use BSON structures that changed in Mendix 11.0 and are **not compatible with 10.x projects**:
63+
64+
| Feature | Minimum Version | Error on 10.x |
65+
|---------|----------------|---------------|
66+
| View entities (CREATE VIEW ENTITY) | 11.0 | CE6775: "A view entity requires an OQL query" |
67+
| Page parameters (Params: { ... }) | 11.0 | InvalidOperationException on 'Variable' property |
68+
| Design properties (Atlas v3) | 11.0 | CE6083: "Design property not supported by your theme" |
69+
| REST client (CREATE REST CLIENT) | 11.0 | BSON format incompatibility |
70+
| Database Connector (EXECUTE DATABASE QUERY) | 11.0 | Module format incompatibility |
71+
| Association storage format | 11.0 | Different BSON encoding for associations |
72+
73+
### Features Requiring Mendix 11.6+
4774

4875
| Feature | Minimum Version | Notes |
4976
|---------|----------------|-------|
50-
| Domain models | 8.x | Full support |
51-
| Microflows | 8.x | 60+ activity types |
52-
| Nanoflows | 8.x | Client-side flows |
53-
| Pages | 8.x | 50+ widget types |
54-
| Pluggable widgets | 9.x | Requires widget templates |
55-
| Workflows | 10.x | User tasks, decisions, parallel splits |
56-
| Business events | 10.x | Event service definitions |
57-
| View entities | 10.x | OQL-backed entities |
58-
| MPR v2 format | 10.18 | Per-document file storage |
59-
| Calculated attributes | 10.x | CALCULATED BY microflow |
77+
| Portable app format | 11.6 | New deployment format |
78+
79+
## BSON Differences Across Versions
80+
81+
The Mendix metamodel evolves across versions. The reflection data shows ~42% type growth from Mendix 9.0 to 11.6. Key structural differences:
82+
83+
### View Entities (10.x vs 11.x)
84+
85+
View entities exist in both 10.18+ and 11.x, but the BSON structure differs. Mendix 10.x stores view entities without the OQL query field that 11.x requires. Writing a view entity with 11.x BSON to a 10.x project causes CE6775.
86+
87+
### Page Parameters (10.x vs 11.x)
88+
89+
Mendix 11.0 changed how page parameters are stored in BSON. The `Variable` property in page parameter mappings uses a different structure. Writing 11.x-style page parameters to a 10.x project causes an `InvalidOperationException`.
90+
91+
### Design Properties (Atlas v2 vs v3)
92+
93+
Atlas UI v3 (Mendix 11.0+) introduced new design properties like "Card style" and "Disable row wrap" for containers. These don't exist in the Atlas v2 theme bundled with 10.x, causing CE6083.
94+
95+
### Widget Type Definitions
96+
97+
Pluggable widget PropertyTypes change between Mendix versions. A widget template extracted from 11.6 may have more or fewer properties than the widget installed in a 10.24 project. The [widget augmentation system](../internals/widget-templates.md) handles this by reconciling templates against the project's `.mpk` files.
98+
99+
## Widget Template Versions
100+
101+
Embedded widget templates are extracted from Mendix 11.6 and cover:
102+
103+
| Widget | Template | Widget ID |
104+
|--------|----------|-----------|
105+
| Combo box | combobox.json | com.mendix.widget.web.combobox.Combobox |
106+
| Data grid 2 | datagrid.json | com.mendix.widget.web.datagrid.Datagrid |
107+
| Gallery | gallery.json | com.mendix.widget.web.gallery.Gallery |
108+
| Image | image.json | com.mendix.widget.web.image.Image |
109+
| Text filter | datagrid-text-filter.json | com.mendix.widget.web.datagridtextfilter.DatagridTextFilter |
110+
| Number filter | datagrid-number-filter.json | com.mendix.widget.web.datagridnumberfilter.DatagridNumberFilter |
111+
| Date filter | datagrid-date-filter.json | com.mendix.widget.web.datagriddatefilter.DatagridDateFilter |
112+
| Dropdown filter | datagrid-dropdown-filter.json | com.mendix.widget.web.datagriddropdownfilter.DatagridDropdownFilter |
113+
114+
### MPK Augmentation
115+
116+
When opening a project, mxcli checks the project's `widgets/` folder for `.mpk` packages. If a widget's installed version differs from the embedded template, the augmentation system:
117+
118+
1. Extracts the XML property definition from the `.mpk`
119+
2. Adds properties found in `.mpk` but missing from the template
120+
3. Removes properties in the template but not in the `.mpk`
121+
4. Preserves the BSON structure (IDs, nesting, cross-references)
122+
123+
This reduces CE0463 ("widget definition changed") errors from widget version drift. See [Widget Templates](../internals/widget-templates.md) for details.
124+
125+
## Version Gates in MDL Scripts
126+
127+
MDL scripts can use `-- @version:` directives to gate sections by Mendix version. This is used in the doctype integration tests to skip features incompatible with older versions:
128+
129+
```mdl
130+
-- Runs on all versions
131+
CREATE ENTITY MyModule.Customer (Name: String(200));
132+
133+
-- @version: 11.0+
134+
-- Only runs on Mendix 11.0 and later
135+
CREATE VIEW ENTITY MyModule.ActiveCustomers (...) AS
136+
SELECT c.Name FROM MyModule.Customer AS c WHERE c.IsActive;
137+
138+
-- @version: 10.6..10.24
139+
-- Only runs on Mendix 10.6 through 10.24
140+
CREATE ENTITY MyModule.LegacyConfig (...);
141+
142+
-- @version: any
143+
-- Resets to unconditional (runs on all versions)
144+
CREATE ENTITY MyModule.Universal (...);
145+
```
146+
147+
**Directive formats:**
148+
- `-- @version: 11.0+` -- minimum version (run on 11.0 and later)
149+
- `-- @version: 10.6..10.24` -- version range (inclusive)
150+
- `-- @version: ..10.24` -- maximum version only
151+
- `-- @version: any` -- reset to unconditional
152+
153+
The directive applies to all lines until the next `-- @version:` directive.
60154

61155
## MxBuild Compatibility
62156

0 commit comments

Comments
 (0)