Recipe structure

A recipe — formally a DDRR, Declarative Data Request Recipe — is a YAML document that describes one batch of records: what each record contains, how many to make, in which language and in which format.

customers.yaml
version: "1"
output:
  language: eng
  format: csv
  quantity: 100
  options: { header: true }
fields:
  - { name: id, type: autoint }
  - { name: name, type: text, category: fullName }
  - { name: email, type: email, unique: true }
  - { name: country, type: country, value: iso2 }
  - { name: signed_up, type: date, range: past }

Top-level keys

Key Required Meaning
version yes Always "1", quoted.
output yes Language, format, size and format options. See below.
fields yes The ordered list of fields. Tabular formats use this order for their columns.
scenario with output.package The HTTP requests of a test bundle.

Unknown keys are rejected, at the top level and inside fields, so a typo such as uniqe: true fails validation instead of being ignored.

The output section

Parameter Values Default Description
language text — Required. ISO 639-3 code of the output language, such as eng, por or deu. It drives names, places and random text. Only complete languages are offered; see the catalog.
format csv, tsv, json, xlsx, parquet, pdf, xml, yaml, sql — Required. Output format.
quantity integer — Required. Number of records. May be omitted when a catalog field sets all: true.
files integer 1 Split the records across this many files, delivered as one ZIP. At most quantity.
filename text ghostbakery-output Base name of the output file, without a path.
charset utf-8 utf-8 Output encoding. Only UTF-8.
package k6, artillery, jmeter, postman, hurl, http — Build a runnable HTTP test bundle for this tool. Requires a scenario.
options map — Format-specific options, listed per format.

Each format's options are listed in Output formats.

Fields

Each entry of fields is a mapping with a name and a type, plus the parameters of that type:

fields.yaml
version: "1"
output: { language: eng, format: json, quantity: 3 }
fields:
  - name: status              # block style...
    type: enum
    values: [pending, active, blocked]
  - { name: score, type: integer, min: 0, max: 10 }   # ...or flow style

Names must be unique within their scope. A field may refer to earlier fields — in a template, a hash or a relational constraint — but never to a later one.

See all field types and the options every field takes.

Validation errors

A recipe is validated completely before anything is charged. Every problem is reported at once, each with the path of the offending key:

422-response.json
{
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "validation failed",
  "errors": [
    { "location": "fields[2].unique", "message": "cannot be satisfied: boolean only has 2 possible values" },
    { "location": "output.format", "message": "is unsupported" }
  ]
}

The recipe builder shows the same messages. Some problems can only surface while generating — unique running out of values, or a textual constraint rejecting a value. The job then fails, its credits are refunded, and the job status carries the error.

Each job is also capped in records, fields and estimated memory. The estimate tells you when a recipe goes over a cap.