IDs and sequences

Identifiers often need two different qualities: a readable business number and an opaque globally shaped ID. Generate each once and reuse it when fields must agree.

The result

The counter increases by one. UUID and ULID values are repeatable when the scenario, seed, and clock are unchanged:

{"orderNumber":100,"orderCode":"ORD-0100","orderId":"7a1093b6-025d-45ec-b30d-6e629d581c68","eventId":"06DQSACCH1AK2TGTTCRM9JTDH8"}
{"orderNumber":101,"orderCode":"ORD-0101","orderId":"a40ac3a9-f4ad-4aba-9f2c-9e2faaa388e0","eventId":"06DQSACCH0JAVAS2B78BGW76YR"}

Generate order identifiers

defaults:
  seed: 42
  clock:
    start: 2026-01-02T03:04:05Z
generators:
  - name: orders
    config:
      maxEvents: 2
    vars:
      number: =seq(start=100)
    value:
      orderNumber: $number
      orderCode: =format(ORD-%04d, $number)
      orderId: =uuid()
      eventId: =ulid()

seq(start?, step?, format?)

Returns a counter scoped to that evaluated field path. It starts at 0 and increases by 1 unless you override start or step.

customerNumber: =seq()
orderNumber: =seq(100)
oddNumber: =seq(start=1, step=2)
customerCode: =seq(format=CUST-%06d)
orderCode: =seq(start=1000, format=ORD-%d)

Three events:

{"customerNumber":0,"orderNumber":100,"oddNumber":1,"customerCode":"CUST-000000","orderCode":"ORD-1000"}
{"customerNumber":1,"orderNumber":101,"oddNumber":3,"customerCode":"CUST-000001","orderCode":"ORD-1001"}
{"customerNumber":2,"orderNumber":102,"oddNumber":5,"customerCode":"CUST-000002","orderCode":"ORD-1002"}

seq() does not use the random seed. It advances while the generator evaluator is active and restarts when that evaluator is recreated, such as a new run. Put it in vars when several fields need the same number; separate seq() expressions maintain separate counters.

format uses a Go fmt.Sprintf pattern. Use an integer placeholder such as %d, %03d, or %06d.

uuid()

Returns a lowercase UUID with version-4 and RFC 4122 variant bits. It is generated from the seed and the current generator, instance, event, and expression identity.

customerId: =uuid()

With seed 42:

{"customerId":"207036ef-22c5-415c-8dcf-7f43cc5e37c0"}

ulid()

Returns a 26-character uppercase ULID. Its time component comes from the scenario event clock; its random component uses the same deterministic identity inputs as other random functions.

eventId: =ulid()

With seed 42 and clock.start: 2026-01-02T03:04:05Z:

{"eventId":"06DQSACCH0H0HS2TDF1GYHXX08"}

Events with later scenario timestamps have later ULID time components. Multiple ULIDs at the same timestamp are deterministic, but this function does not promise monotonic ordering within that millisecond.

Moving or renaming an expression may change generated UUID and ULID values because expression identity is part of the random stream. Repeatability means the same scenario, seed, clock, and sampling order produce the same values.

Related: format readable codes and understand the scenario clock.

Next: generate random values.