Misleading JSON vs MDL Token Comparison

[hankxdev]

The current documentation compares a verbose JSON representation against a highly optimized domain-specific syntax (MDL), then concludes that MDL is significantly more token-efficient.

Issues can be found in:

mxcli/docs/10-user-docs/mxcli-slides.md

Line 105 in 3539cf6

### JSON vs MDL

mxcli/docs-site/src/preface/what-is-mdl.md

Line 37 in 3539cf6

A simple entity definition illustrates the difference.

mxcli/docs/10-user-docs/mxcli-slides.typ

Line 145 in 3539cf6

== Slide 8: Token Comparison

I think this comparison is misleading because the two examples are not equivalent in design goals or verbosity level.

Current Example

Verbose JSON:

{
  "entity": {
    "name": "Customer",
    "documentation": "Customer master data",
    "attributes": [
      {"name": "Name", "type": {"type": "String", "length": 200}},
      {"name": "Email", "type": {"type": "String", "length": 200}}
    ]
  }
}

Compact MDL:

/** Customer master data */
CREATE PERSISTENT ENTITY Sales.Customer (
    Name: String(200),
    Email: String(200)
);

Why This Is Problematic

The comparison mixes:

• a generic serialization format (JSON)
• with a purpose-built DSL (MDL)

The JSON example is also intentionally verbose:

• repeated "type" nesting
• repeated object wrappers
• redundant field naming

A more compact JSON representation could be:

{
  "name": "Customer",
  "doc": "Customer master data",
  "fields": {
    "Name": "string(200)",
    "Email": "string(200)"
  }
}

Or even:

{
  "Customer": {
    "Name": "string(200)",
    "Email": "string(200)"
  }
}

At that point, the claimed token difference becomes much smaller.

Suggested Improvement

Instead of presenting this as “JSON vs MDL token efficiency,” I’d suggest framing it as:

• MDL is more concise because it is a domain-specific language
• JSON prioritizes generic interoperability and machine tooling
• MDL prioritizes human-readable schema authoring

That would make the comparison feel more technically fair and less like an apples-to-oranges benchmark.

[github-actions]

Issue Triage

Summary:
The reporter points out that the documentation’s JSON‑vs‑MDL token‑efficiency comparison is misleading and suggests reframing it to highlight MDL’s domain‑specific conciseness versus JSON’s generic interoperability.

Checklist for feature request

Required info	Present?	Details
Use case – why the feature is needed / what problem it solves	✅	Explains that the current comparison mixes unrelated formats and gives an unfair impression of MDL’s efficiency.
Proposed syntax or behavior (if applicable)	✅	Suggests rewording the docs to frame MDL as a concise DSL, JSON as a generic interchange format, and to avoid an apples‑to‑oranges benchmark.
Mendix version relevance (if version‑specific)	⚠️	Not indicated as version‑specific; the change applies to all versions, so this field is not required.

Feedback:
The issue provides a clear use case and a concrete proposal for improving the documentation. Since the request is not tied to a particular Mendix version, the missing “Mendix version relevance” item is not needed. The feature request is sufficiently complete.

Thank you for raising this point—your suggestion will help make the documentation more accurate and helpful!

---

Automated triage via OpenRouter — workflow source