Identifier

Generates a unique identifier: a GUID, a ULID, a UUID version 7, or a value built from a pattern such as ABC-0001-X.

Use it for keys and reference codes such as order numbers, ticket codes, batch identifiers and surrogate primary keys. The values are not validated against any external standard or check digit.

For an identifier in a published format with a check digit, such as a credit card number or an IBAN, use Format.

Sub-field: value

Every JSON block on this page is a single field object, one entry in a table's fields array. See Building a Request for the full request structure.

Properties

Property	Type	Default	Description
`caseOutput`	`CaseOutput`	`"None"`	Case transformation applied after the value is produced. `Guid` and `UuidV7` values are lowercase unless this is set.
`delimiter`	`string`	`"-"`	`Pattern` mode: separates whichever of `prefix`/`id`/`postfix` are present.
`id`	`IdentifierPart?`	none	`Pattern` mode: the required core part.
`map`	`object`	required	Maps the `value` sub-field to a destination column, usually a text column such as `VarChar`. A `Pattern` that is only a `Number` part can also be mapped to a numeric column. See Building a Request.
`mode`	`"Guid"` / `"Ulid"` / `"UuidV7"` / `"Pattern"`	`"Guid"`	How the value is produced.
`nullPercentageMax`	`number`	`0`	Upper bound (0-100) of the percentage of rows that should be null. See `nullPercentageMin`.
`nullPercentageMin`	`number`	`0`	Lower bound (0-100) of the percentage of rows that should be null. The rate is fixed once for the whole field from this range, not recalculated per row. Set equal to `nullPercentageMax` for an exact rate.
`postfix`	`IdentifierPart?`	none	`Pattern` mode: the part after `id`. Omit for no postfix at all.
`prefix`	`IdentifierPart?`	none	`Pattern` mode: the part before `id`. Omit for no prefix at all.
`seed`	`integer`	random	Per-field seed, overriding the request's own `seed` for this field only.
`unique`	`boolean`	`false`	Whether every generated value must differ from the others. `Guid`, `Ulid` and `UuidV7` have so many possible values that the limit is never reached. In `Pattern` mode, the number of distinct values is limited by the parts. A request for more unique rows than the field can produce is rejected before any data is generated, stating how many are available.

Modes

Guid produces a random GUID. It ignores every other property except caseOutput. Use it when the format of the identifier does not matter.
Ulid produces a ULID: the current time followed by random characters, using a 32-character alphabet that excludes letters easily confused with digits. Sorting the column orders the rows by creation time.
UuidV7 produces a UUID in the standard GUID format, with the current time in its leading digits, so it also sorts by creation time. Use it for a UUID column that needs to sort by creation time.
Pattern builds the value from up to three parts, prefix, id and postfix, separated by delimiter. Only id is required, so a pattern can be a single padded number or a value such as ABC-0001-X. Use it when the identifier must follow a specific format.

Reproducibility

Every mode returns the same values for the same seed, with two exceptions. Ulid and UuidV7 include the time of generation, which makes them sortable by creation time. That part does not depend on seed, so these two modes produce different values on every run, even with a fixed seed. Use Guid or Pattern when a request must produce identical output on every run.

Properties by mode

Property	Guid	Ulid	UuidV7	Pattern
`prefix`, `id`, `postfix`	Rejected	Rejected	Rejected	Yes
`delimiter`				Yes
`caseOutput`	Yes	Yes	Yes	Yes
`nullPercentageMin`, `nullPercentageMax`	Yes	Yes	Yes	Yes

prefix, id and postfix are rejected outside Pattern mode rather than ignored, because the other modes cannot use them. delimiter only separates those parts, so setting it in another mode has no effect and is accepted.

caseOutput applies in every mode, including Guid.

IdentifierPart

Each of prefix, id and postfix is a part. A part's type sets how its value is produced, so one pattern can combine, for example, a fixed department code, a sequential number and a random suffix.

Fixed produces the text in fixedValue on every row. Use it for a constant code, such as a system or region code.
Lookup selects one entry from lookupValues per row, by weight. Use it for a small set of known codes, such as site or department codes. Each entry is { value, weight }. Weights are relative, not percentages, so 6/3/1 gives the same split as 60/30/10. An entry with no weight has a weight of 1, so a list with no weights splits evenly.
RandomString produces a random alphanumeric string of randomLength characters on each row. Use it for a value that must not be predictable.
RandomLetters produces a random string of the letters A to Z only, with no digits. Use it for a position in the format that is always a letter, such as the first character of a value made of one letter and seven digits.
Number produces a number, sequential or random, as set by numberMode. Sequential starts at start and increases by step on each row. Random selects a value between min and max. padWidth pads either with leading zeros to a fixed width.

The properties that apply depend on type.

Property	Type	Default	Description
`type`	`"Fixed"` / `"Lookup"` / `"RandomString"` / `"RandomLetters"` / `"Number"`	`"Fixed"`	How this part produces its value.
`fixedValue`	`string`	none	The text produced on every row. Required.
`lookupValues`	`object[]`	none	The values to select from, each `{ value, weight }`. One is selected per row by weight. Required, and must not be empty. A weight must be greater than 0.
`max`	`integer`	`99999999`	Inclusive upper bound.
`min`	`integer`	`0`	Inclusive lower bound.
`numberMode`	`"Sequential"` / `"Random"`	`"Sequential"`	Whether the number starts at `start` and increases by `step`, or is selected at random between `min` and `max`.
`padWidth`	`integer?`	none	Pads the number with leading zeros to at least this many digits, so `1` at width `4` is written as `0001`. A longer number is not shortened. Must be at least 1.
`randomLength`	`integer`	none	Length of the random string produced on each row. Required, and must be at least 1.
`start`	`integer`	`1`	The first row's value.
`step`	`integer`	`1`	The amount added to the value on each row. Use `0` to repeat `start`, or a negative value to count down.

Properties by part type

Property	Fixed	Lookup	RandomString	RandomLetters	Number
`type`	Yes	Yes	Yes	Yes	Yes
`fixedValue`	Yes
`lookupValues`		Yes
`randomLength`			Yes	Yes
`numberMode`, `padWidth`					Yes
`start`, `step`					Yes
`min`, `max`					Yes

start and step apply when numberMode is Sequential, and min and max when it is Random.

Examples

Each example below is a single field object, one entry in a table's fields array within a full request. See Building a Request for how it fits into a full DatasetRequest.

A plain random GUID

{
  "type": "Identifier",
  "mode": "Guid",
  "map": { "value": { "column": "uuid", "dataType": "VarChar" } }
}

Sample output:

uuid
037771dd-9026-4cae-99c3-3c741dba9c3d
24e13eb1-2a09-42be-a397-804767f0f5a5
2ff8bac6-3049-41df-8605-9893e25413c8
b6b8cbd1-71ad-4295-b244-e08f0f66d429
62ae97cd-6cc1-40f3-9e80-5d04922b50cf

Identifiers that sort by creation time

Ulid and UuidV7 both start with the time of generation, so sorting the column orders the rows by creation time.

{
  "type": "Identifier",
  "mode": "Ulid",
  "map": { "value": { "column": "event_id", "dataType": "VarChar" } }
}

Sample output:

event_id
01M4E7R51TCA6W6V3CCSQKHJM2
01M4E7R51TCA6W6V3CCTCJ1NRW
01M4E7R51V8SNNN2QVW7X3K6M7
01M4E7R51V8SNNN2QVWBJ7S705
01M4E7R51V8SNNN2QVWBS7DDRD

The values have the same leading characters because the rows were generated within milliseconds of each other. Sorting the column as text returns the rows in generation order, including rows generated within the same millisecond.

UuidV7 produces values in the standard GUID format, which also sort by creation time:

{
  "type": "Identifier",
  "mode": "UuidV7",
  "map": { "value": { "column": "event_uuid", "dataType": "VarChar" } }
}

Sample output:

event_uuid
01a11c7c-8782-7fba-8c16-2d7df2dca9eb
01a11c7c-8783-700a-97bd-e40cf47edb17
01a11c7c-8783-700a-97bd-e40d951135b0
01a11c7c-8783-700a-97bd-e40e920136a4
01a11c7c-8783-700a-97bd-e40f02af64f6

An order number like `ORD-000123`

{
  "type": "Identifier",
  "mode": "Pattern",
  "prefix": { "type": "Fixed", "fixedValue": "ORD" },
  "id": { "type": "Number", "numberMode": "Sequential", "start": 1, "padWidth": 6 },
  "map": { "value": { "column": "order_number", "dataType": "VarChar" } }
}

Sample output:

order_number
ORD-000001
ORD-000002
ORD-000003
ORD-000004
ORD-000005

A padded running sequence with no prefix

Only id is required, so a pattern can consist of a single sequential number.

{
  "type": "Identifier",
  "mode": "Pattern",
  "id": {
    "type": "Number",
    "numberMode": "Sequential",
    "start": 1,
    "padWidth": 6
  },
  "map": { "value": { "column": "batch_id", "dataType": "VarChar" } }
}

Sample output:

batch_id
000001
000002
000003
000004
000005

A prefix selected from a set of site codes

{
  "type": "Identifier",
  "mode": "Pattern",
  "delimiter": "/",
  "prefix": {
    "type": "Lookup",
    "lookupValues": [
      { "value": "LDN", "weight": 3 },
      { "value": "NYC", "weight": 2 },
      { "value": "TYO" }
    ]
  },
  "seed": 2,
  "id": {
    "type": "Number",
    "numberMode": "Sequential",
    "start": 500,
    "step": 5,
    "padWidth": 5
  },
  "map": { "value": { "column": "asset_tag", "dataType": "VarChar" } }
}

Sample output. The site code is selected separately on each row, and the number increases on every row, whatever the site code:

asset_tag
NYC/00500
LDN/00505
LDN/00510
TYO/00515
LDN/00520
LDN/00525

A random number rather than a sequence

{
  "type": "Identifier",
  "mode": "Pattern",
  "prefix": { "type": "Fixed", "fixedValue": "INV" },
  "id": {
    "type": "Number",
    "numberMode": "Random",
    "min": 100000,
    "max": 999999
  },
  "map": { "value": { "column": "invoice_ref", "dataType": "VarChar" } }
}

Sample output:

invoice_ref
INV-805345
INV-360450
INV-298616
INV-918766
INV-644798

A ticket code like `SUP-7F3K9Q-EU`

{
  "type": "Identifier",
  "mode": "Pattern",
  "prefix": { "type": "Fixed", "fixedValue": "SUP" },
  "id": { "type": "RandomString", "randomLength": 6 },
  "postfix": {
    "type": "Lookup",
    "lookupValues": [{ "value": "US" }, { "value": "EU" }, { "value": "APAC" }]
  },
  "caseOutput": "Upper",
  "seed": 1,
  "map": { "value": { "column": "ticket_code", "dataType": "VarChar" } }
}

Sample output:

ticket_code
SUP-83GRNF-EU
SUP-X3N18B-APAC
SUP-ONAMPP-APAC
SUP-35DS6S-US
SUP-TVKPP0-APAC

Null rows

{
  "type": "Identifier",
  "mode": "Guid",
  "nullPercentageMin": 30,
  "nullPercentageMax": 30,
  "seed": 2,
  "map": { "value": { "column": "external_ref", "dataType": "VarChar" } }
}

Sample output:

external_ref
2495c693-e3b9-4c6f-b898-b7dd200bc116

16bdf02e-f246-46a9-936c-626933ef855a
f5b0530a-47a8-4f81-bf72-bc652bae5287

A license number of one letter and seven digits

RandomLetters produces only letters, so the first character is always a letter. RandomString can produce a digit in that position.

{
  "type": "Identifier",
  "mode": "Pattern",
  "delimiter": "",
  "prefix": { "type": "RandomLetters", "randomLength": 1 },
  "id": { "type": "Number", "numberMode": "Sequential", "start": 1, "padWidth": 7 },
  "map": { "value": { "column": "license_number", "dataType": "VarChar" } }
}

Sample output:

license_number
F0000001
C0000002
X0000003
T0000004
U0000005

Setting delimiter to an empty string joins the parts with no separator, as a fixed-width format requires.

For an identifier derived from the person in the same row, see Person.

An email address not linked to a person

Setting delimiter to @ makes id the local part of the address and postfix the domain.

{
  "type": "Identifier",
  "mode": "Pattern",
  "delimiter": "@",
  "id": { "type": "RandomLetters", "randomLength": 8 },
  "postfix": {
    "type": "Lookup",
    "lookupValues": [
      { "value": "example.com", "weight": 6 },
      { "value": "example.net", "weight": 3 },
      { "value": "example.org", "weight": 1 }
    ]
  },
  "caseOutput": "Lower",
  "seed": 2,
  "map": { "value": { "column": "email", "dataType": "VarChar" } }
}

Sample output:

email
ukezchul@example.com
ataanjhs@example.com
tcciitxv@example.net
ycryzcbi@example.net
rtrcbhgm@example.org

RandomLetters excludes digits from the local part. With weights of 6, 3 and 1, about 60% of rows have the first domain, 30% the second and 10% the third.

These addresses are not related to any other column. For an address derived from the name in the same row, use Person.

Table of Contents

Identifier

Properties

Modes

Reproducibility

Properties by mode

IdentifierPart

Properties by part type

Examples

A plain random GUID

Identifiers that sort by creation time

An order number like ORD-000123

A padded running sequence with no prefix

A prefix selected from a set of site codes

A random number rather than a sequence

A ticket code like SUP-7F3K9Q-EU

Null rows

A license number of one letter and seven digits

An email address not linked to a person

An order number like `ORD-000123`

A ticket code like `SUP-7F3K9Q-EU`