# JSON Mask

This is a [composite generator](https://docs.tonic.ai/app/generation/generators/generator-types/generators-composite).

Runs a selected sub-generator on values that match a user specified [JSONPath](https://goessner.net/articles/JsonPath/index.html#e2).  You can only search for and apply sub-generators to individual key values. You cannot apply a sub-generator to an object or to an array.

If an error occurs, the selected fallback generator is used for the entire JSON value.

For JSON columns in a file connector workspace, you can instead use **Document View** to assign generators to individual paths. For more information, go to [json-document-view](https://docs.tonic.ai/app/generation/working-with-document-based-data/json-document-view "mention").

## Sequence for applying the sub-generators <a href="#json-mask-sub-generator-sequence" id="json-mask-sub-generator-sequence"></a>

Sub-generators are applied sequentially, from the sub-generator at the top of the list to the sub-generator at the bottom of the list.

If a key matches more than one JSONPath expression, then the most recently added generator takes priority.

## JSON path options <a href="#json-mask-json-path" id="json-mask-json-path"></a>

### Regular expressions and comparisons <a href="#json-mask-json-path-regex" id="json-mask-json-path-regex"></a>

JSON paths can also contain regular expressions and comparison logic, which allow the configured sub-generators to be applied only when there are properties that satisfy the query.

For example, a column contains this JSON:

`[ { file_name: "foo.txt", b: 10 }, ... ]`

The following JSON path only applies to array elements that contain a `file_name` key for which the value ends in `.txt`:

`$.[?(@.file_Name =~ /^.*.txt$/)]`

### Using recursion <a href="#json-mask-json-path-recursion" id="json-mask-json-path-recursion"></a>

A JSON path can also be used to point to a key name recursively. For example, a column contains this JSON:

```json
{
  "first_name": "John",
  "last_name": "Smith",
  "children": [
    {
      "first_name": "Mary",
      "last_name": "Jones",
      "children": [
        {
          "first_name": "Ann",
          "last_name": "Jones"
        }
      ]
    }
  ]
}
```

The following JSON path applies to all properties for which the key is `first_name`:

`$..first_name`

## Characteristics <a href="#json-mask-characteristics" id="json-mask-characteristics"></a>

<table data-header-hidden><thead><tr><th valign="top"></th><th valign="top"></th></tr></thead><tbody><tr><td valign="top"><strong>Consistency</strong></td><td valign="top">Determined by the selected sub-generators.</td></tr><tr><td valign="top"><strong>Linking</strong></td><td valign="top">Determined by the selected sub-generators.</td></tr><tr><td valign="top"><strong>Differential privacy</strong></td><td valign="top">Determined by the selected sub-generators.</td></tr><tr><td valign="top"><strong>Data-free</strong></td><td valign="top">Determined by the selected sub-generators.</td></tr><tr><td valign="top"><strong>Allowed for primary keys</strong></td><td valign="top">No</td></tr><tr><td valign="top"><strong>Allowed for unique columns</strong></td><td valign="top">No</td></tr><tr><td valign="top"><strong>Uses format-preserving encryption (FPE)</strong></td><td valign="top">No</td></tr><tr><td valign="top"><strong>Privacy ranking</strong></td><td valign="top">5</td></tr><tr><td valign="top"><strong>Generator ID (for the API)</strong></td><td valign="top"><a href="../../../api/quick-start-guide/tonic-api-generator-assignment/generator-api-reference/generator-api-ref-json-mask"><code>JsonMaskGenerator</code></a></td></tr></tbody></table>

## How to configure <a href="#json-mask-configure" id="json-mask-configure"></a>

### Adding a sub-generator <a href="#json-mask-add-sub-generator" id="json-mask-add-sub-generator"></a>

To assign a generator to a path expression:

1. Under **Sub-generators**, click **Add Generator**.\
   \
   On the sub-generator configuration panel, the **Cell JSON** field contains a sample value from the source database. You can use the previous and next icons to page through different values.
2. In the **Path Expression** field, type the path expression to identify the value to apply the generator to. You cannot use the exact same path expression more than once.\
   \
   To create a path expression, you can also click the value in **Cell JSON** that you want the expression to point to.\
   \
   The path expression must identify a key value. You cannot apply sub-generators to an object or to an array.\
   \
   **Matched JSON Values** shows the result from the value in **Cell JSON**.
3. By default, the selected generator is applied to any value that matches the expression.\
   \
   To limit the types of values to apply the generator to, from the **Type Filter**, specify the applicable types.\
   \
   You can select **Any**, or you can select any combination of **String**, **Number**, **Boolean**, and **Null**.
4. From the **Generator Configuration** dropdown list, select the generator to apply to the path expression.\
   \
   You cannot select another composite generator.
5. Configure the selected generator.\
   \
   You cannot configure the selected generator to be consistent with another column.
6. To save the configuration and immediately add a generator for another path expression, click **Save and Add Another**.\
   \
   To save the configuration and close the add generator panel, click **Save**.

### Managing the sub-generators list <a href="#json-mask-manage-sub-generators" id="json-mask-manage-sub-generators"></a>

From the **Sub-Generators** list:

* To edit a generator assignment, click the edit icon.
* To remove a generator assignment, click the delete icon.
* To move a generator assignment up or down in the list, click the up or down arrow.

### Selecting the fallback generator <a href="#json-mask-fallback-generator" id="json-mask-fallback-generator"></a>

From the **Fallback Generator** dropdown list, select the generator to use if the assigned generator for a path expression fails.

The options are:

* [Passthrough](https://docs.tonic.ai/app/generation/generators/generator-reference/passthrough)
* [Constant](https://docs.tonic.ai/app/generation/generators/generator-reference/constant)
* [Null](https://docs.tonic.ai/app/generation/generators/generator-reference/null)