# Schema-Drift Detector

> Catch Structural and Semantic Contract Changes

`D01-F04-A04` · Market Data Engineering → Data Quality · archetype `row-classify` · difficulty 2/5 · verification **contract**

Full page: https://docs.thefintechbuilder.com/market-data-engineering/data-quality/schema-drift-detector/
Agent skill: `npx skills add IslamBaraka90/Fintech-Algorithms-Library` — https://docs.thefintechbuilder.com/guides/agent-skill/

## Install and import

```bash
npm install fintech-algorithms
```

```ts
import { detectSchemaDrift } from "fintech-algorithms/market-data-engineering/data-quality/schema-drift-detector";
```

## Signature

```ts
detectSchemaDrift(baseline, candidate, policy)
```

Compares two versions of a feed schema and classifies every change as compatible or breaking. Vendors rename and retype fields without announcement, and a silently renamed field is worse than an outage because nothing fails.

## Parameters

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `baseline` | `Schema` | yes | The schema currently relied upon. |
| `candidate` | `Schema` | yes | The schema just observed on the feed. |
| `policy` | `DriftPolicy` | yes | Which categories of change are tolerated, and which must fail. |

## Returns

`{ baseline_version, candidate_version, policy, status, coverage_complete, changes }`

Every change with its classification, plus whether the comparison covered the whole schema — an incomplete comparison must not read as a clean bill of health.

## Errors

- When either schema is missing an identifier or version — throws

## Complexity

Time `O(fields)`, space `O(fields)`.

## Worked example

Captured by running this function on the input its own test provides. Real output of real code — but not asserted against a published figure.

### Input

`baseline`:

```json
{
  "schema_id": "synthetic-trades",
  "version": "v1.0",
  "parent_version": null,
  "completeness": "complete",
  "fields": {
    "symbol": {
      "type": "string",
      "required": true,
      "nullable": false,
      "enum": null,
      "unit": null,
      "meaning": "Instrument symbol under the declared venue symbology"
    },
    "price": {
      "type": "number",
      "required": true,
      "nullable": false,
      "enum": null,
      "unit": "USD per share",
      "meaning": "Executed price"
    },
    "size": {
      "type": "integer",
      "required": true,
      "nullable": false,
      "enum": null,
      "unit": "shares",
      "meaning": "Executed quantity"
    },
    "sale_condition": {
      "type": "string",
      "required": false,
      "nullable": true,
      "enum": [" ", "O"],
      "unit": null,
      "meaning": "Synthetic sale-condition code"
    }
  }
}
```

`candidate`:

```json
{
  "schema_id": "synthetic-trades",
  "version": "v1.0-clone",
  "parent_version": "v1.0",
  "completeness": "complete",
  "fields": {
    "symbol": {
      "type": "string",
      "required": true,
      "nullable": false,
      "enum": null,
      "unit": null,
      "meaning": "Instrument symbol under the declared venue symbology"
    },
    "price": {
      "type": "number",
      "required": true,
      "nullable": false,
      "enum": null,
      "unit": "USD per share",
      "meaning": "Executed price"
    },
    "size": {
      "type": "integer",
      "required": true,
      "nullable": false,
      "enum": null,
      "unit": "shares",
      "meaning": "Executed quantity"
    },
    "sale_condition": {
      "type": "string",
      "required": false,
      "nullable": true,
      "enum": [" ", "O"],
      "unit": null,
      "meaning": "Synthetic sale-condition code"
    }
  }
}
```

### Call

```ts
detectSchemaDrift(baseline, candidate, policy)
```

### Returns

object with 6 fields: baseline_version, candidate_version, policy, status, coverage_complete, changes

```json
{
  "baseline_version": "v1.0",
  "candidate_version": "v1.0-clone",
  "policy": {
    "name": "strict_existing_consumer_v1",
    "direction": "candidate_producer_to_baseline_consumer",
    "added_field": "non_breaking",
    "removed_optional": "review",
    "removed_required": "breaking",
    "type_changed": "breaking",
    "optional_to_required": "non_breaking",
    "required_to_optional": "breaking",
    "nonnullable_to_nullable": "breaking",
    "nullable_to_nonnullable": "non_breaking",
    "enum_values_added": "breaking",
    "enum_values_removed": "review",
    "unit_changed": "breaking",
    "meaning_changed": "breaking"
  },
  "status": "unchanged",
  "coverage_complete": true,
  "changes": []
}
```

## Verification and provenance

Tier: **contract**.

The module loads, the entry point is callable and its declared signature matches the compiled code. The example below is real captured output, but no independently published figure asserts the numbers.

Both tiers guarantee the signature. Full explanation: https://docs.thefintechbuilder.com/guides/verification/

Generated from the docs.json payload shipped inside fintech-algorithms@0.13.1.
The signature and parameter list are checked against the compiled implementation at build time,
so a description that contradicts the code fails the build rather than reaching this file.

## Links

- Article (how it works, step by step): https://thefintechbuilder.com/market-data-engineering/data-quality/schema-drift-detector/
- Implementation source: https://github.com/IslamBaraka90/Fintech-Algorithms-Library/blob/main/src/market-data-engineering/data-quality/schema-drift-detector/impl.ts
- Standalone repository: https://github.com/IslamBaraka90/Fintech-Schema-Drift-Detector-Data-Quality-algorithm
- Package on npm: https://www.npmjs.com/package/fintech-algorithms
- Domain index for agents: https://docs.thefintechbuilder.com/market-data-engineering/llms.txt