JSON Structures And Mappings

JSON Structures, Import Mappings & Export Mappings

This skill covers creating and managing JSON structures, import mappings, and export mappings in Mendix using MDL.

Key Concepts

JSON Structures

A JSON structure defines the schema of a JSON payload. It stores a JSON snippet and auto-derives an element tree with paths, types, and custom names.

Import Mappings

An import mapping converts a JSON string into Mendix entity objects. It maps JSON fields to entity attributes.

Two names per member: the raw key and the exposed name

Every JSON structure element stores both, and for any lowercase-initial key they differ:

Mendix derives the exposed name by capitalising the initial, and for an array's item object by suffixing Item — so total → Total, camelCase → CamelCase, __Value (array) → __ValueItem (its item). Keys already starting with an underscore are left alone: __returnedCount stays __returnedCount.

This is Mendix's own convention, not something mxcli does. A blank app's Studio-Pro-authored FeedbackModule.JSON_AppInsightsResponse stores ExposedName: "Uuid" against Path: "(Object)|uuid", and its IMM_PostResponse binds JsonPath: "(Object)|uuid".

Consequences worth knowing:

• Either spelling works in MDL. Total = total and Total = Total produce the same stored mapping. Write whichever you have.
• DESCRIBE emits the raw JSON key, so its output reproduces the script that produced the mapping — Total = total comes back as Total = total, and an array binding as = item rather than = ItemItem. It also emits create or modify, so the output re-runs against the project it was read from. (Until #915 it printed the exposed name and a bare create: the text differed from the input, making every script-vs-describe diff noise, and re-running it failed with "import mapping already exists". The stored mapping was correct either way.)
• A member matching neither spelling is refused, listing what would have worked. It is never written with a guessed path: such a mapping passed mxcli check and failed later in mxbuild (CE5015) or at runtime.

Inherited attributes

Mendix inheritance is multi-table: all of a parent's attributes are members of the child, so an entity created with extends can map them. Name an inherited attribute exactly like one of the entity's own — mxcli resolves each to the entity that declares it, which is the reference Studio Pro needs to show the field mapped.

mdl 1;
create persistent entity Docs.DocumentBase (
  DocName: String(200),
  Confidential: Boolean
);

create persistent entity Docs.Contract extends Docs.DocumentBase (
  ContractNumber: String(50)
);

create import mapping Docs.IMM_Contract
  with json structure Docs.JSON_Contract
{
  create Docs.Contract {
    ContractNumber = contractNumber,   -- own
    DocName        = docName,          -- inherited
    Confidential   = confidential      -- inherited
  }
};

Qualifying an inherited attribute against the entity being mapped instead of its declaring entity is Mendix CE1613 "The selected attribute ... no longer exists", and the field shows unmapped in Studio Pro.

Export Mappings

An export mapping converts Mendix entity objects into a JSON string. It maps entity attributes to JSON fields.

Critical: Import and Export Need Different Domain Models

Import and export mappings for the same JSON structure typically require different entity structures.

• Import: The child entity owns the FK to the parent (from Child to Parent). Arrays map directly to the item entity — no intermediate container entity needed.
• Export: The domain model mirrors the JSON structure. Arrays need an intermediate container entity (e.g., Items) plus an item entity (e.g., ItemsItem). The container links to the parent, the item links to the container.

JSON Structures

Create

mdl 1;
create json structure Module.JSON_Pet
  sample '{"id": 1, "name": "Fido", "status": "available"}';

For multi-line JSON, use dollar-quoting:

mdl 1;
create json structure Module.JSON_Order
  sample $${
  "orderId": 100,
  "customer": {"name": "Alice", "email": "alice@example.com"},
  "items": [{"sku": "A1", "quantity": 2, "price": 9.99}]
}$$;

Custom name mapping (rename JSON fields):

mdl 1;
create json structure Module.JSON_Pet
  sample '{"id": 1, "name": "Fido"}'
  CUSTOM NAME map ('id' as '_id');

Name array items yourself — item of (ako/mxcli#272). An array's item is the anonymous [...] entry, so it has no JSON key and the plain form cannot reach it; left alone it gets a derived name like LinesItem:

mdl 1;
create json structure Module.JSON_Invoice
  sample '{"lines": [{"sku": "A1"}], "tags": ["urgent"]}'
  CUSTOM NAME map (
    'lines' as 'OrderLines',
    item of 'lines' as 'OrderLine',
    item of 'tags' as 'Tag'
  );

This is worth doing rather than accepting the default: a mapping element clones the schema element's ExposedName, so the item's name is what every mapping over this structure carries, and it is one of the two names a member resolves by.

• The two clauses are independent — naming an item does not require renaming its array, so adding one is a one-line diff.
• item of names a primitive array's wrapper too; that wrapper is the item.
• A root-level array has no key: item of 'Root' as 'Entry'.
• An entry whose key is not in the snippet is an error (MDL-JSON01), as is item of on something that is not an array (MDL-JSON02).

Browse

mdl 1;
list json structures;
list json structures in module;
describe json structure Module.JSON_Pet;
drop json structure Module.JSON_Pet;

Message Definitions

A mapping's source can also be a message definition — 74 of the 327 mappings in the demo corpus (22.6%), and the only non-JSON source MDL can create. It holds nothing external: it is a selection over the domain model.

mdl 1;
create message definition collection Sales.MD_Order {
  definition OrderMessage for Sales.Order as 'Orders' {
    OrderId,
    Sales.Order_Customer/Sales.Customer { FirstName }
  }
};

A bare name is an attribute; Assoc/Module.Entity is an association. Name the target entity — the stored cardinality follows the direction of traversal and the association's type, so a Reference gives a single object one way and a list the other, while a ReferenceSet is a list both ways.

Mendix 11.15 removed collections. Each definition is its own document, and a mapping names it in two parts. The collection form is refused on 11.15, and the document form below 11.15:

mdl 1;
create message definition Sales.OrderMessage for Sales.Order as 'Orders' {
  OrderId,
  Sales.Order_Customer/Sales.Customer { FirstName }
};
create import mapping Sales.IMM_Order with message definition Sales.OrderMessage
{
  create Sales.Order { OrderId = OrderId }
};

The full vocabulary, the ALTER statements, inherited attributes and what mxcli deliberately does not guess: reference/message-definitions.md.

Import Mappings

Domain Model for Import

For import mappings, associations point FROM the child entity TO the parent:

mdl 1;
create non-persistent entity Module.OrderResponse (
  OrderId: integer
);

create non-persistent entity Module.CustomerInfo (
  Name: string,
  Email: string
);

create non-persistent entity Module.OrderItem (
  Sku: string,
  Quantity: integer,
  Price: decimal
);

-- Child entity owns the FK (FROM child TO parent)
create association Module.CustomerInfo_OrderResponse
  from Module.CustomerInfo
  to Module.OrderResponse;

create association Module.OrderItem_OrderResponse
  from Module.OrderItem
  to Module.OrderResponse;

Simple Import Mapping (flat JSON)

mdl 1;
create import mapping Module.IMM_Pet
  with json structure Module.JSON_Pet
{
  create Module.PetResponse {
    PetId = id,
    Name = name,
    status = status
  }
};

Nested Import Mapping (objects and arrays)

Arrays map directly to the item entity — no intermediate container needed:

mdl 1;
create import mapping Module.IMM_Order
  with json structure Module.JSON_Order
{
  create Module.OrderResponse {
    OrderId = orderId,
    create Module.CustomerInfo_OrderResponse/Module.CustomerInfo = customer {
      Name = name,
      Email = email
    },
    create Module.OrderItem_OrderResponse/Module.OrderItem = items {
      Sku = sku,
      Quantity = quantity,
      Price = price
    }
  }
};

Object Handling

Mendix stores two properties here, not one: how to get the object, and what to do when a find comes up empty. Both are yours to choose.

Append overridable to let the caller override the backup at import time: find Module.PetResponse or create overridable.

mdl 1;
create import mapping Module.IMM_UpsertPet
  with json structure Module.JSON_Pet
{
  find Module.PetResponse or create {
    PetId = id key,
    Name = name,
    status = status
  }
};

A bare find is refused. Which of the three you get is a real runtime difference, and mxcli used to pick create for you whatever the document said — so it now asks rather than guessing.

A find has two requirements, and mxcli check enforces both (ako/mxcli#253):

1. At least one member marked key, per searching element — nested ones included. Without it there is nothing to search on: CE0250, reported as MDL-MAP02. (key is only valid with find; on a create it means nothing.)
2. A persistable entity. A search is a database query, and a non-persistent entity has no database: CE0251, reported as MDL-MAP03. Persistability comes from the generalization chain, not the entity's own flag — an entity declared with plain create entity that extends a non-persistent parent is still not searchable.

Re-measuring these is easy to get wrong: mxbuild reports one at a time. A keyless find over a non-persistent entity is CE0250 only, and CE0251 appears only once a key exists.

A custom handler is exempt from both — the microflow is the find, so there is no key to declare and no query to run.

Custom Object Handling and the Mapping's Input Object

A microflow can resolve the object instead of Create/Find. Write it as by on the element; the microflow's parameters are named with their sources:

parameter needs the mapping to declare an input object, which is a clause on the header — import mappings only:

mdl 1;
create import mapping Module.IMM_Embed
  with json structure Module.JSON_Embed
  parameter GenAICommons.ChunkCollection
{
  create GenAICommons.ChunkCollection {
    Name = id,
    find Module.Chunk_ChunkCollection/GenAICommons.Chunk
      by Module.MF_FindChunk ( Collection: parameter, Index: idx )
      = embeddings {
        Text = text
      }
  }
};

Using parameter without declaring one is refused — the build reports it as CE0279. The declared entity must match the microflow's parameter type, which the build checks as CE0282.