DataMasque Portal

Ruleset Library Structure

This page describes how ruleset libraries are named and structured.

Name and Namespace

A library has a name and an optional namespace.

  • The name can consist of up to 255 characters. Any character is allowed except / (slash).
  • The namespace is an optional attribute used to group related libraries together. Namespaces help organise libraries by domain or team and prevent name collisions when different teams create libraries independently. For example, you might have a sales_db namespace with libraries customers_library and orders_library.
  • Namespaces can be up to 255 characters long, including slashes, but may not start or end with a slash, nor contain two consecutive slashes.

When referring to a library with $ref (see the page on referencing):

  • If the library has no namespace, just use the library name.
  • If the library has a namespace, prefix the library name with its namespace and a slash.

Library name examples

Library name Valid?
my_library Valid
2026library Valid
library/name Invalid (library names cannot contain slashes)

Namespace examples

Namespace name Valid?
sales_db Valid
sales_db/2026 Valid (reference as sales_db/2026/library_name)
/sales_db/2026 Invalid (cannot start with a slash)
sales_db/2026/ Invalid (cannot end with a slash)
sales_db//2026 Invalid (cannot contain consecutive slashes)

Version

Like rulesets, all libraries must have a version field. Currently, the only supported version is 1.0. The field is a string, so the version must be quoted: version: "1.0".

version: "1.0"

Sections

A ruleset library has up to seven sections, each representing a different level of granularity:

  • masks - individual masks
  • database_rules - rules for mask_table, including target column
  • tabular_file_rules - rules for mask_tabular_file, including target column
  • file_rules - rules for mask_file
  • columns - a list of masks (usable in both database and file masking)
  • tasks - complete task definitions
  • other - freeform constant values

The database_rules, file_rules and tabular_file_rules sections support optional conditional rules (if). See the documentation on conditional masking for further details:

Each section is a dictionary mapping user-defined keys to their values, allowing you to give your masks, rules, and so on meaningful names. All sections except other have a fixed structure; other accepts any arbitrarily-nested structure of dictionaries, arrays, and/or scalar values.

masks Section

The masks section defines individual masks.

  • Specify masks as individual dictionaries, not array items.
  • For each mask, all required fields must be present and all fields must have valid values.

This example shows two masks named name and date_of_birth.

masks:
  name:
    type: from_file
    seed_file: DataMasque_firstNames_mixed.csv
    seed_column: firstname-mixed
  date_of_birth:
    type: retain_age

database_rules Section

The database_rules section contains rules for database masking (mask_table). This is similar to columns, but rules include the column field and can also contain if conditionals.

This example shows a reusable mask_pci rule that could be used across multiple tables containing a credit_card column.

database_rules:
  mask_pci:
    column: '"credit_card"'
    masks:
      - type: credit_card
        on_invalid: skip
        pan_format: true

tabular_file_rules Section

The tabular_file_rules section contains rules for tabular file masking (mask_tabular_file). The format is the same as database_rules.

tabular_file_rules:
  mask_pci:
    column: '"credit_card"'
    masks:
      - type: credit_card
        on_invalid: skip
        pan_format: true

file_rules Section

The file_rules section contains rules for file masking (mask_file). The format is similar to database_rules, but uses hash_sources instead of hash_columns and does not have a column field.

file_rules is not the same as columns: both contain a list of masks under a masks key, but file_rules can contain if conditionals. This example shows a conditional file masking rule designed for JSON/NDJSON files, named gender_firstname. If the gender field contains the value female or is absent, it replaces the first_name field with Alice. Otherwise, the first_name is changed to Bob.

file_rules:
  gender_firstname:
    if:
      - json_path: ["gender"]
        equals: "female"
    on_missing: apply_if_rules
    rules:
      - masks:
          - type: json
            transforms:
              - path: ["first_name"]
                on_missing: error
                masks:
                  - type: from_fixed
                    value: "Alice"
    else_rules:
      - masks:
          - type: json
            transforms:
              - path: ["first_name"]
                on_missing: error
                masks:
                  - type: from_fixed
                    value: "Bob"

columns Section

The columns section defines lists of masks. These must be wrapped under a masks key, and again, all masks must have all required fields present and valid field values.

This example shows a list of masks named uppercase_imitate.

columns:
  uppercase_imitate:
    masks:
      - type: from_unique_imitate
        skip_digits: true
      - type: transform_case
        transform: uppercase

This can be used in a rules section for both database masking and file masking, for example:

tasks:
  - type: mask_table
    table: customers
    key: customer_number
    rules:
      - column: customer_id
        $ref: "customer_library#columns/uppercase_imitate"

tasks:
  # Masking text files containing only customer IDs
  # (demonstrating how to use a `columns` entry at the `rules` level of a task)
  - type: mask_file
    include:
      - glob: "*.txt"
    rules:
      - $ref: "customer_library#columns/uppercase_imitate"

  # More realistic example: masking customer IDs in NDJSON data
  - type: mask_file
    include:
      - glob: "*.ndjson"
    rules:
      - masks:
          - type: json
            transforms:
              - path: ['customer_id']
                $ref: "customer_library#columns/uppercase_imitate"

tasks Section

The tasks section contains entire tasks. The tasks can be of any type defined in the Ruleset YAML Specification. Tasks must have all required fields present, and all fields must have valid values (which can be placeholders).

The following library snippet defines a run_sql task named drop_orders_customers_fk that drops a foreign key.

tasks:
  drop_orders_customers_fk:
    type: run_sql
    sql: >
      ALTER TABLE "orders" DROP CONSTRAINT "fk_orders_customers";

other Section

The other section is a freeform dictionary. Use it to define constant values that you would want to reference elsewhere, for example table names, from_choices lists, or prefixes for identifiers. You can also use it to define parts of masks if the restriction that masks or rules must be complete is too restrictive for your use case, as an alternative approach to specifying placeholder values and overriding them when referencing the mask in the ruleset.

This example declares some constant values that might be used in various places - a scalar, an array, and a dictionary.

other:
  id_prefix: "MASKED_"
  order_status_choices:
    - PLACED
    - IN_PROGRESS
    - DISPATCHED
    - DELIVERED
  common_fui_options:
    type: from_unique_imitate
    skip_digits: true
    retain_prefix_length: 3

Locality Interpolation

Libraries do not support locality interpolation.

You can still use locality interpolation in rulesets that import libraries. See the referencing guide for details.