Element <key>

Purpose: Define one generated, copied, converted, or scripted field in a product.

Why: Use it for a named field in a generated record when the field is not specifically an identifier.

Example

<key name="customer_id" generator="IncrementGenerator"/>

Decision guide

Business value: Defines one visible product field and keeps its generation or transformation rule reviewable.

• Use when

  • Adding a scalar field to the generated output record.

• Choose another approach when

  • The value is only an intermediate binding or represents the record identifier.

• Prerequisites

  • Place it in a field-producing parent and choose one compatible value strategy.

• Alternatives

  • Use id when the field is the stable product identifier. (See: <id>)
  • Use variable for a reusable value that must not be exported. (See: <variable>)
  • Use nestedKey for structured objects or repeated records. (See: <nestedKey>)

Complete examples

Choose explicit field generation strategies

Use constants, generators, scripts, patterns, or native numeric ranges according to who owns the field value.

<setup>
    <generate name="field_strategies" count="5" target="LogExporter">
        <key name="status" constant="active"/>
        <key name="sequence" generator="IncrementGenerator"/>
        <key name="doubled" script="sequence * 2"/>
        <key name="reference_code" pattern="[A-Z]{2}[0-9]{4}"/>
        <key name="score" type="int" min="1" max="5" distribution="step"/>
    </generate>
</setup>

Control nulls, conditions, and fallbacks

Use nullQuota for probabilistic absence and defaultValue only as the fallback of a scripted field.

<setup>
    <generate name="optional_fields" count="4" target="LogExporter">
        <key name="always_null" type="string" nullQuota="1"/>
        <key name="nickname" script="None" defaultValue="'unknown'"/>
        <key name="visibility" script="'internal'" condition="False" defaultValue="'redacted'"/>
    </generate>
</setup>

Keep a raw datetime until final formatting

Keep temporal arithmetic on an unformatted variable and apply outDateFormat only to exported keys.

<setup>
    <generate name="invoice_dates" count="1" target="LogExporter">
        <variable name="issued_at" generator="DateTimeGenerator(value='2024-01-15 10:30:00')"/>
        <key name="issue_date" script="issued_at" outDateFormat="%Y-%m-%d"/>
        <key name="due_date" script="issued_at.add_days(30)" outDateFormat="%Y-%m-%d"/>
    </generate>
</setup>

Sample weighted or unique inline values

Use weights for biased replacement sampling and unique for distinct picks without replacement; never combine both on one key.

<setup rngSeed="42">
    <generate name="value_pools" count="4" target="LogExporter">
        <key name="tier" values="'standard','premium'" weights="3,1"/>
        <key name="batch_code" values="'A','B','C','D'" unique="true"/>
    </generate>
</setup>

Rules and invalid combinations

A key requires one value-generation mode.

Attributes: type, source, values, script, generator, constant, pattern, string

Why: A field without a type, source, value pool, script, generator, constant, pattern, or string template cannot produce a value.

<key name="status" constant="active"/>

<key name="status"/>

Choose exactly one explicit key generation mode.

Attributes: source, values, script, generator, constant, pattern, string

Why: Combining source, values, script, generator, constant, pattern, or string would make ownership of the field value ambiguous.

<key name="status" constant="active"/>

<key name="status" constant="active" string="${status}"/>

weights requires an inline values pool.

Attributes: weights, values

Why: Each weight biases the corresponding values entry and has no meaning without that pool.

<key name="tier" values="'standard','premium'" weights="3,1"/>

<key name="tier" type="string" weights="3,1"/>

unique on a key requires an inline values pool.

Attributes: unique, values

Why: Key uniqueness is sampling without replacement from explicitly listed values; generators do not expose a finite pool here.

<key name="code" values="'A','B'" unique="true"/>

<key name="code" generator="IncrementGenerator" unique="true"/>

unique cannot be combined with weights.

Attributes: unique, weights

Why: Unique sampling is uniform without replacement; weights describe biased draws with replacement.

<key name="code" values="'A','B'" unique="true"/>

<key name="code" values="'A','B'" weights="1,2" unique="true"/>

Source parsing options require source.

Attributes: source, selector, separator

Why: selector, separator, and source-dependent options only modify a source read.

<key name="status" source="data/status.ent.csv" separator=","/>

<key name="status" type="string" separator=","/>

A key distribution requires an int or float range.

Attributes: distribution, type, min, max

Why: The key-level distribution shapes a numeric grid and is different from source-row distribution.

<key name="score" type="int" min="1" max="10" distribution="step"/>

<key name="score" type="string" min="1" max="10" distribution="step"/>

outDateFormat produces a string and rejects a non-string type.

Attributes: outDateFormat, type

Why: Formatting is the final presentation step; downstream expressions no longer receive the raw temporal value.

<key name="created" constant="2026-01-02" outDateFormat="%d.%m.%Y"/>

<key name="created" type="int" constant="2026-01-02" outDateFormat="%d.%m.%Y"/>

Integer granularity must be a whole number.

Attributes: type, granularity

Why: A fractional step cannot produce an integer grid without silent truncation.

<key name="score" type="int" granularity="2"/>

<key name="score" type="int" granularity="0.5"/>

defaultValue requires script.

Attributes: defaultValue, script

Why: The fallback is evaluated only when the scripted value is absent or its condition suppresses generation.

<key name="nickname" script="None" defaultValue="'unknown'"/>

<key name="nickname" constant="unknown" defaultValue="'fallback'"/>

nullQuota must be between 0 and 1.

Attributes: nullQuota

Why: The value represents a probability: 0 never emits null and 1 always emits null.

<key name="middle_name" type="string" nullQuota="0.5"/>

<key name="middle_name" type="string" nullQuota="1.1"/>

Allowed parents / Allowed children

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

Allowed children:

element

Related concepts and use cases

• Expression Evaluation and Lifetime — Explains the different evaluation lifetimes of literal values, cached expressions, and dynamic expressions so descriptor authors do not accidentally move runtime state into setup-time attributes.
• Variable Scoping in Nested Generates — Prevents accidental ancestor reads and shadowing, and routes memstore reads through the public Scripting API.
• Data De-identification — Distinguishes de-identification outcomes from masking, generalization, pseudonymization, and anonymization, then proves the current converter behavior with an executable source project.
• First DATAMIMIC Model — Builds the smallest model and then composes preparation and generation stages.
• Migrate Benerator Models to DATAMIMIC — Maps Benerator concepts to the current generated grammar without freezing another support matrix.
• Generate Values from Regular Expressions — Shows bounded structural patterns and explains why regex shape is not domain validation.
• Date and Time Generation — Explains deterministic windows, weighted selection, offsets, and epoch output.
• Generate Database-backed Sequences — Explains bounded database sequence reservation and its single-process policy.
• Custom Generators and Converters — Shows the trusted-code boundary and loader-provided base classes for project-local generators and converters without exposing internal import paths.
• Use the Scripting API in a Model — Shows all read-only scripting helpers together at their real expression-evaluation boundary.
• 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.
• Scripted Source Templates — Explains typed full-value source expressions, embedded string substitution, and the boundary between sourceScripted templates and field or generate scripts.
• Assemble a complex deterministic model — Provides the requirement-to-model sequence for products, field dependencies, relationships, targets, and acceptance evidence.

Attributes

Show all 29 attributes

condition

Condition for key data generation.

optional; string; Default: null.

constant

Constant value for key data.

optional; string; Default: null.

converter

Converter for key data transformation.

optional; string; Default: null.

database

Database client id when source equals 'database'.

optional; string; Default: null.

defaultValue

Default value for the key.

optional; string; Default: null.

distribution

Sampling distribution / sequence for ranged numeric key.

optional; string; Default: null; Values: uniform, cumulated, step, increment, randomWalk, shuffle, wedge, bitreverse, fibonacci, padovan.

generator

Predefined generators for key data generation.

optional; string; Default: null.

granularity

Step width of numeric grid; defaults 1 for int, 0.1 for float. On int, must be whole.

optional; string; Default: null.

inDateFormat

Input date format for key data.

optional; string; Default: null.

max

Maximum value for numerical generator.

optional; number; Default: null.

maxLength

Maximum length for binary payload generation.

optional; integer; Default: null.

mimeType

Optional MIME signature for binary payload generation.

optional; string; Default: null.

min

Minimum value for numerical generator.

optional; number; Default: null.

minLength

Minimum length for binary payload generation.

optional; integer; Default: null.

name

Name of the key.

required; string.

nullQuota

Null quota for key data generation.

optional; number; Default: null.

outDateFormat

Output date format for key data.

optional; string; Default: null.

pattern

Pattern for key data generation.

optional; string; Default: null.

script

Script for key data generation.

optional; string; Default: null.

selector

Selector for key data generation.

optional; string; Default: null.

separator

Separator for key data.

optional; string; Default: null.

source

Source of data for the key.

optional; string; Default: null.

string

String for the variable data generation.

optional; string; Default: null.

type

Data type of the key.

optional; string; Default: null; Values: string, int, integer, float, bool, binary.

unique

Emit each value at most once (distinct picks from values, no replacement).

optional; boolean; Default: null.

values

Comma-separated list of values for the key.

optional; string; Default: null.

variablePrefix

Prefix before field's name for string in key generation.

optional; string; Default: null.

variableSuffix

Suffix after field's name for string in key generation.

optional; string; Default: null.

weights

Comma-separated relative weights, one per values entry, for weighted random selection.

optional; string; Default: null.