Field options

Every field is a YAML mapping with at least a name and a type. On top of the type's own parameters, three families of options apply.

Common options

Accepted by every field type.

Parameter Values Default Description
name text — Required. Output field name, unique within its scope. Tabular formats use it as the column name.
type text — Required. Field type, one of the types listed in this reference.
label text — Human-friendly label shown in the recipe builder. Not used in the output.
unique boolean false No repeated values within one job. The job fails when the type cannot produce enough distinct values.
emptyRate number 0 Fraction from 0 to 1 of records where the field is empty: an empty CSV/TSV/XLSX cell, JSON null, Parquet null.
cardinality low, medium, high, unique — Repetition hint. unique is the same as unique: true; low, medium and high are accepted but do not change the output yet. Exclusive with unique.

unique is checked while generating. When a type runs out of distinct values — httpMethod has seven — the job fails instead of repeating one. For boolean and enum the validator catches it before the job starts.

emptyRate is not allowed on autoint, which always has a value.

Textual constraints

Types marked as textual in their reference also take these. They apply to the final value, in this order: add prefix and suffix, change case, then check length and characters.

Parameter Values Default Description
minLength integer — Minimum length of the final value, in Unicode characters.
maxLength integer — Maximum length of the final value, in Unicode characters.
prefix text — Text prepended to the value. Counts toward the length limits.
suffix text — Text appended to the value. Counts toward the length limits.
lowercase boolean — Convert the final value to lowercase. Exclusive with uppercase.
uppercase boolean — Convert the final value to uppercase. Exclusive with lowercase.
ascii boolean — Only ASCII characters. Localized names switch to their romanized form (Müller becomes Mueller).
digitsOnly boolean — Only the digits 0-9.
allowedRunes text — The only characters the value may contain, written as one string.
forbiddenRunes text — Characters the value must not contain, written as one string.

Case changes, prefix and suffix always transform the value. The length and character options are guarantees, not shapers: the generator does not bend its output to fit them. A value that breaks one fails the job, so a username with maxLength: 8 fails as soon as a longer name comes up. Two exceptions:

  • regexp retries each value up to maxAttempts times before failing.
  • text with the default words category uses minLength/maxLength to pick the length of a run of letters.

To produce a specific shape, describe it with the generator instead:

shapes.yaml
version: "1"
output: { language: eng, format: csv, quantity: 5 }
fields:
  - { name: pin, type: regexp, pattern: "[0-9]{6}" }            # six digits
  - { name: plate, type: pattern, pattern: "???-####", uppercase: true }
  - { name: sku, type: regexp, pattern: "[A-Z0-9]{8}", prefix: "SKU-" }

Relational constraints

A field can depend on a field declared earlier in the same scope (the top-level list, or the same json object).

Parameter Values Default Description
eqfield field name — Copy the value of an earlier field. Exclusive with gtfield and ltefield.
gtfield field name — Regenerate until the value is greater than an earlier field (numbers, dates, strings).
ltefield field name — Regenerate until the value is less than or equal to an earlier field.
relational.yaml
version: "1"
output: { language: eng, format: csv, quantity: 5 }
fields:
  - { name: start, type: date, min: "2024-01-01", max: "2024-06-30" }
  - { name: end, type: date, min: "2024-01-01", max: "2024-12-31", gtfield: start }
  - { name: min_price, type: decimal, min: 10, max: 50 }
  - { name: max_price, type: decimal, min: 10, max: 100, gtfield: min_price }

gtfield and ltefield regenerate the value until it fits, up to 256 tries per record, so keep the ranges overlapping generously. When the referenced field is empty for a record, the constraint is skipped for that record.

Limits

Limit Maximum
Characters in one text value, template, pattern or enum value 65,536
Words in one text value (minWords/maxWords) 10,000
Bytes in one binary or base64 value 1,048,576
Items in one json array (maxItems) 1,000
regexp attempts per value (maxAttempts) 10,000
Characters in one password 4,096