Element <nestedKey>

Purpose: Build or overlay a nested list/dict field within the current product row.

Why: Use it to build or enrich one nested dictionary or a repeated list of one shape.

Example

<nestedKey name="items"/>

Decision guide

Business value: Models a structured object or repeated record group without flattening business structure.

• Use when

  • One output field contains a dictionary or repeated records with a common shape.

• Choose another approach when

  • The value is scalar, a homogeneous scalar array, or a heterogeneous conditional list.

• Prerequisites

  • Define the nested child fields and the intended cardinality or source.

• Alternatives

  • Use array for homogeneous scalar collections. (See: <array>)
  • Use list for entries with different shapes or conditions. (See: <list>)

Complete examples

Assemble nested objects, conditional lists, arrays, and branches

Use this shape when one deterministic product combines nested records, heterogeneous list entries, literal arrays, and mutually exclusive fields.

<setup rngSeed="42" numProcess="1">
    <generate name="profiles" count="3" target="LogExporter">
        <key name="id" generator="IncrementGenerator"/>
        <nestedKey name="address" type="dict">
            <key name="city" constant="Berlin"/>
            <key name="postal_code" constant="10115"/>
        </nestedKey>
        <list name="contacts" converter="RemoveNoneOrEmptyElement">
            <item>
                <key name="channel" constant="email"/>
                <key name="value" script="'customer-' + str(id) + '@example.test'"/>
            </item>
            <item condition="id % 2 == 0">
                <key name="channel" constant="sms"/>
                <key name="value" script="'+49-30-' + str(100000 + id)"/>
            </item>
        </list>
        <array name="roles" type="literal">
            <value constant="customer"/>
            <value constant="newsletter"/>
        </array>
        <condition>
            <if condition="id == 1">
                <key name="segment" constant="new"/>
            </if>
            <else-if condition="id == 2">
                <key name="segment" constant="active"/>
            </else-if>
            <else>
                <key name="segment" constant="loyal"/>
            </else>
        </condition>
    </generate>
</setup>

Rules and invalid combinations

cyclic requires source or script input.

Attributes: cyclic, source, script

Why: Only an existing input sequence can be repeated.

<nestedKey name="items" count="2" cyclic="true" script="[{'id': 1}]"/>

<nestedKey name="items" count="2" cyclic="true"/>

cyclic requires count, minCount, or maxCount.

Attributes: cyclic, count, minCount, maxCount

Why: A finite count bound prevents an endlessly repeated nested input.

<nestedKey name="items" count="2" cyclic="true" script="[{'id': 1}]"/>

<nestedKey name="items" script="[{'id': 1}]" cyclic="true"/>

script cannot be combined with source parsing attributes.

Attributes: script, source, type, separator, sourceScripted

Why: A script owns the complete nested value; source, type, separator, and sourceScripted describe a different input owner.

<nestedKey name="items" script="[{'id': 1}]"/>

<nestedKey name="items" script="[{'id': 1}]" source="data/items.ent.csv"/>

distribution requires a list-capable source.

Attributes: distribution, source, type

Why: Distribution selects rows from a source pool; it cannot shape a scalar or source-free nested object.

<nestedKey name="items" source="mem" distribution="ordered"/>

<nestedKey name="items" source="data/items.ent.csv" distribution="ordered"/>

Use count or minCount/maxCount, never both.

Attributes: count, minCount, maxCount

Why: Both strategies own the number of nested values.

<nestedKey name="items" type="list" count="2"/>

<nestedKey name="items" type="list" count="2" minCount="1"/>

minCount must be less than or equal to maxCount.

Attributes: minCount, maxCount

Why: The nested repetition count is drawn from the inclusive interval between those bounds.

<nestedKey name="items" type="list" minCount="1" maxCount="3"/>

<nestedKey name="items" type="list" minCount="3" maxCount="1"/>

A source-free list requires count, minCount, or maxCount.

Attributes: type, source, count, minCount, maxCount

Why: The list length cannot otherwise be determined.

<nestedKey name="items" type="list" count="2"/>

<nestedKey name="items" type="list"/>

separator and sourceScripted require source.

Attributes: source, separator, sourceScripted

Why: These options modify source parsing and have no effect on script- or child-owned values.

<nestedKey name="items" source="data/items.ent.csv" separator=","/>

<nestedKey name="items" count="1" separator=","/>

type as a memstore sourceEntity alias cannot conflict with sourceEntity.

Attributes: source, type, sourceEntity

Why: A memstore product must have one unambiguous source identity.

<nestedKey name="items" type="list" source="mem" sourceEntity="orders"/>

<nestedKey name="items" source="mem" type="archived_orders" sourceEntity="orders"/>

I822 — Task NestedKey Item Not Dict

Expect current product of '{name}' is a dictionary, but got invalid datatype: '{value_type}'

Why: A value expected to be a dictionary was not a dictionary in the task configuration.

Resolution: Provide a dictionary value for the configuration.

Full rule

I192 — Source Reference Identifier Empty

Explicit source URI for family '{family}' requires a non-empty identifier

Why: A recognized source-family URI was declared without the identifier needed to resolve its source.

Resolution: Add the source identifier after the URI scheme and retry.

Full rule

I193 — Source Reference Consumer Unsupported

Explicit source family '{family}' is not supported by <{consumer}>

Why: The source family is valid, but the consuming DSL element does not implement its read contract.

Resolution: Use a source family supported by this element or move the read to generate/iterate.

Full rule

I195 — Source Reference Identifier Conflict

Explicit source identifier '{identifier}' conflicts with {attribute}='{configured_identifier}'

Why: Two source attributes select different identities for the same explicit source reference.

Resolution: Remove the legacy override or make it equal to the identifier in source.

Full rule

W006 — Memstore Dataset Selected Through type

<{element}> attribute type='{entity}' in descriptor '{descriptor}' is read as sourceEntity='{entity}'; execution continues. Use sourceEntity for dataset selection and keep type for list or dict; if you meant a container, check the spelling of type.

Why: A memstore dataset is selected through type instead of sourceEntity.

Resolution: Move the dataset name to sourceEntity; reserve type for list or dict.

Full rule

Allowed parents / Allowed children

Allowed parents: else, else-if, generate, if, item, iterate, nestedKey, while

Allowed children:

array, assert, condition, echo, element, execute, id, key, list, mapping, nestedKey, rule, sourceConstraints, targetConstraints, variable, while

Related concepts and use cases

• Variable Scoping in Nested Generates — Prevents accidental ancestor reads and shadowing, and routes memstore reads through the public Scripting API.
• Upgrade your models from DATAMIMIC 3.5 to 4.0 — Helps existing 3.5 users identify affected models, understand the reasons for 4.0 changes, and migrate syntax and expected results without confusing retained compatibility with breakage.
• Migrate Benerator Models to DATAMIMIC — Maps Benerator concepts to the current generated grammar without freezing another support matrix.
• Structured Data and Rule Pipelines — Shows how composite output shapes and the ordered source-filter, mapping, and target-filter pipeline work together without hiding phase boundaries.
• Assemble a complex deterministic model — Provides the requirement-to-model sequence for products, field dependencies, relationships, targets, and acceptance evidence.
• Model relationships and correlated data — Explains when to use nested products, memstore lineage, or one correlated reference selection.

Attributes

Show all 17 attributes

condition

Condition for nested key generation.

optional; string; Default: null.

converter

Converter for element data transformation.

optional; string; Default: null.

count

Number of nested keys to generate.

optional; string; Default: null.

cyclic

Enable or disable cyclic generation for nested keys.

optional; boolean; Default: null.

defaultValue

Default value for nested keys.

optional; string; Default: null.

distribution

Distribution type for nested key sampling.

optional; string; Default: null; Values: ordered, random, round_robin, reservoir, cumulated.

maxCount

Maximum count for nested key generation.

optional; integer; Default: null.

minCount

Minimum count for nested key generation.

optional; integer; Default: null.

name

Name of the nested key.

required; string.

script

Script for nested key generation.

optional; string; Default: null.

separator

Separator for nested key data.

optional; string; Default: null.

source

CSV/JSON project-file or memstore source for nested list/dict data; expressions resolve per row.

optional; string; Default: null.

sourceEntity

Explicit memstore product to read (overrides the nested-key name fallback).

optional; string; Default: null.

sourceScripted

Enable or disable scripted sources.

optional; boolean; Default: null.

type

Type of the nested key.

optional; string; Default: null; Values: list, dict.

variablePrefix

Prefix before field names inside nested selectors.

optional; string; Default: null.

variableSuffix

Suffix after field names inside nested selectors.

optional; string; Default: null.