Configuration format

A configuration is YAML with two sections: where the output goes, and what the data looks like.

Output:
  Path: customers.csv          # relative to this file
  Format: CSV                  # CSV | JSON | XLSX

Schema:
  RowCount: 1000
  GlobalSeed: 20260822
  UniqueConstraints: []
  Columns: []

Output

Key	Meaning
Path	Where to write. Relative paths resolve against the configuration file, not the working directory.
Format	CSV, JSON, or XLSX. Must agree with the extension.

The command line can override both with --output.

Schema

Key	Meaning
RowCount	How many rows. Must be greater than zero.
GlobalSeed	The seed. Omit it and a random one is used and printed - fix it if you want the run to be repeatable.
UniqueConstraints	A list of lists of column ids. See Uniqueness.
Columns	The columns, in output order.

A column

    - Id: 7e57d004-2b97-0e7a-b45f-5387367791cd
      Name: customer_id
      IsOptional: false
      FillProbability: 1.0
      IsExcludedFromOutput: false
      Generator:
        Type: Guid
        Settings: {}

Key	Meaning
Id	A GUID identifying the column. Part of the reproducibility guarantee - it derives the column's seed, so do not change it casually.
Name	The column header.
IsOptional	When true, some cells are left blank.
FillProbability	With IsOptional, the chance a cell is filled. 0.9 leaves roughly one in ten blank.
IsExcludedFromOutput	Generate the column but do not write it. Useful for a value other columns reference.
Generator.Type	The column type, by name - see Column types.
Generator.Settings	That type's options. Omitted keys take their defaults.

Settings

Every option has a default, and an omitted key keeps the behaviour the version before it had. So a configuration written against an older release keeps producing what it always did.

      Generator:
        Type: Date
        Settings:
          Min: 2000-01-01
          Max: 2030-12-31
          IncludeTime: false      # a date with no time component

      Generator:
        Type: Pick List
        Settings:
          ValueType: String       # String | Integer | Decimal | Boolean
          Values: [api, sso, billing, audit]
          MinPicks: 1
          MaxPicks: 2             # above 1, several distinct values per cell
          Separator: ", "         # CSV and Excel; JSON writes a real array

Paths

Any path in a configuration - the output, a file-backed column's source - is stored relative to the configuration file and written with forward slashes. That way a schema and the files it reads can be moved or shared together, and a configuration saved on Windows opens on Linux.

A missing source file is an error when the configuration is opened, not blank cells at the end of a run.