`util.nullable`

Wraps any sub-schema with configurable null probability. This is a convenience wrapper that makes it easy to create optional/nullable fields in simulation specs, providing a simpler alternative to manually using core.select with null options.

Keywords

`schema`required

The sub-schema to wrap. Can be any valid schema type. When a non-null value is generated, it will be produced by this sub-schema.

`percentage`

An integer between 0 and 100 (inclusive) that determines the probability of returning null. Default is 50 (equal chance of null or value).

0 - Never returns null (always delegates to sub-schema)
50 - 50% null, 50% value (default)
100 - Always returns null (never calls sub-schema)

Examples

Default 50% chance of null, wrapping a person.name schema:

{
  "type": "util.nullable",
  "schema": {
    "type": "person.name"
  }
}

20% chance of null (80% chance of value) for an email field:

{
  "type": "util.nullable",
  "percentage": 20,
  "schema": {
    "type": "internet.email"
  }
}

Using in an object schema to create an optional middle name field that is rarely present (80% null):

{
  "type": "object",
  "properties": {
    "id": {"type": "integer"},
    "firstName": {"type": "person.givenName"},
    "middleName": {
      "type": "util.nullable",
      "percentage": 80,
      "schema": {"type": "person.givenName"}
    },
    "lastName": {"type": "person.familyName"}
  }
}

Design Notes

This schema is optimized for the common use case of optional/nullable fields. It provides a more concise and readable alternative to core.select:

With util.nullable:

{
  "type": "util.nullable",
  "percentage": 20,
  "schema": {"type": "string"}
}

Without (using core.select):

{
  "type": "select",
  "options": [
    {
      "stream": {"type": "null"},
      "weight": 20
    },
    {
      "stream": {"type": "string"},
      "weight": 80
    }
  ]
}

The schema uses deterministic random number generation for reproducibility, ensuring that simulations with the same seed produce identical null/value sequences.

util.nullable