Syntax

Scenario values can be fixed, calculated, or copied from another visible value. The first character tells Synthtraffic which behavior you want.

The result

The product name and availability stay fixed. The number changes for each event, and both fields that use it agree:

{"productName":"Wireless headphones","productNumber":1,"sku":"PROD-001","available":true}
{"productName":"Wireless headphones","productNumber":2,"sku":"PROD-002","available":true}

Read the three value forms

defaults:
  seed: 42
generators:
  - name: products
    config:
      maxEvents: 2
    vars:
      number: =seq(start=1)
    value:
      productName: Wireless headphones
      productNumber: $number
      sku: =format(PROD-%03d, $number)
      available: true

• Wireless headphones and true are plain values. Synthtraffic copies them as written.
• =seq(start=1) and =format(...) are expressions. The leading = asks Synthtraffic to call a built-in function.
• $number is a reference. The leading $ copies a value that is already visible in the current generator.

vars.number is calculated once per event. It stays out of the output unless a field under value copies or uses it.

Compact expressions

A compact expression starts with = and must contain a function call:

customerId: =uuid()
amount: =uniform(10, 100, round=2)
label: =format(customer-%03d, seq(start=1))

{"customerId":"207036ef-22c5-415c-8dcf-7f43cc5e37c0","amount":86.94,"label":"customer-001"}

Calls can contain other calls. Positional arguments must come before named arguments:

amount: =normal(2500, 900, min=200, max=10000, round=2)

{"amount":2959.21}

=normal(mean=2500, 900) is invalid because a positional argument follows a named one.

Block expressions

Functions that describe a larger object or list use an indented block:

items:
  =array:
    count: 2
    of:
      productId: =uuid()
      quantity: =int(1, 5)

{"items":[{"productId":"60b7529e-bf1f-4b5e-8b70-a7b5d26b30aa","quantity":1},{"productId":"1d267630-784e-472d-8995-c3154c000c40","quantity":4}]}

The expression name is still explicit: =array: sets items to the generated list. array, case, and easingChain require block form. categorical, merge, selectKeys, and omitKeys support it.

References and dependency order

References use $name or a dotted path such as $customer.customerId. They only read values in the current scope; use ref() for an event from another generator.

Fields may refer to another field in the same object even when the referenced field appears later:

value:
  total: =multiply($unitPrice, $quantity)
  unitPrice: 25
  quantity: 2

{"total":50,"unitPrice":25,"quantity":2}

Synthtraffic detects the dependency and calculates unitPrice and quantity before total. A missing path or a circular dependency is a validation error.

Literal and quoting rules

• Strings may be bare words like CREATED or quoted like "CREATED".
• Inside a call, true, false, null, integers, and decimals become typed values. Other bare arguments are strings.
• Quote strings that contain commas, parentheses, leading = or $, or significant spaces.
• Lists and objects use YAML or JSON syntax rather than compact expression syntax.
• There are no arithmetic operators. Use add, subtract, multiply, and related functions instead.
• Synthtraffic provides built-in functions only—no JavaScript, custom functions, or hidden scripting.

Before a run, Synthtraffic compiles these forms into a typed intermediate representation (IR) — a validated internal form of your scenario. The runtime evaluates that IR only; it never re-reads or interprets the original expression text.

Browse functions

• Generate counters and identifiers: IDs and sequences
• Generate numbers, booleans, strings, bytes, and durations: Random
• Pick values: Selection
• Generate realistic names and addresses: Faker
• Reshape and calculate data: Collections and Math
• Compare, format, and work with time: Logic, Strings and env, and Time

For generators, schedules, connections, and the rest of the document structure, see Scenario file.

Next: generate IDs and sequences.