# How Expected Schema Checks Work

Source: https://userguide.qualytics.io/data-quality-checks/expected-schema/deep-dive/how-it-works/

## Definition

*Asserts that all declared fields are present on the container and that their data types match what was declared.*

## Overview

The Expected Schema rule pins the shape of a container to a contract. You declare the names of the fields the container must carry; on every scan the check confirms that each one is present and that its type still matches the type recorded on the field's profile. The **Allow other fields** toggle decides what happens to columns you did not declare: leave it on and extras are tolerated, turn it off and the container must match the declaration exactly.

Like [Field Count](https://userguide.qualytics.io/data-quality-checks/field-count/introduction/), the rule reads the container's structure rather than its values, so it offers neither a filter clause nor a coverage setting.

Typical use cases:

- Freeze the contract of a published extract or an integration interface.
- Detect a type change upstream, such as a numeric column arriving as text.
- Catch a renamed or dropped column that a count-only check would miss.

## Field Scope

**None:** The rule evaluates the container's structure, so there is no field to select on the form. The fields it asserts are declared as a property instead. Because nothing is evaluated per row, the check offers neither a filter clause nor a coverage setting.

## Anomaly Types

| Type | Supported |
| --- | --- |
| Record Flag inconsistencies at the row level | Not supported |
| Shape Flag inconsistencies in the overall patterns and distributions of a field | Supported |

## Evaluation Flow

Every Expected Schema check follows the same three-step evaluation flow:

1. **Confirm every declared field is present.** Any declared name missing from the container fails the check here, and the evaluation stops.
2. **Apply the extra-fields policy.** When **Allow other fields** is off, a column outside the declaration fails the check and the evaluation stops. When it is on, extras are ignored.
3. **Compare the types.** For each declared field, the type the scan read is compared with the type on the field's profile; incompatible types fail the check.

The three steps short-circuit in that order, so a scan reports the first category that fails, not all of them at once.

## What Allow Other Fields Changes

The toggle turns one rule into two:

| Setting | The check asserts |
| --- | --- |
| **On** | The declared fields are present with a compatible type. Extra columns are fine. |
| **Off** | The container holds exactly the declared fields, no more. |

Leave it **on** when you consume a subset of a table that other teams keep extending: you only care that your columns are intact. Turn it **off** for a delivered file or a published extract, where an unexpected column is itself a contract breach.

## Types Are Part of the Contract

This is what separates Expected Schema from [Field Count](https://userguide.qualytics.io/data-quality-checks/field-count/introduction/). A column that arrives as text where a number was declared keeps the count unchanged, so a count-only rule stays green while every downstream cast breaks. Expected Schema reports it.

## Renames Are Reported as a Missing Field

A renamed column reads as the declared field being absent, plus (when **Allow other fields** is off) an undeclared column appearing. That is the correct reading: for a consumer binding to the old name, the column is gone.

## No Filter, No Coverage

A filter selects rows and coverage tolerates failing rows; neither concept applies to a rule that reads the container's structure. Both inputs are absent from the form, and the API rejects them: a non-empty `filter`, or a `coverage` other than `1`, returns `422`.

## See Also

- **Anomaly Reporting**

  What the Shape Anomaly reports, how to read it, and why per-row reporting does not apply.

  [Anomaly Reporting](https://userguide.qualytics.io/data-quality-checks/expected-schema/deep-dive/anomaly-reporting/)
- **Examples**

  Three production scenarios: a stable contract, a type change, and an unexpected column.

  [Examples](https://userguide.qualytics.io/data-quality-checks/expected-schema/deep-dive/examples/)
- **Best Practices**

  Guidelines for declaring the contract, choosing the extra-fields policy, and pairing with Field Count.

  [Best Practices](https://userguide.qualytics.io/data-quality-checks/expected-schema/deep-dive/best-practices/)
- **Permissions**

  The team permission each action needs: view, create, edit, archive, restore, and delete.

  [Permissions](https://userguide.qualytics.io/data-quality-checks/expected-schema/deep-dive/permissions/)

*Last updated: September 21, 2026.*
