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

# Handle Schema Changes

> Inspect Union Schema and select an explicit policy for new or sensitive fields.

# Handle Schema Changes

**Goal:** detect a new field in incoming events, distinguish observation from confirmed drift, and decide what to do before allowing deliveries.

> [!NOTE]
>
> **Screen version:** The numbered images are historical Control UI test captures. Follow the current five-step flow (Connect → Sample & Record Selection → Destinations → Route Processing → Deploy), not older step ordering. See the [numbered screenshot guide](https://control.datarelay.run/use-cases/screen-walkthrough.md).

## When to use this scenario

This scenario builds on an existing Connector, Destination and Stream. If you have not configured a Source yet, start from the [connector-specific collection guides](https://control.datarelay.run/use-cases/index.md). Follow the concrete steps below and verify **actual Logs and Destination/quarantine evidence**. Existing test screenshots are illustrative, not runtime proof.

## 1. Start with known events

Create a Stream using [the HTTP or Webhook guide](https://control.datarelay.run/use-cases/webhook-first-flow.md). Send several synthetic events containing:

```json theme={null}
{"id":"schema-001","user":{"name":"alice"},"severity":"low"}
```

In **Sample & Record Selection**, confirm **Record Selection** and **Union Schema**. The observed schema combines fields across the selected events; it is not limited to one arbitrary sample.

![record-selection — numbered Control historical UI capture](https://mintcdn.com/datarelay-control/Tl9_UibGAprPlCr8/images/screenshots/annotated/record-selection.webp?fit=max\&auto=format\&n=Tl9_UibGAprPlCr8\&q=85\&s=196de1ecaf541296095434008afc05ad)

*Figure 1. **Choosing record path and checkpoint.** ① Review the suggested Record Path, ② inspect actual fields in JSON Tree, ③ select the Checkpoint Field. This capture shows the not-yet-confirmed state.*

## 2. Send a changed event

Send another synthetic event through the same receiver:

```json theme={null}
{"id":"schema-002","user":{"name":"alice","email":"lab@example.invalid"},"severity":"low","custom_flag":true}
```

Re-run sample collection or use the runtime/schema view supported by your Stream. Inspect the new field paths and their occurrence counts. A newly observed field is not automatically a confirmed schema incident.

## 3. Select a handling policy

1. Open **Stream Edit → Route Processing → Protection / Schema Drift Policy** (or the corresponding Route editor).
2. For ordinary unknown fields, review the default **Pass Through** behavior; change to **Require Review** or **Quarantine** only when needed.
3. For suspected sensitive fields such as email or API keys, review any sensitivity suggestion and explicitly choose an appropriate protection/review action. Automatic suggestions must not silently activate a policy.
4. Keep the Stream-level Union Schema baseline shared by Routes; use per-Route overrides only for destination-specific treatment.
5. Save, verify the effective configuration and distinguish **Observed** from **Confirmed Drift** in operational evidence.

## 4. Verify the result

Send a second changed event with a unique ID. Inspect **Logs**, Stream/Route details, policy warnings, and the actual receiver payload or held-event record. Confirm ordinary fields follow the selected policy and sensitive fields are not unexpectedly exposed.

**PASS =** changed fields are visible in the observation/evidence, the chosen policy is effective, and the delivered or held event matches that policy.

## If it fails

* No new field: ensure the event was accepted, correct root selected, and multiple events were sampled.
* Sensitive suggestion missing: choose the actual observed field path and review the sensitivity configuration; suggestions are not guarantees.
* Event disappeared: inspect **Quarantine**, **Policy**, and **Logs** before assuming data loss.
* Field passes through unexpectedly: confirm the rule was saved and applies to the effective Route, not just a draft.

**Related:** [Mask by Route](https://control.datarelay.run/use-cases/protect-pii.md), [Quarantine review](https://control.datarelay.run/use-cases/quarantine-replay.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.