Ruleset Generation Configuration

• Introduction
  • The discovery / generation split
  • Upgrading from earlier versions
  • Creating and Editing Configurations
  • Cloning and deleting
• Top-Level Structure
• Labels
  • Label Entry Fields
  • Skipping generation for a label
• Mask Types
  • Built-in Mask Types
  • Inline masks
• Imports and References
  • The imports block
  • Referencing a full mask
  • Referencing part of a mask
  • Limitations
• Label Reconciliation at Generation
• Generated Rulesets and Libraries
• Worked Example

Introduction

A ruleset generation configuration controls how DataMasque turns the labels discovered on your columns into a masking ruleset. It maps each label — such as first_name, email, or a custom label of your own — to the mask that ruleset generation should emit for columns carrying that label.

Unlike a discovery configuration, a ruleset generation configuration is not tied to a specific connection type: you can use the same configuration to generate rulesets for database or file connections, because a label-to-mask mapping is independent of where the data lives.

Here is a minimal ruleset generation configuration that maps two discovered labels to built-in masks:

labels:
  first_name:
    preset_mask: first_name_mask
  email:
    preset_mask: realistic_email_mask

Save it and select it when you generate a ruleset. Every column labelled first_name receives a first_name_mask, and every column labelled email receives a realistic_email_mask. The rest of this page covers the other mask forms you can map to, importing masks from a library, and what generation does with labels the config does not mention.

The discovery / generation split

Discovery and ruleset generation are two separate stages, driven by two separate configurations:

1. A discovery configuration controls the first stage — it defines the labels and the metadata / In-Data Discovery rules that assign those labels to columns.
2. A ruleset generation configuration controls the second stage — it maps the labels to masks, and you choose it when you generate a ruleset.

By selecting a different ruleset generation configuration, you can turn the same discovery results into different rulesets, and reuse a single one across many discovery configurations and connections.

Upgrading from earlier versions

In earlier versions, per-label mask and skip_generation settings lived inside the discovery configuration. Upgrading moves them automatically: each discovery configuration that carried those settings gains a companion ruleset generation configuration, usually named db_<name> or file_<name> (after the discovery configuration's type and name — very long names are shortened, and a numeric suffix is added if the name is already taken). Companions are schema-validated during the upgrade; open one in the editor to fully validate its masks against your installed mask set. To keep generating the same rulesets as before the upgrade, select that companion configuration when you generate — in the web interface, or by moving API calls to the endpoint versions that accept an rg_config selection (v3 of generate-ruleset, v2 of the file and async generate endpoints). Earlier endpoint versions keep working but always generate with the built-in default masks. Discovery configurations without per-label masks need no companion — selecting DataMasque Defaults behaves as before.

Creating and Editing Configurations

Ruleset generation configurations are managed from the Ruleset Generation Configurations page, reached from the sidebar (below Discovery Configurations):

1. Navigate to Ruleset Generation Configurations in the sidebar.
2. Click New configuration. The editor opens pre-populated with a copy of the current built-in defaults, which you can edit or clear. There is no Database / File choice to make — a ruleset generation configuration applies to both database and file connections.
3. Give the configuration a name and edit the YAML in the built-in editor.
4. Click Save to validate and store the configuration.

The editor is the same schema-assisted Monaco editor used for rulesets and discovery configurations. It validates your configuration against the ruleset generation configuration schema as you type: structural errors (invalid YAML, unknown fields, an unknown built-in mask name) are marked inline on the relevant line, and the imports block autocompletes to the ruleset libraries available on your instance. The server performs the same validation when you click Save and remains the authoritative check.

Once saved, a configuration can be selected when generating a ruleset.

Cloning and deleting

The Ruleset Generation Configurations list page shows every saved configuration with its validation status, and lets you filter by name.

• Clone an existing configuration to start a new one from a copy of its YAML.
• Delete a configuration to remove it. Once deleted, the configuration no longer appears in the list and cannot be selected for generation, but rulesets already generated from it are unaffected.

Top-Level Structure

A ruleset generation configuration has the following top-level sections:

# Optional: ruleset libraries this config references via `$ref`.
imports:
  - clients/pii_library

# Required: per-label mask entries, keyed by discovery label name.
labels:
  first_name:
    preset_mask: first_name_mask
  email:
    preset_mask: realistic_email_mask
  tax_file_number:
    mask:
      $ref: "clients/pii_library#masks/tfn_mask"
  gdpr_data_subject_id:
    skip_generation: true

Section	Required	Default	Description
labels	Yes	—	Per-label mask entries, keyed by discovery label name. See Labels.
imports	No	None	Names of the ruleset libraries this config references via $ref. See Imports and References.

Labels

The labels section is a mapping keyed by label name. Each key is the name of a label that a discovery configuration can assign to a column, and each value describes how columns carrying that label should be masked.

labels:
  first_name:
    preset_mask: first_name_mask
  social_security_number:
    preset_mask: social_security_number_mask

Label names correspond to the labels defined in your discovery configuration. A label that is discovered but has no entry here is reconciled at generation time.

Label Entry Fields

Field	Type	Required	Default	Description
preset_mask	string or null	No	null	The name of a built-in mask to generate for columns carrying this label. Mutually exclusive with mask.
mask	mask definition or null	No	null	An inline mask, or a $ref to a mask in an imported library, to generate for columns carrying this label. Mutually exclusive with preset_mask.
skip_generation	boolean	No	false	When true, no masking rule is generated for this label. Useful for audit-only labels. Cannot be combined with preset_mask or mask. See below.

Set at most one of preset_mask, mask, or skip_generation: true per label — a skipped label generates no masking rule, so a mask alongside it would never be used. When all three are omitted, columns carrying the label fall back to a data-type default mask.

Skipping generation for a label

Some labels are useful for discovery and reporting but should not be masked — for example a label used purely to mark columns for compliance auditing. Set skip_generation: true for such labels so that columns carrying them are left untouched by generation without producing a reconciliation warning:

labels:
  gdpr_data_subject_id:
    skip_generation: true

Mask Types

A label names the mask to generate through one of two mutually exclusive keys: preset_mask for a built-in mask name, or mask for an inline mask definition or a $ref to a mask in an imported ruleset library.

Built-in Mask Types

The simplest form is a preset_mask naming one of the following built-in mask types. These determine how discovered columns are masked during ruleset generation.

Mask reference	Masking behaviour
first_name_mask	Random first name from a seed file.
last_name_mask	Random last name from a seed file.
full_name_mask	Random first name + last name.
realistic_email_mask	Realistic, unique fake email address.
realistic_email_mask	Realistic email in firstname.lastname@domain format.
imitate_mask	Imitates the character pattern of the original value.
date_of_birth_mask	Date with the original age retained.
social_security_number_mask	Random SSN-format number.
country_mask	Random country name from a seed file.
country_abbreviation_mask	Random two-letter country code (ISO 3166 alpha-2).
state_mask	Random state or province name from a seed file.
us_state_mask	Random US state name.
us_state_short_mask	Random US state abbreviation.
city_mask	Random city name from a seed file.
county_mask	Random county name from a seed file.
post_code_mask	Random postal code from a seed file.
street_type_mask	Random street type (Avenue, Road, etc.).
street_type_abbreviation_mask	Random street type abbreviation (Ave, Rd, etc.).
address_mask	Full address composed from seed file fields. Format varies by locality.
street_address_mask	Street address from a seed file.
suburb_mask	Suburb or neighbourhood name from a seed file.
gender_mask	Fixed value REDACTED.
age_mask	Random number between 1 and 99.
login_mask	Random alphanumeric string (8–16 characters).
mac_address_mask	Imitates the original MAC address format.
ip_address_mask	Random IPv4 address.
job_position_mask	Random job title from a seed file.
company_mask	Random company name from a seed file.
nric_mask	Random Singapore NRIC-format string.
luhn_checksum_mask	Imitates the original value with a valid Luhn checksum.
payment_card_number_mask	Random credit card number with a valid checksum.
brazil_cpf_mask	Random Brazilian CPF number.
expiry_date_mask	Random card expiry date in MM-YYYY format.

Masks that draw values from a seed file (e.g. first_name_mask, address_mask, city_mask) select the seed file based on the configured locality. For example, if the locality is set to AU, the generated ruleset will prefer Australian seed files where they exist.

Inline masks

Instead of a preset_mask, you can write a full mask definition inline under mask, using the same YAML shape as a mask in a ruleset. This lets you use any mask type with any parameters:

labels:
  employee_id:
    mask:
      type: from_unique_imitate
      retain_prefix_length: 3
      skip_letters: true

DataMasque emits the inline mask verbatim into the generated ruleset for every column carrying the label.

Note: DataMasque writes an inline mask into the generated ruleset exactly as you authored it. The adjustments DataMasque makes automatically for built-in masks are not applied. These include:

• typecasts required by the target database or file format;
• truncation for columns narrower than the values the mask produces;
• removing specified hash columns from a rule that uses a unique-preserving mask, such as imitate_unique, which performs its own implicit hashing.

Make sure an inline mask suits every column its label matches. Prefer a preset_mask where that does what you need — DataMasque then applies these adjustments for you.

Imports and References

A ruleset generation configuration can reference masks stored in ruleset libraries, so a mask maintained in one place can be reused across many configurations. References use the same $ref syntax as rulesets — see References to Ruleset Libraries for the full syntax.

The imports block

Every library a configuration references must be declared in the top-level imports list, exactly as in a ruleset. If a $ref points at a library that is not imported, validation fails.

imports:
  - clients/pii_library         # library "pii_library" in namespace "clients"
  - common_masks                # library "common_masks" with no namespace

Referencing a full mask

To use a whole mask from a library, set a label's mask to a $ref pointing at it:

imports:
  - clients/pii_library

labels:
  date_of_birth:
    mask:
      $ref: "clients/pii_library#masks/date_of_birth_mask"

DataMasque keeps the referenced mask verbatim in the generated ruleset — it emits the $ref itself, not the resolved mask — and adds the library it points at to the generated ruleset's imports.

Referencing part of a mask

A $ref can also appear inside an inline mask, to pull just one field from a library. For example, to reuse a shared list of choices while keeping the rest of the mask local:

imports:
  - common_masks

labels:
  order_status:
    mask:
      type: from_choices
      choices:
        $ref: "common_masks#other/order_statuses"

Here the mask is defined inline, but its choices value is read from the common_masks library. As above, DataMasque preserves the reference verbatim in the generated ruleset and imports the library.

Limitations

• Only external references are supported. Every $ref in a ruleset generation configuration must point at an imported ruleset library ("<library>#<path>"). A bare self-reference (a $ref of the form "#<path>", with no library name) is not supported. A ruleset generation configuration holds only label-to-mask entries, so there is nothing for a self-reference to point at.
• A $ref can only reference a ruleset library — the only kind of library a ruleset generation configuration can import.
• Every referenced library must be listed in imports.

Label Reconciliation at Generation

Because discovery and generation are configured separately, a discovery run can find a label on a column that the ruleset generation configuration does not list at all. DataMasque reconciles this when you generate a ruleset, and records any warning in a documentation block at the top of the generated ruleset.

Such columns are masked with a generic data-type default mask instead of an appropriate one. The generated ruleset lists the affected columns:

The following columns matched a label that has no mask configured, so a generic default mask was used instead. To choose the mask yourself, set a mask for these labels in a ruleset generation configuration:

• "employees"."full_name" (matched label full_name)

To resolve the warning, add the label to your ruleset generation configuration, or set skip_generation: true if the columns should intentionally be left unmasked. Only columns included in the generated ruleset are considered — a label discovered only on columns you did not select does not produce a warning.

A label that is listed but sets neither preset_mask nor mask is not a warning: an empty entry is the explicit way to accept the data-type default for that label.

Generated Rulesets and Libraries

When a label's mask is (or contains) a $ref, the generated ruleset keeps that reference verbatim and lists the referenced library in its own top-level imports block. The reference is only resolved at the start of a masking run, when DataMasque loads the imported libraries and resolves every $ref.

Important: A generated ruleset that references a library is not self-contained. The referenced ruleset library must exist wherever the ruleset is run, under the same name and namespace, or the masking run will fail to resolve the reference.

Worked Example

A complete, self-contained ruleset generation configuration that combines all three mask forms — a built-in mask name, an inline mask, and a library $ref — plus a skipped label:

imports:
  - clients/pii_library

labels:
  # Built-in mask name.
  first_name:
    preset_mask: first_name_mask

  # Inline mask definition.
  employee_id:
    mask:
      type: from_unique_imitate
      retain_prefix_length: 3
      skip_letters: true

  # Full mask pulled from an imported library.
  date_of_birth:
    mask:
      $ref: "clients/pii_library#masks/date_of_birth_mask"

  # Discovered for compliance auditing, but intentionally left unmasked.
  gdpr_data_subject_id:
    skip_generation: true