Check Syntax

MDL Syntax Validation Skill

This skill ensures MDL scripts are validated before presenting them to users or executing them.

When to Use This Skill

ALWAYS use this skill before:

• Presenting MDL code to users
• Executing MDL scripts via mxcli exec
• Committing MDL files to version control

exec refuses what check rejects

mxcli exec runs the same semantic checks before writing anything. A script whose checks report an error is not executed at all — nothing is written — because exec applies statements one at a time and cannot roll back, so a known-bad script would leave the model partly updated. Warnings are printed and do not stop the run.

mxcli exec script.mdl -p app.mpr              # checked, then applied
mxcli exec script.mdl -p app.mpr --no-check   # applied regardless

This does not replace running check yourself. check is faster, needs no write connection, and reports the warnings worth reading before you commit to a run. What the gate guarantees is narrower and still valuable: a script that slips past you cannot half-apply.

It also does not mean the script is correct. mxcli check validates MDL syntax and mxcli's own rules; it does not validate the Mendix model. Run mx check (or mxcli docker check -p app.mpr) after applying a slice.

-p resolves references — there is no separate opt-in

mxcli check script.mdl alone checks syntax and the semantic rules that need no model. Pass -p and it also resolves every reference — modules, entities, pages, microflows and icons — against that project. It reaches inside stored documents where a name can only be answered there: an ALTER PAGE … SET is dry-run against the page it edits, so a widget the page does not have, or a property the stored widget does not declare, is reported here rather than stopping the script partway through exec.

mxcli check script.mdl                 # syntax + model-free rules
mxcli check script.mdl -p app.mpr      # ... and every reference resolved

--references is implied by -p and is kept only so existing scripts keep working. It used to be required, which meant mxcli check script.mdl -p app.mpr printed an unqualified Check passed! having resolved nothing — a misspelled icon or entity sailed through a command that had been handed the project. A run without a project now says what it did not check, so a pass is never read as more than it is.

An excluded document's dangling references are warnings, not errors. Mendix does not validate excluded documents (Feedback v4.0.2 ships an excluded page bound to nanoflows it lacks, and the project checks at 0 errors), so check and exec print them as Reference warning lines for excluded microflows, nanoflows, rules, and pages/snippets exec will write excluded (@excluded, or a stored namesake that is). A missing data-source flow is a warning only when the bindings inside it are qualified (Attribute: Module.Entity.Attr, {1} = Module.Entity.Attr, Visible: Module.Entity.Attr in (…)) — the form describe writes there. The widgets inside bind against the entity that flow returns, so with the flow missing a bare binding cannot be resolved; it is refused, naming the widget, because on 11.13.0 a bare attribute reference left a project mx could not load. A missing entity still blocks.

It also reports a name the PROJECT already has

A plain create of a document the project already carries is a check error, not something to discover at exec time:

statement 4: association already exists in project: Sales.Order_Customer — use CREATE OR MODIFY to update it

The reason it belongs in check is that exec stops at the first one having already written everything before it. A script whose fourth statement conflicts leaves three statements' worth of changes in the project and no fourth — so "run it and see" is not a free experiment. check reports every conflict in the script before anything is written.

Three spellings say "fine if it already exists", and none is reported: create or modify, create or replace, and create <kind> if not exists <name> (which leaves the stored element untouched rather than rewriting it; every create that names one element takes it, e.g. create page if not exists M.P … — mxcli syntax create-if-not-exists). create module M; is never reported either — it is a no-op when the module exists, which is what lets it open every script.

The types covered are the ones exec refuses: entity, enumeration, constant, association, microflow, nanoflow, rule, page, snippet, layout, java action, javascript action, workflow, menu, task queue, scheduled event, regular expression, database connection, REST client, OData client and service, message definition collection, the integration/agent document types, module roles, user roles, demo users and configurations. Annotations are the one known gap (they have no name to compare). If you find another that exec refuses and check does not, that is a bug of exactly the shape TestEveryCreateStmtIsClassified and TestEveryCreateDocTypeIsProjectChecked exist to prevent.

Separately, check reports MDL-DUPNAME for a name Mendix will not let two elements share — a nanoflow named like a microflow, a page and a snippet, an enumeration and an entity, or the same kind spelled in another case (M.act_login next to M.ACT_Login, CE0122). It covers rename … to and move … to Module onto a taken name too. mxcli help MDL-DUPNAME has the table.

It reports what the script REMOVES from the project

create or modify entity is on the list above — it is never a conflict, because "fine if it already exists" is exactly what it says. What it does not say is that it rebuilds the entity from the statement, so every member the statement omits is deleted. Slice an app into ordered scripts and that becomes a real hazard: an attribute added by a later alter entity — a calculated one whose microflow does not exist until then is the usual reason — is gone the moment the earlier script is re-run on its own. Script order is load-bearing, even though each script is individually idempotent.

check now says so before anything is written, as MDL087:

⚠ applying this script to the project removes 1 member(s) from entity
  ServiceCore.LithoSystem that it does not restate: OpenRequestCount
  — anything still bound to them (widgets, microflows) fails the build with CE1613
    at ServiceCore.LithoSystem
    → … or add them incrementally with 'alter entity ServiceCore.LithoSystem
      add attribute <name>: <type>;' in this script; if they are meant to go,
      say so with 'alter entity … drop attribute <name>;'

exec prints the same list — but as it applies the statement, by which point the attribute is gone. Left unreported entirely, the loss surfaces slices later as CE1613 on whatever still binds it, naming the page, not the script that removed the attribute (ako/mxcli#562).

Two properties of the rule are worth knowing, because they are what keep it from becoming noise you learn to scroll past:

• It is the NET effect of the whole script, not one statement's. A script that rebuilds an entity and then adds the members back with alter entity … add attribute loses nothing and is silent. So the combined slices check clean and slice 01 alone does not, which is precisely the difference that bit.
• An explicit removal is not reported. drop attribute, rename attribute and drop entity say what they do. Only a member the project holds, that the script neither restates nor asks to remove, is a warning.

It is a warning: "modify to this shape" is a legitimate intent and check still exits 0. The defect was the silence, not the behaviour. It also covers the members that are not attributes — the four audit system fields and an omitted extends — because those drop the same way.

It reports the flow changes exec would refuse

create or modify microflow|nanoflow on a stored flow is a patch. A change the patch cannot make (inside a loop body or error handler, a redrawn connector, a return added) is refused by exec under mdl 1;, and rebuilt (IDs, merges and curves lost) without the header. With -p, check runs the same verdict exec and diff run: an MDL-V1-REBUILD error quoting exec's refusal under mdl 1, the MDL-V1-REBUILD warning without the header, and MDL090 for an alter microflow|nanoflow exec would refuse. Use alter for the change, or drop and create the flow. A flow an earlier statement of the script touches is not predicted (exec sees that statement's result), and fmt --upgrade --header -p keeps the header off a file it would make refuse (ako/mxcli#876).

It reports a doc comment that is lost

A /** … */ doc comment documents the statement right after it, and only a create of something with documentation stores one. Above a drop, grant, revoke, set, alter or create module it is ignored, so MDL089 warns and names the next statement that could have taken it. In drop-then-create, put the comment between the drop and the create (ako/mxcli#877).

It resolves MEMBER names too, where it can establish the entity

Resolution does not stop at the entity. An attribute named in a create or change activity is looked up on that entity and its generalizations, so a typo is reported by check rather than by mxbuild as CE1613 "The selected attribute '…' no longer exists" a whole build later:

Sales.ACT_Close: Sales.Order has no member "IsArchived" (in change $Order)
  — it has OrderNo, Status — mxbuild reports this as CE1613 …

This needs the target's entity to be known, and that is the boundary worth understanding rather than assuming:

Widget positions are resolved too:

• an XPath constraint on a database from Module.Entity source — every step is followed, so a bare name must be an attribute of the entity it lands on and a Module.Name step must be an association or an entity;
• a template parameter (ContentParams / CaptionParams) rooted in a variable. That one needs no project and fires under a bare mxcli check, because the answer is in the statement.

The template-parameter rule is narrower than "no $ roots", and the difference is measured rather than reasoned — the writer strips one prefix on one branch:

Note the two-segment form: Assoc/Attr, not the XPath Assoc/Entity/Attr, which mxbuild also rejects.

Expression KINDS are checked in the positions that declare one

Two more things reach mxbuild as CE0117 "Error(s) in expression" and are now reported by check:

• A bare word as a member's value. Mendix expressions have no bare identifiers, so CHANGE $Order (Status = Closed) is E013. Write 'Closed' (a literal), $Closed (a variable), or Module.Enum.Value (an enumeration). Scoped to the whole value of a create/change member: a bare name nested in a list-operation predicate is legal — FILTER($L, Status = 'Open') resolves Status against the item under test — and is not reported.
• A log message's template parameter must be a String. LOG … WITH ({1} = $Order/Qty) is E009. Measured on 11.13.0: Integer, Decimal, Boolean, DateTime and an object each fail; a String attribute is clean; and toString(…) around any of them is clean. So wrap the non-String ones — the writer is fine, Mendix simply does not coerce here.

Three more things check now refuses

• An unqualified CREATE (create association Order_Probe …) — MDL074, no project needed. exec always refused it; check now does too, which matters because exec is not transactional: the statements before the failure are already applied, and re-running hits "already exists" on them.
• RETURNS void AS $x — MDL075, no project needed. An alias names the variable a flow returns, so it cannot be paired with void; mxcli used to believe the alias and write return $x into a flow with no such variable (CE0109). Write RETURNS void, or give the alias the type it holds.
• empty($List) — E014. empty is a Mendix keyword, not a function, so the parser stops at the (. Write $List = empty or length($List) = 0.

One thing to know about hint ordering: the reference check runs before expression checking and exits on its first error, so an unrelated mistake anywhere in a file hides every expression hint in it. If you expect an E0xx and see none, fix the reference errors first and re-run.

A variable this cannot type is left unchecked, never guessed at — a false "no such member" would block a script that builds cleanly. Two more things are deliberately not reported: a qualified member (Module.Assoc), which exec already refuses when it cannot be an attribute, and any member on an entity the script itself creates or whose attribute the script adds earlier — the add-the-column-then-populate-it shape stays valid.

Pre-Flight Validation Checklist

Before writing any MDL, verify these requirements:

0. Start the script with mdl 1;

A script without the header is checked and executed as mdl 0, the alpha language, where some statements mean something else. Write mdl 1; as the first line of every new script. To edit a headerless one, upgrade it first (mxcli fmt --upgrade --header -p app.mpr -w script.mdl) — never mix the two in one file; see choose-edit-mode.

1. Check Supported Syntax

Supported in Microflows:

• declare $Var type = value; (primitives only: String/Integer/Long/Decimal/Boolean/DateTime/Enumeration)
• $entity = create Module.Entity (...); / retrieve $entity from ... first; (objects — never declare an object; that fails CE0053/CE0038 and is flagged MDL043)
• $list = create list of Module.Entity; (lists — never declare a list; that fails CE0053/CE0038 and is flagged MDL040)
• set $Var = expression;
• $Var = create Module.Entity (attr = value);
• change $entity (attr = value);
• commit $entity [without events] [refresh]; (omitted = with events, Mendix's default)
• delete $entity;
• retrieve $Var from Module.Entity [where condition];
• $Result = call microflow Module.Name (Param = $value); (NOT set $Result = ...)
• $Result = call nanoflow Module.Name (Param = $value);
• show page Module.PageName (Param = $value);
• close page;
• validation feedback $entity/attribute message 'message';
• log info|warning|error [node 'name'] 'message';
• if condition then ... [else ...] end if;
• loop $item in $list begin ... end loop;
• return $value;
• on error continue|rollback|[without rollback] begin handler end error;

Now Supported (previously not):

• rollback $entity [refresh]; - Reverts uncommitted changes
• retrieve ... first - Returns a single entity; limit n [offset n] returns a list (a bare limit 1 is the object only without the mdl 1; header, and warns MDL-V1-LIMIT1)
• boolean without default - Auto-defaults to false
• buttonstyle: warning and buttonstyle: info - Now parse correctly
• Keywords as attribute names - caption, label, title, text, content, format, range, source, check, etc. all work unquoted

NOT Supported (will cause errors):

• set $var = call microflow ... - Use $var = call microflow ... (no SET)
• while ... end while - Use loop with lists
• case ... when 'String' ... - Case values are bare enum identifiers, never quoted or qualified; case ... when Value then ... end case; itself IS supported (enum splits only), and takes no else (MDL008) and no AS alias
• TRY ... CATCH - Use on error blocks
• break / continue - Not implemented
• commit message 'text' - Not in current grammar (session command only)

2. Quote All Identifiers

Best practice: Always quote all identifiers (entity names, attribute names, parameter names) with double quotes. This escapes every MDL parser keyword conflict — quotes are stripped automatically by the parser.

Caveat — quoting does not exempt platform-reserved member names. Quoting only escapes MDL parser keywords. Names the Mendix platform reserves for entity members are still rejected after the quotes are stripped: Type (CE7247, MDL021), the system audit attributes CreatedDate / ChangedDate / Owner / ChangedBy (MDL020 — use the AutoCreatedDate / AutoChangedDate / AutoOwner / AutoChangedBy pseudo-types instead), plus the CE7247 word list (ID, GUID, CurrentUser, Java keywords, …). "Type": String still fails MDL021 — rename to a non-reserved name (e.g. ResourceType, TypeValue). "Always safe to quote" covers parser keywords, not these.

The parse error tells you which case you are in. 'Title' is a keyword in MDL. Quote it to use it as a name means quoting works and nothing has to be renamed; 'Type' is reserved by MENDIX itself, not just by MDL means it does not. Measured across the keywords mxcli hints on: 38 are rescued by quoting, 3 (Type, Default, Owner) are not.

Third case — OQL keywords, where quoting works but in a different grammar. Year, Month, Quarter, Week, Day, Hour and the other date-part words are neither MDL parser keywords nor platform-reserved: they are accepted everywhere and build at 0 errors. They bite only inside a view entity's OQL, and only unquoted (CE0174). OQL takes double-quoted identifiers just like SQL — s."Month", from Module."Year" as s — and mxcli writes them through unchanged, so the usual fix is a quote in the OQL, not a rename. mxcli reports MDL071 as a warning at CREATE/ALTER so the name is still cheap to change if you would rather rename. Applies to the entity name as well as its attributes.

The exception is an alias, and that limit is OQL's own: it takes a bare identifier there for any name — as "Total", reserved nowhere, is CE0174 too (MDL072). A view entity's attribute name is also its select alias, so a view column cannot be called Month at all — that one needs a rename, not a quote.

Exception — never quote $-prefixed variable/parameter references. The quote rule is for bare names (entities, attributes, associations, declared parameter names). Variable and parameter references in expressions and widget bindings stay unquoted: datasource: $X, params: ( $X: MES."Order" ), $currentObject. Quoting them ("$X") breaks resolution ("parameter … references '$X' but no such parameter is declared").

Enumeration values: no =. Value names may be quoted like any identifier, but the caption follows as a quoted string — there is no equals sign: create enumeration Mod.E ("Grade1" 'Grade 1', Grade2 'Grade 2'); (or Grade1 caption 'Grade 1'). Writing "Grade1" = 'Grade 1' fails with mismatched input '=' — the = is the problem, not the quotes.

mdl 1;
create persistent entity Module."Customer" (
  "Name": string(200),
  "status": string(50),
  "create": datetime
);

Both "Name" and `Name` syntax are supported. Prefer double quotes for consistency.

Run mxcli syntax keywords for the full list of 320+ reserved keywords.