> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dataharbor.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Control

> Field-level privacy controls — redaction, tokenization, masking, hashing, and anonymization.

# Data Control

**Privacy controls, not privacy code.**

Field-level privacy controls that protect sensitive data without requiring engineering effort. Configure once, apply everywhere.

<Info>
  Data Control runs inside the ordered `controls` pipeline after [input normalization](../sources/input-normalization) and before [output formatting](../delivery/output-formatting). You can mix privacy filters with [data transforms](./data-transform) in the same object definition.
</Info>

<Tip>
  For a complete Virtual API Configuration, start with `version: "0.3"` and define controls under `objects.<objectName>.controls`. See [Virtual APIs](../core/virtual-apis) if you need a refresher on object definitions.
</Tip>

## Quick example

Use Data Control when you need to protect specific fields but still preserve the rest of the upstream shape:

```yaml theme={null}
version: "0.3"
objects:
  customers:
    controls:
      - type: redact
        fields: [ssn]
      - type: tokenize
        fields: [email]
      - type: mask
        fields: [phone]
```

Each control has two required properties:

* `type` — the operation to apply (`redact`, `tokenize`, `anonymize`, `mask`, `hash`, `allow`)
* `fields` — one or more field names to apply it to

You can also add `required: true` when a missing field should fail the request instead of being skipped.

## Choosing a control

| Control type | Use it when you need to                                              |
| ------------ | -------------------------------------------------------------------- |
| `redact`     | Blank out a value but keep the field present                         |
| `tokenize`   | Preserve correlation across records without exposing raw identifiers |
| `anonymize`  | Produce non-correlatable stand-ins for demos, testing, or ML         |
| `mask`       | Preserve some visual context while hiding most of the value          |
| `hash`       | Create a deterministic one-way value for deduplication or joins      |
| `allow`      | Be explicit about fields that should pass through unchanged          |

## Control types

### Redact

Remove sensitive data entirely. `redact` keeps the field in the response and only changes its value. If you want the field to disappear entirely, use `delete` from [Data Transform](./data-transform).

```yaml theme={null}
controls:
  - type: redact
    fields: [ssn, date_of_birth, drivers_license]
```

### Tokenize

Replace sensitive values with consistent, syntax-preserving tokens. The same input always produces the same token within the same Virtual API and matched object definition — enabling analytics without exposing raw data.

```yaml theme={null}
controls:
  - type: tokenize
    fields: [email, phone]
```

Tokenization is **scope-bound** — the same input value always produces the same token within the same Virtual API and matched object definition. Different object definitions or different Virtual APIs can produce different tokens for the same input.

### Anonymize

Generate randomized replacements that preserve data structure. Each call produces a different value, making re-identification impossible.

```yaml theme={null}
controls:
  - type: anonymize
    fields: [email, name]
```

### Mask

Partially redact values while preserving enough structure for context. Useful in support, debugging, and audit log scenarios where you need to understand the data shape without revealing full values.

```yaml theme={null}
controls:
  - type: mask
    fields: [ssn, phone]
```

Masking behavior varies by data type:

| Type     | Rule                                                                                                                                                                      | Example                         |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `string` | Keeps first & last N characters visible (N=2 for strings longer than 4 chars, N=1 otherwise). Strings of 2 or fewer characters are fully masked. Whitespace is preserved. | `"John Smith"` → `"Jo** ***th"` |
| `double` | Zeros leading digits, keeps last 2 visible per segment                                                                                                                    | `123456.78` → `000056.78`       |
| `long`   | Zeros leading digits, keeps last 2 visible                                                                                                                                | `5551234567` → `0000000067`     |
| `bool`   | Always returns `false`                                                                                                                                                    | `true` → `false`                |

### Hash

Replace values with a one-way SHA-256 digest. Consumers can correlate and deduplicate records without seeing real values — the same input within the same Virtual API and matched object definition always produces the same hash.

```yaml theme={null}
controls:
  - type: hash
    fields: [email, customerId]
```

Hash behavior varies by data type:

| Type     | Output                  | Notes                             |
| -------- | ----------------------- | --------------------------------- |
| `string` | 64-character hex digest | Full SHA-256 hex of `scope:input` |
| `double` | Deterministic double    | Derived from hash bytes           |
| `long`   | Deterministic long      | From first 8 hash bytes           |
| `bool`   | Deterministic boolean   | Based on first hash byte          |

<Info>
  Hashing is **scope-bound** — different object definitions or different Virtual APIs produce different hashes for the same input value, preventing broad cross-context correlation.
</Info>

### Allow

Pass data through unchanged. Useful when you want to be explicit about which fields are permitted, even though fields not referenced by any control already pass through unchanged.

```yaml theme={null}
controls:
  - type: allow
    fields: [publicName]
```

## Working with the controls pipeline

* Controls execute top-to-bottom. Later controls see the values produced by earlier controls.
* If you are transforming and filtering the same field, place the transform first so later controls operate on the transformed value.
* Filter controls target scalar values only: strings, numbers, and booleans. If a path resolves to an object or array, the request fails.
* If the matched payload is a root array, the control list runs against each object element automatically. Non-object elements are skipped.
* Set `required: true` when a missing field should fail instead of being skipped.

## Targeting fields

Use dot notation for nested fields and bracket segments for arrays:

```yaml theme={null}
controls:
  - type: redact
    fields: [user.ssn, user.address.street, "[contacts].email"]
```

See [Field Targeting](./field-targeting) for the shared path rules used by Data Control and Data Transform.

## When to reach for reference docs

Use this page to choose the right privacy behavior. Use the reference docs when you need exhaustive option rules or edge-case behavior:

* [Field Targeting](./field-targeting) for nested paths, arrays, and `required` behavior
* [Control Block Reference](../api-reference/control-block-reference) for detailed option tables and per-control rules
* [YAML Reference](../api-reference/yaml-reference) for the full Virtual API Configuration shape

## Next steps

<CardGroup cols={2}>
  <Card title="Field Targeting" icon="crosshair" href="./field-targeting">
    Learn how controls target nested fields and arrays
  </Card>

  <Card title="Data Transform" icon="shuffle" href="./data-transform">
    Combine, coalesce, and delete fields in the same pipeline
  </Card>

  <Card title="Control Block Reference" icon="code" href="../api-reference/control-block-reference">
    Review detailed behavior and config options
  </Card>
</CardGroup>