# Generate Realistic Fake Data From a Schema

![banner](https://articles.aux4.blog/data/posts/aux4/generate-realistic-fake-data/banner.png)

## Introduction

Tests, demos, and staging databases all need data that *looks* real — believable names, valid emails, sensible numbers — without hand-typing any of it. `aux4/faker` generates exactly that from the command line. This post walks from single throwaway values up to fully-shaped records and enriching data you already have.

## Install the package

```bash
aux4 aux4 pkger install aux4/faker
```

## Single values

`aux4 fake value` takes a **category** and a `--type`. It prints one value:

```bash
aux4 fake value person --type firstName     # -> Jaunita
aux4 fake value internet --type email       # -> Royce_Olson@yahoo.com
aux4 fake value string --type uuid          # -> f69dcf30-f74c-4892-bab9-29d6542eb031
```

Types take arguments through `--arg key=value`, and `--lang` switches locale:

```bash
aux4 fake value number --type int --arg min=1 --arg max=100    # -> 87
aux4 fake value commerce --type price --arg min=5 --arg max=50  # -> 11.45
aux4 fake value person --type firstName --lang pt_BR            # -> Ladislau
```

Run `aux4 fake list` to browse every category (`person`, `internet`, `location`, `commerce`, `date`, and more). Add `--count` to get a JSON array instead of a single value:

```bash
aux4 fake value internet --type email --count 3
```

```json
["Pink10@gmail.com", "Marcelo.Langosh@yahoo.com", "Candida46@gmail.com"]
```

## Whole records

Real fixtures are objects, not loose values. Describe the shape in a `config.yaml` under a named config — each field gets a `fake` spec written as `<category> <type>`, or an expanded form with `args`:

```yaml
config:
  user:
    mapping:
      firstName:
        fake: person firstName
      email:
        fake: internet email
      age:
        fake:
          category: number
          type: int
          args:
            min: 18
            max: 65
      role:
        fake:
          category: helpers
          type: arrayElement
          args:
            - - admin
              - editor
              - viewer
      address:
        mapping:
          city:
            fake: location city
          country:
            fake: location country
```

`arrayElement` picks from a fixed set — the double-nested list is the array passed as its argument — and a nested `mapping:` builds a nested object. `aux4 fake object` reads stdin (for the enrich mode below), so redirect `/dev/null` when you just want fresh records:

```bash
aux4 fake object --config user --count 2 < /dev/null
```

```json
[
  {
    "firstName": "Amara",
    "email": "Eriberto.Erdman37@hotmail.com",
    "age": 52,
    "role": "editor",
    "address": { "city": "New Isac", "country": "Saint Barthelemy" }
  },
  {
    "firstName": "Yesenia",
    "email": "Hal_Luettgen36@gmail.com",
    "age": 26,
    "role": "admin",
    "address": { "city": "Heathcotefort", "country": "Aruba" }
  }
]
```

Fields can also reference each other with `@`. Point `firstName`'s `sex` argument at a generated `sex` field so the two agree:

```yaml
config:
  person:
    mapping:
      sex:
        fake: person sex
      firstName:
        fake:
          category: person
          type: firstName
          args:
            sex: "@sex"
```

```bash
aux4 fake object --configFile person.yaml --config person --count 3 < /dev/null
```

```json
[
  { "sex": "male", "firstName": "Luther" },
  { "sex": "female", "firstName": "Jennyfer" },
  { "sex": "male", "firstName": "Dana" }
]
```

## Enrich existing data

Pipe records in and `fake object` *adds* the mapped fields, keeping what's already there. Add an `addEmail` config next to `user`:

```yaml
config:
  addEmail:
    mapping:
      email:
        fake: internet email
```

Input type decides output type — NDJSON in, NDJSON out — so it slots into a stream:

```bash
printf '{"id":1}\n{"id":2}\n' | aux4 fake object --config addEmail
```

```json
{"id":1,"email":"Roxane_Frami22@yahoo.com"}
{"id":2,"email":"Olaf_Upton@gmail.com"}
```

This is how you backfill a column of fake emails onto real ids, or top up a table of records that's missing a field.

## Conclusion

`aux4/faker` scales from a one-off value to structured records with enums, nested objects, and cross-field references — and it enriches data you already have. Point a `config.yaml` at your schema and you have a repeatable fixture generator you can pipe straight into a database or an API.

## See Also

- [aux4/faker](https://hub.aux4.io/r/public/packages/aux4/faker)