JSON Structure

Content Type: Module
Categories: Import/Export


The JSON Structure module provides tools to marshal arbitrary data structures between JSON and Mendix entities. It does so by defining an intermediate structure that expresses your data in terms of generic objects, arrays, properties and values. You define how your data model maps to this generic structure by defining export microflows. Serialization and deserialization between the intermediate structure and JSON is handled by calling one microflow activity. Features - Export any Mendix entity to a serializable data structure by defining export microflows. The correct microflow for each entity in your data structure is automatically looked up (based on a pre-defined template) and executed. - You can customize the template to look up the right microflow. - Serialize any Mendix domain model structure to JSON. - Deserialize any JSON to a generic Mendix entity structure.


Please find the API docs here.


  1. Import the JSON Structure module into your project.
  2. That's it. Nothing else is needed.

Serializing Mendix data to JSON

To explain how you can serialize and serialize your data, we’ll take a simple example as a starting point. Our domain model looks like this:
We’ll assume that our app contains some data for both entities, e.g. a Course on the subject of “Woodworking” with two students; “Tom” (age 24) and “Betty” (age 52).
We want our JSON to look like this:
  • “subject”: Woodworking”,
  • “students”: [
  • {
  • “name”: “Tom”,
  • “age”: 24
  • },
  • {
  • “name”: “Betty”,
  • “age”: 52
  • }
  • ]
Serialization of Mendix data to JSON requires three steps:
  • Define a mapping between the domain model and the desired JSON structure
  • Export your data to the JSON structure you defined
  • Serialize the exported data
Define a mapping between the domain model and the desired JSON structure
The first step is to define a mapping between our domain model and the desired structure of our JSON output. We do this by defining an export microflow for each entity. Export microflows are automatically picked up during export based on the following rules:
    • The microflow must reside within the same module as the entity
    • The microflow name is “JSONExport_”, where “” is the name of the entity (make sure that the capitalization matches).
We’ll start with the Student entity.
  • Create a new microflow called ‘JSONExport_Student’ and add a single parameter of type ‘Student’:
  • Define the mapping between our domain model and the desired JSON structure, using the helpers available in the JSON Structure module.  We start by creating a JSON object and setting it as the return value of our microflow:
  • Next, we need to define our two properties. The attribute ‘Name’ is a string, so we add a call to ‘AddStringProperty’ to our flow. All ‘AddXXProperty’ helpers work in a similar fashion; they require the object that we want to modify, the name of the property, and the value of the property:
  • Similarly, for the attribute ‘Age’, we use the ‘AddIntegerProperty’ helper:
That's it for the Student entity. Let's move on to Course.
  • Create a microflow called ‘JSONExport_Course’ and make sure it has the following content:
You’ll recognize some of the helpers from the microflow we created earlier. However, there are a few new elements.
Because our Course is connected to Students through an association, we'll need to make sure that those Students are exported correctly. To do that, we first retrieve the Students, and pass them to ‘Export list’. This results in a JSONArray.
We can then set our JSONStudents as the value of a new property of JSONCourse, with the help of the ‘AddArrayProperty’ helper.
Export your data to the JSON structure you defined
Now that we have defined how our domain model maps to the desired JSON structure, we can export data. Exporting data is trivial. All we need to do is call ‘ExportEntity’ and pass our input entity:
Under water, this will determine the type of the input data (i.e. which entity it is) and look up the relevant export microflow based on the rules described above. It will then execute this microflow with our Course as a parameter. The result is JSONObject, which we can use for serialization.
Note that we don't export our students. This is already done by our JSONExport_Course microflow.
As you can see in the properties dialog, ExportEntity also allows you to adjust the default microflow name pattern.
Serialize the exported data
Finally, we can serialize our JSON structure, by calling the Serialize action. It expects an input value (which can be of type JSONObject or JSONArray) and it outputs a JSON string.
The output can be controlled by the two additional parameters:
  • Skip empty: If this is true, properties that have an Empty value will not be included in the output.
  • Pretty: If this is true, the output is nicely formatted. If it is false, everything is printed on one line.

Deserializing JSON to Mendix data

Deserializing JSON to Mendix entities is a matter of calling Deserialize and passing your JSON input string. The result is a JSONValue. You can then process the result in any way you deem fit. In most cases, you’ll use an Object Type Decision to determine the exact type of the result.


Version: 1.1.0
Framework Version: 8.12.7
Release Notes: Make module compatible with Mx9
Version: 1.0.1
Framework Version: 8.5.0
Release Notes: Fix Java compilation error
Version: 1.0.0
Framework Version: 8.5.0
Release Notes: The JSON Structure module provides tools to marshal arbitrary data structures between JSON and Mendix entities.