Severity Levels

How DriftGuard scores schema drift and maps it to pass, warning, or breaking.

DriftGuard evaluates every schema check by calculating a severity score from 0 to 100. Each type of change contributes a fixed number of points. The total score determines the final result returned in the check response.

---

The Three Results

breaking

Score 90–100. Will cause downstream failures. Block the pipeline or fail CI.

warning

Score 20–89. Drift detected that may cause issues. Review before proceeding.

pass

Score 0–19. Schema matches the contract. Safe to proceed.

---

Scoring Formula

Points are added for each difference found between the incoming schema and the contract. The total is capped at 100.

Change Type	Points
Required column removed	+40
Optional column removed	+20
Column type changed	+30 per column
New column added	+5 per column

Score → Result Mapping

Score Range	Result
0 – 19	pass
20 – 89	warning
90 – 100	breaking

The required flag on each column definition determines whether a removed column scores +40 or +20. Set required: true for columns your downstream consumers cannot function without.

---

Worked Examples

Example 1 — breaking (score: 95)

Contract has email (string, required) and created_at (timestamp, required). Incoming schema is missing email entirely, and created_at has changed type to string.

Change	Points
email removed (required)	+40
created_at type changed (timestamp → string)	+30
Total	70 → capped? No → warning

Wait — let’s add one more required column removed:

Change	Points
email removed (required)	+40
user_id removed (required)	+40
created_at type changed	+30
Total (capped at 100)	100 → breaking

{
  "result": "breaking",
  "severity": 100,
  "diff": {
    "removed": ["email", "user_id"],
    "type_changes": [
      { "column": "created_at", "from": "timestamp", "to": "string" }
    ],
    "added": []
  }
}

---

Example 2 — warning (score: 70)

Contract has email (string, required) and created_at (timestamp, required). Incoming schema is missing email, and created_at has changed type to string.

Change	Points
email removed (required)	+40
created_at type changed	+30
Total	70 → warning

{
  "result": "warning",
  "severity": 70,
  "diff": {
    "removed": ["email"],
    "type_changes": [
      { "column": "created_at", "from": "timestamp", "to": "string" }
    ],
    "added": []
  }
}

---

Example 3 — pass (score: 5)

Contract has email, user_id, created_at. Incoming schema matches all three but adds one unexpected new column updated_at.

Change	Points
updated_at added	+5
Total	5 → pass

{
  "result": "pass",
  "severity": 5,
  "diff": {
    "removed": [],
    "type_changes": [],
    "added": ["updated_at"]
  }
}

---

What is Not Currently Detected

The current diff engine tracks three change types: removed columns, type changes, and added columns. The following are not yet detected:

Change	Status
Column renames	Not detected — appears as a removal + addition
Nullability changes	Not detected
Column reordering	Not detected — order is not enforced

---

Customising Severity

Contract-level rules to customise scoring (such as ignoring new columns or changing how renames are treated) are on the roadmap. See Rules for the planned behaviour and current workarounds.

---

Run a Check

See the full scoring formula in action with the check endpoint.

Rules

Planned contract-level rules for customising severity thresholds.