Skip to content

nestedKey Element

The <nestedKey> element defines nested key fields and their generation methods within a data generation task. It allows you to structure complex data in a hierarchical format, such as dictionaries (dict) or lists (list), and control its content dynamically.

Attributes

  • name: Specifies the name of the nested key. This is mandatory.
  • type: Defines the type of the nested key. It can be list or dict.
  • count: Specifies the number of items to generate for nested keys, applicable for list types.
  • source: Specifies the data source for the nested key.
  • sourceScripted: Determines whether the source is scripted (optional).
  • cyclic: Enables or disables cyclic behavior for data generation (optional).
  • separator: Defines a separator used between multiple key values (optional).
  • condition: Specifies a condition for the inclusion of the nested key.
  • defaultValue: Sets a default value when the condition is false.
  • script: Specifies a script for generating dynamic content for the nested key.
  • minCount and maxCount: Define the minimum and maximum counts for generating keys.
  • distribution: Controls how data from the source is distributed (random, ordered). Default is random.
  • converter: Specifies a converter to transform nestedKey's children values.
  • variablePrefix: Configurable attribute that defines the prefix for variable substitution in dynamic strings (default is __).
  • variableSuffix: Configurable attribute that defines the suffix for variable substitution in dynamic strings (default is __).

Children

  • key: Defines key-value pairs within the nested structure.
  • variable: Variables can be used within the nested structure.
  • nestedKey: Allows additional nesting within a nested key.
  • execute: Executes operations within the nested structure.
  • if: Defines conditional logic inside the nested key.
  • list: Embeds lists within the nested key.
  • echo: Outputs data for logging/debugging.
  • element: Specifies child elements for XML generation.
  • array: Embeds arrays within the nested key.

Example 1: Nested Dictionary

Warning

The examples provided are intended to demonstrate the syntax and structure of DATAMIMIC models and features. They may not work directly out of the box. For fully functional examples, please refer to the demo section available in our demo store when you log in. If you are missing specific use cases or scenarios, feel free to reach out to us—we're happy to assist.

The following example creates a nested dictionary (dict) with keys like street, city, and zip.

1
2
3
4
5
<nestedKey name="address" type="dict">
    <key name="street" script="person.street"/>
    <key name="city" script="person.city"/>
    <key name="zip" script="person.zip"/>
</nestedKey>

Output:

1
2
3
4
5
6
7
{
    "address": {
        "street": "123 Main St",
        "city": "Springfield",
        "zip": "12345"
    }
}

Example 2: Nested List

This example generates a nested list (list) with two items, each containing brand and manufacturing_date keys.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
<nestedKey name="cars" type="list">
    <item>
        <key name="brand" constant="Tesla"/>
        <key name="manufacturing_date" constant="23-FEB-2023"/>
    </item>
    <item>
        <key name="brand" constant="BMW"/>
        <key name="manufacturing_date" constant="11-MAR-2022"/>
    </item>
</nestedKey>

Output:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
    "cars": [
        {
            "brand": "Tesla",
            "manufacturing_date": "23-FEB-2023"
        },
        {
            "brand": "BMW",
            "manufacturing_date": "11-MAR-2022"
        }
    ]
}

Example 3: Using condition and defaultValue

This example shows how to apply conditions and default values when generating nested keys.

1
2
3
4
5
6
7
8
<nestedKey name="list" type="list" count="2" condition="True" defaultValue="[]">
    <key name="id" type="int"/>
</nestedKey>
<nestedKey name="list2" type="list" count="2" condition="False" defaultValue="[]"/>
<nestedKey name="dict" type="dict" condition="True" defaultValue="{}">
    <key name="id" type="int"/>
</nestedKey>
<nestedKey name="dict2" type="dict" condition="False" defaultValue="{}"/>

Output:

1
2
3
4
5
6
7
8
9
{
  "list": [
    { "id": 0 },
    { "id": 50 }
  ],
  "list2": [],
  "dict": { "id": 75 },
  "dict2": {}
}

Example 4: Enriching or Overwriting Nested Keys from a Template

You can enrich or overwrite nested keys from an existing template. Here’s how to add a field (country) to an existing address key without specifying the type:

1
2
3
4
5
<generate name="datamimic_user_dict" source="script/address.json" target="JSON">
    <nestedKey name="address">
        <key name="country" constant="USA"/>
    </nestedKey>
</generate>

Output:

1
2
3
4
5
6
7
8
{
    "address": {
        "street": "123 Main St",
        "city": "Springfield",
        "zip": "12345",
        "country": "USA"
    }
}

To overwrite a nested key entirely from a template:

1
2
3
4
5
6
7
<generate name="datamimic_user_dict" source="script/address.json" target="JSON">
    <nestedKey name="address" type="dict">
        <key name="custom-street" script="person.street"/>
        <key name="custom-city" script="person.city"/>
        <key name="custom-zip" script="person.zip"/>
    </nestedKey>
</generate>

Output:

1
2
3
4
5
6
7
{
    "address": {
        "custom-street": "123 Main St",
        "custom-city": "Springfield",
        "custom-zip": "12345"
    }
}

Example 5: Using source put data into nestedKey

This follow example get data from source and put it to nestedKey, have to specify the right type of input data.

1
2
3
4
5
6
<setup>
    <generate name="people1" target="JSON" count="1">
        <nestedKey name="people_csv" count="1" type="list" source="data/person.ent.csv" separator=","/>
        <nestedKey name="pet_json" type="dict" source="data/pet.json" distribution="ordered"/>
    </generate>
</setup>
data/person.ent.csv
1
2
3
4
name,pet_file
Alice,alice_pet
Bob,bob_pet
Cathay,cathay_pet
data/pet.json
1
2
3
4
5
{
    "name":"Bob",
    "age":34,
    "notes":null
}

Output: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
[
  {
    "people_csv": [
      {
        "name": "Alice",
        "pet_file": "alice_pet"
      }
    ],
    "pet_json": {
      "name": "Bob",
      "age": 34,
      "notes": null
    }
  }
]

Example 6: Using source with sourceScripted for dynamic value in source

This follow example get data from source, and specific values in source will be replaced by generated value. We call they dynamic variables.

When using dynamic variables to replace values in a source dataset, there are two ways to represent variables: {var} and __var__ ('__' can be changed by setting 'variablePrefix' and 'variableSuffix').

Both allow dynamic replacement, but they differ in functionality, scope, and the type of value they return.

Using {var}:

  • The {} must enclose the entire value, inside {} only the variable name is allowed, no additional characters inside or outside.
  • The replaced value retains the data type of the generated variable. E.g. if the variable is an integer, the replaced value will also be an integer.
1
"age": "{random_age}"

Using variablePrefix and variableSuffix:

  • The variable must be enclosed by the prefix and suffix (default is __).
  • It supports combining multiple variables and text in the string containing __var__.
  • The replaced value is always a string, regardless of the original data type of the variable.
1
"address": "120, __street_name__ St"

Example:

datamimic.xml
1
2
3
4
5
6
7
<setup>
    <generate name="json_data" source="script/data.json" sourceScripted="True" target="JSON">
        <variable name="random_age" generator="IntegerGenerator(min=18, max=65)"/>
        <variable name="street_name" generator="StreetNameGenerator"/>
        <variable name="address_number" generator="IntegerGenerator"/>
    </generate>
</setup>

Source data:

script/data.json
1
2
3
4
5
6
7
8
9
[
    {
        "id": 1,
        "name": "Alice",
        "age": "{random_age}",
        "address_number": "__address_number__",
        "address": "__address_number__, __street_name__ St"
    }
]

Output (both age and address_number original are number, but with __var__ output is string and {var} output is number)

1
2
3
4
5
6
7
8
9
[
  {
    "id": 1, 
    "name": "Alice", 
    "age": 50, 
    "address_number": "729625",
    "address": "729625, Center Street St"
  }
]

Important:

  • In source data, you can not have 'key' or 'header column' with the same name as dynamic variable name (e.g. you cannot use "random_age": "__random_age__")

Example 7: Using script to get value into nestedKey

This follow example get data from script attribute, nestedKey 'type' will be set base on input value. Noted that input value type must be 'dict' or a 'list' of 'dict'.

1
2
3
4
5
6
7
8
<setup>
    <generate name="json_data" count="1" target="JSON">
        <variable name="random_age" script="[{'age':10},{'age':20},{'age':30}]"/>
        <variable name="address" script="{'address_number':1023,'street_name':'Hauptstrasse'}"/>
        <nestedKey name="ages" script="random_age"/>
        <nestedKey name="my_address" script="address"/>
    </generate>
</setup>

Output 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
[
  {
    "ages": [
      {"age": 10},
      {"age": 20},
      {"age": 30}
    ],
    "my_address": {
      "address_number": 1023,
      "street_name": "Hauptstrasse"
    }
  }
]

Best Practices for Using <nestedKey>

  1. Use Conditions and Default Values: Leverage conditions to dynamically control whether a nested key is generated, and use default values when the condition evaluates to False.
  2. Nesting for Complex Data: Utilize nested keys to generate complex hierarchical structures like dictionaries and lists.
  3. Enrich or Overwrite Templates: Use <nestedKey> to enhance or completely overwrite nested data from predefined templates.
  4. Efficient Distribution: Use the distribution attribute to control how data from the source is applied (random, ordered).