# Expected Schema Check Examples

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

Three real-world scenarios that show how the Expected Schema check behaves in production: a contract that holds, a type change upstream, and an unexpected column. Expected Schema is a Shape-only rule, so every failure is reported as a single Shape Anomaly for the container.

**Tab: Contract Holds**

**The situation:** A partner receives an `ORDERS` extract with four agreed columns and fixed types. The layout is closed, so **Allow other fields** is off: an unannounced column would itself be a breach.

**Check configuration**

| Field | Value |
| --- | --- |
| Rule | Expected Schema |
| Table / File | `ORDERS` |
| Fields | `o_orderkey` (Integral), `o_custkey` (Integral), `o_orderstatus` (String), `o_totalprice` (Fractional) |
| Allow other fields | Off |
| Owner | *(check creator)* |
| Anomaly Assignee | *(Integrations team)* |
| Description | The ORDERS extract must match the agreed layout. |
| Tags | `schema`, `contract` |
| Additional Metadata | `jira: DATA-9801` |
| Status | Active |

**Payload**

```json
{
    "description": "The ORDERS extract must match the agreed layout.",
    "rule": "expectedSchema",
    "fields": [],
    "container_id": 145,
    "filter": null,
    "properties": {"list": ["o_orderkey", "o_custkey", "o_orderstatus", "o_totalprice"], "allow_other_fields": false},
    "tags": ["schema", "contract"],
    "additional_metadata": {"jira": "DATA-9801"},
    "template_id": null,
    "status": "Active",
    "owner_id": 7,
    "default_anomaly_assignee_id": 12
}
```

**Sample Data**

| Field | Profiled type | Type on the container |
| --- | --- | --- |
| o_orderkey | Integral | Integral |
| o_custkey | Integral | Integral |
| o_orderstatus | String | String |
| o_totalprice | Fractional | Fractional |

**What gets flagged**

Every declared field is present with a type matching its profile, and no undeclared column exists. The check passes and no anomaly is created. This is the baseline the next two scenarios drift away from.

> **Example: No anomaly**
>
> The container matches the declaration. The check passes.

**Flowchart**

```mermaid
graph TD
    A["Read the container's structure"] --> B["Compare against the declaration"]
    B --> C{"All declared fields present<br/>with a matching type?"}
    C -->|No| E["Report a Shape Anomaly"]
    C -->|Yes| D{"Allow other fields off and<br/>an undeclared column exists?"}
    D -->|Yes| E
    D -->|No| F["Check passes"]
```

**Equivalent SQL**

```sql
-- The same question, asked of the catalog rather than the data.
SELECT column_name, data_type
FROM information_schema.columns
WHERE table_name = 'ORDERS'
ORDER BY ordinal_position;
```

**Tab: A Type Changed Upstream**

**The situation:** A release changed `o_totalprice` from a decimal to text. Every value still looks like a number, so no value-level check fires, but the downstream cast will fail on the first non-numeric string that arrives.

**Check configuration**

| Field | Value |
| --- | --- |
| Rule | Expected Schema |
| Table / File | `ORDERS` |
| Fields | `o_orderkey` (Integral), `o_custkey` (Integral), `o_orderstatus` (String), `o_totalprice` (Fractional) |
| Allow other fields | Off |
| Owner | *(check creator)* |
| Anomaly Assignee | *(Integrations team)* |
| Description | The ORDERS extract must match the agreed layout. |
| Tags | `schema`, `contract` |
| Additional Metadata | `jira: DATA-9801` |
| Status | Active |

**Payload**

```json
{
    "description": "The ORDERS extract must match the agreed layout.",
    "rule": "expectedSchema",
    "fields": [],
    "container_id": 145,
    "filter": null,
    "properties": {"list": ["o_orderkey", "o_custkey", "o_orderstatus", "o_totalprice"], "allow_other_fields": false},
    "tags": ["schema", "contract"],
    "additional_metadata": {"jira": "DATA-9801"},
    "template_id": null,
    "status": "Active",
    "owner_id": 7,
    "default_anomaly_assignee_id": 12
}
```

**Sample Data**

| Field | Profiled type | Type on the container |
| --- | --- | --- |
| o_orderkey | Integral | Integral |
| o_custkey | Integral | Integral |
| o_orderstatus | String | String |
| o_totalprice | Fractional | String |

**What gets flagged**

The field count is unchanged, so a [Field Count](https://userguide.qualytics.io/data-quality-checks/field-count/introduction/) check stays green. Expected Schema compares the type the scan read against the field's profiled type and reports the mismatch as a single Shape Anomaly.

> **Example: Shape Anomaly**
>
> The types of fields [o_totalprice(expected:Fractional,loaded:String)] do not match the latest profile

**Flowchart**

```mermaid
graph TD
    A["Read the container's structure"] --> B["Compare o_totalprice:<br/>declared Fractional, found String"]
    B --> C{"Do the types match?"}
    C -->|Yes| D["Check passes"]
    C -->|No| E["Report a Shape Anomaly<br/>for the container"]
```

**Equivalent SQL**

```sql
-- Confirming the type change against the catalog.
SELECT column_name, data_type
FROM information_schema.columns
WHERE table_name = 'ORDERS' AND column_name = 'o_totalprice';
-- Returns String; the declaration says Fractional.
```

**Tab: An Unexpected Column Appeared**

**The situation:** An upstream team added `o_channel` to the shared extract. The declared fields are all still there with the right types, but the layout is closed, so the addition breaks the contract the partner's loader depends on.

**Check configuration**

| Field | Value |
| --- | --- |
| Rule | Expected Schema |
| Table / File | `ORDERS` |
| Fields | `o_orderkey` (Integral), `o_custkey` (Integral), `o_orderstatus` (String), `o_totalprice` (Fractional) |
| Allow other fields | Off |
| Owner | *(check creator)* |
| Anomaly Assignee | *(Integrations team)* |
| Description | The ORDERS extract must match the agreed layout. |
| Tags | `schema`, `contract` |
| Additional Metadata | `jira: DATA-9801` |
| Status | Active |

**Payload**

```json
{
    "description": "The ORDERS extract must match the agreed layout.",
    "rule": "expectedSchema",
    "fields": [],
    "container_id": 145,
    "filter": null,
    "properties": {"list": ["o_orderkey", "o_custkey", "o_orderstatus", "o_totalprice"], "allow_other_fields": false},
    "tags": ["schema", "contract"],
    "additional_metadata": {"jira": "DATA-9801"},
    "template_id": null,
    "status": "Active",
    "owner_id": 7,
    "default_anomaly_assignee_id": 12
}
```

**Sample Data**

| Field | Declared? | Type on the container |
| --- | --- | --- |
| o_orderkey | Yes | Integral |
| o_custkey | Yes | Integral |
| o_orderstatus | Yes | String |
| o_totalprice | Yes | Fractional |
| o_channel | No | String |

**What gets flagged**

Every declared field is intact, but `o_channel` was not declared and **Allow other fields** is off, so the check reports a Shape Anomaly. Had the toggle been on, the extra column would have been ignored and the check would have passed.

> **Example: Shape Anomaly**
>
> Unexpected fields [o_channel] are present

**Flowchart**

```mermaid
graph TD
    A["Read the container's structure"] --> B["All declared fields present<br/>with a matching type"]
    B --> C{"Allow other fields?"}
    C -->|On| D["Extras ignored.<br/>Check passes"]
    C -->|Off| E["o_channel is undeclared.<br/>Report a Shape Anomaly"]
```

**Equivalent SQL**

```sql
-- Listing what the container carries beyond the declaration.
SELECT column_name
FROM information_schema.columns
WHERE table_name = 'ORDERS'
  AND column_name NOT IN ('o_orderkey', 'o_custkey', 'o_orderstatus', 'o_totalprice');
-- Returns o_channel.
```

## See Also

- **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/)
- **How It Works**

  The complete reference: definition, container scope, the declared field list, the extra-fields toggle, and why filters and coverage do not apply.

  [How It Works](https://userguide.qualytics.io/data-quality-checks/expected-schema/deep-dive/how-it-works/)
- **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/)

*Last updated: September 21, 2026.*
