API Schema Drift Detector - Claude Code Hook

PostToolUse hook that compares a just-edited OpenAPI or JSON Schema document against the version committed in git and warns about backward-incompatible drift — removed OpenAPI paths and removed required properties — so breaking API changes are surfaced before they ship. Advisory only; it never blocks the edit.

by jony376·added 2026-06-04·

Claude Code

HarnessClaude Code

Trigger:PostToolUse

Command center

Source

Review first

Review safety and privacy notes before installing or copying commands.

Safety notes Privacy notes

Install & copy

mkdir -p .claude/hooks && touch .claude/hooks/api-schema-drift-detector.sh && chmod +x .claude/hooks/api-schema-drift-detector.sh

Trust & readiness

TrustReview first
Sourcesource-backed
Safety notesPresent
ReviewedYes

Community context

Related entries(4)
Related guides(3)
Community signals

Compare

Integrations & API

Contribute

Suggest a metadata change Claim this listing

Documentation Source repository Browse directory

Review first — review before installing

Open the source and read safety notes before installing.

Citation facts

Source-backed facts for citing this resource, derived directly from the registry — also available as plain text for AI assistants.

Canonical URL: https://heyclau.de/entry/hooks/api-schema-drift-detector
Source URLs: https://spec.openapis.org/oas/latest.html, https://github.com/OAI/OpenAPI-Specification
Safety notes: Runs after every Write, Edit, and MultiEdit and only inspects JSON files that declare openapi, swagger, a $schema key, or paths., Stays read-only and runs git show to read the committed version; it never edits, stages, or commits anything., Advisory by design and always exits 0, so it never blocks a write even when drift is detected., Uses key-set comparison heuristics for removed paths and required fields, so it catches common breaking changes but is not a full OpenAPI diff.
Privacy notes: Reads the edited schema file and its committed HEAD version from the local repository only., Prints removed path and required-field names to local hook stderr; it makes no network calls and writes no logs., Path and field names shown in output may reveal internal API surface in your terminal.
Author: jony376
Submitted by: jony376
Claim status: unclaimed
Last verified: 2026-06-04

Decision playbook

Review trust signals before you adopt

Signals are present but mixed. Use the checklist below to confirm the source and operational safety for your environment.

Compare context

Selected

Current score

Baseline

—

Delta

No baseline selected

No major trust-signal divergence detected in the current selection.

Source and provenance checks

Complete

Confirm ownership and provenance before trusting install instructions.

Source link availableRequired
Open the canonical repository and verify ownership.
Done
Source provenance statusRequired
Marked as source-backed.
Done
Metadata reviewed
Registry metadata indicates a reviewed listing.
Done

Safety and privacy checks

Complete

Validate risk disclosures before installation or API wiring.

Safety notes presentRequired
Review the listed safety guidance before running commands.
Done
Privacy notes presentRequired
Review data handling notes before connecting accounts or secrets.
Done
Trust level risk gateRequired
Trust level does not block evaluation.
Done

Package and install checks

Needs review

Check package metadata and artifact integrity signals.

Install payload available
Install or copy payload is available for review.
Done
Package verification flag
No package verification flag provided.
Pending
Checksum metadata
No checksum provided for downloaded artifact.
Pending

Compare-driven decision checks

Needs review

Use compare context to validate trade-offs before adoption.

Compare tray has multiple entries
Add at least one more entry to compare trust differences.
Pending
Baseline comparison available
No baseline peer selected yet.
Pending
Diverging trust signals identified
No major trust-signal divergence found.
Pending

Setup at a glance

CLI install

Copy-ready — paste the snippet to get started.

Install command

Provided

Config snippet

Provided

Copy snippet

Provided

Prerequisites

3 to clear

Platforms

1 listed

Install type

CLI install

Adoption plan

Balanced adoption plan

Current risk score 16/100. Use staged verification before broader rollout.

Risk 16

Pre-adoption checks

Validate source and review signals before any execution.

Confirm source provenanceRequired
Source URL/provenance metadata is present.
Done
Confirm metadata review state
Listing has review metadata.
Done
Verify install payload
Install/config payload exists and can be inspected.
Done

Security checks

Confirm safety, privacy, and package integrity signals.

Review safety notesRequired
Safety notes are present.
Done
Review privacy notesRequired
Privacy notes are present.
Done
Verify package integrity metadata
No package verification/checksum metadata.
Pending

Rollout

Adopt in controlled steps based on the selected plan.

Run in isolated sandbox firstRequired
Use a constrained sandbox and observe behavior across multiple tasks.
Pending
Roll out graduallyRequired
Roll out to a small cohort before wider usage.
Pending
Set monitoring and fallback
Define rollback path and monitor errors after adoption.
Pending

Evidence readiness

Evidence readiness matrix · balanced

Required evidence gates are covered (5/6 signals complete).

Risk 15

Source provenance

Present

Source repository/provenance is listed.

Required in this preset

Metadata review

Present

Review metadata is present.

Required in this preset

Safety notes

Present

Safety notes are present.

Required in this preset

Privacy notes

Present

Privacy notes are present.

Optional in this preset

Package integrity

Missing

Package integrity metadata is missing.

Optional in this preset

Install payload

Present

Install payload is available.

Required in this preset

Required evidence gates are covered for this preset.

Decision timeline

Decision timeline · balanced

5/6 steps complete with no blocking gaps for this preset.

Risk 14

triage

Confirm source provenanceRequired

Source/provenance metadata is available.

Done

triage

Check metadata review statusRequired

Review metadata is available.

Done

verify

Review safety notesRequired

Safety notes are available.

Done

verify

Review privacy notes

Privacy notes are available.

Done

verify

Validate package integrity metadata

Package integrity metadata is missing.

Pending

rollout

Verify install payload and commandsRequired

Install payload is available.

Done

No required blockers for this timeline preset.

Prerequisite readiness

3 prerequisites to line up before setup.

0/3 ready

Install & runtime1Configuration1General1

Safety & privacy surface

4 safety and 3 privacy notes across 4 risk areas. Review closely: network access.

4 areas

SafetyLocal filesRuns after every Write, Edit, and MultiEdit and only inspects JSON files that declare openapi, swagger, a $schema key, or paths.
SafetyExecution & processesStays read-only and runs git show to read the committed version; it never edits, stages, or commits anything.
SafetyGeneralAdvisory by design and always exits 0, so it never blocks a write even when drift is detected.
SafetyLocal filesUses key-set comparison heuristics for removed paths and required fields, so it catches common breaking changes but is not a full OpenAPI diff.
PrivacyLocal filesReads the edited schema file and its committed HEAD version from the local repository only.
PrivacyNetwork accessPrints removed path and required-field names to local hook stderr; it makes no network calls and writes no logs.
PrivacyLocal filesPath and field names shown in output may reveal internal API surface in your terminal.

Safety notes

Runs after every Write, Edit, and MultiEdit and only inspects JSON files that declare openapi, swagger, a $schema key, or paths.
Stays read-only and runs git show to read the committed version; it never edits, stages, or commits anything.
Advisory by design and always exits 0, so it never blocks a write even when drift is detected.
Uses key-set comparison heuristics for removed paths and required fields, so it catches common breaking changes but is not a full OpenAPI diff.

Privacy notes

Reads the edited schema file and its committed HEAD version from the local repository only.
Prints removed path and required-field names to local hook stderr; it makes no network calls and writes no logs.
Path and field names shown in output may reveal internal API surface in your terminal.

Prerequisites

Claude Code CLI with hooks enabled.
git, jq, and bash on PATH; the hook fails open and stays silent when git or jq is missing.
The schema file must be tracked in git so a committed baseline exists to diff against.

Schema details

Install type: cli
Troubleshooting: No

Source repository stats

Scope: Source repo

Runtime and command metadata

Trigger: PostToolUse
Script language: bash

Script body

#!/usr/bin/env bash
set -u

# Claude Code PostToolUse hook. After a JSON OpenAPI / JSON Schema file is
# written or edited, compare it against the version committed in git (HEAD)
# and warn about backward-incompatible drift: removed OpenAPI paths and
# removed required properties. Advisory only - it never blocks the edit -
# and fails open if jq or git is unavailable.

if ! command -v jq >/dev/null 2>&1 || ! command -v git >/dev/null 2>&1; then
  exit 0
fi

INPUT=$(cat)
FILE=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // ""')

[ -z "$FILE" ] && exit 0
case "$FILE" in
  *.json) : ;;
  *) exit 0 ;;
esac
[ -f "$FILE" ] || exit 0

# Only act on OpenAPI / JSON Schema documents.
if ! jq -e 'has("openapi") or has("swagger") or has("$schema") or has("paths")' "$FILE" >/dev/null 2>&1; then
  exit 0
fi

# A committed baseline is required to detect drift.
OLD=$(git show "HEAD:$FILE" 2>/dev/null) || exit 0
[ -z "$OLD" ] && exit 0

drift=0

# Removed OpenAPI paths are breaking for existing clients.
removed_paths=$(comm -23 \
  <(printf '%s' "$OLD" | jq -r '(.paths // {}) | keys[]' 2>/dev/null | sort -u) \
  <(jq -r '(.paths // {}) | keys[]' "$FILE" 2>/dev/null | sort -u))
if [ -n "$removed_paths" ]; then
  echo "API schema drift in $FILE - removed path(s):" >&2
  while IFS= read -r path; do
    printf '   - %s\n' "$path" >&2
  done <<< "$removed_paths"
  drift=1
fi

# Removed top-level required properties are breaking for JSON Schema consumers.
removed_required=$(comm -23 \
  <(printf '%s' "$OLD" | jq -r '(.required // []) | .[]' 2>/dev/null | sort -u) \
  <(jq -r '(.required // []) | .[]' "$FILE" 2>/dev/null | sort -u))
if [ -n "$removed_required" ]; then
  echo "API schema drift in $FILE - removed required field(s):" >&2
  while IFS= read -r field; do
    printf '   - %s\n' "$field" >&2
  done <<< "$removed_required"
  drift=1
fi

if [ "$drift" -ne 0 ]; then
  echo "Treat these as breaking changes - bump the major version and update consumers." >&2
fi

exit 0

Full copyable content

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/api-schema-drift-detector.sh"
          }
        ]
      }
    ]
  }
}

About this resource

Features

Detects backward-incompatible schema drift the moment an OpenAPI or JSON Schema file is saved, by diffing it against the version committed in git.
Flags the two most common breaking changes — removed OpenAPI paths and removed top-level required properties.
Advisory only — it always exits 0, so it surfaces risk without interrupting your edit flow.
Fails open — if git or jq is missing, or the file has no committed baseline, it stays silent.
Pure local bash + jq + git show; no network calls and no persisted logs.

How it works

On PostToolUse, the hook reads the edited file path from the tool input. If the file is a JSON document that declares openapi, swagger, $schema, or paths, it reads the committed version with git show HEAD:<file> and compares key sets — paths present before but absent now, and required entries removed. Any removal is reported to stderr as a breaking change, with a reminder to bump the major version per semantic versioning.

Use cases

Catch an accidentally deleted endpoint or required field while iterating on an API contract.
Add a fast, local breaking-change signal ahead of a full contract test in CI.
Keep generated clients and consumers in sync by surfacing removals early.

Installation

Create the hooks directory: mkdir -p .claude/hooks
Create the hook file: touch .claude/hooks/api-schema-drift-detector.sh
Paste the script body into that file and make it executable: chmod +x .claude/hooks/api-schema-drift-detector.sh
Add the configuration below to .claude/settings.json (project) or ~/.claude/settings.json (user).

Requirements

Claude Code CLI with hooks enabled
bash, jq, and git
The schema file must be committed at least once so HEAD has a baseline

Hook configuration

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/api-schema-drift-detector.sh"
          }
        ]
      }
    ]
  }
}

Limitations

Compares top-level path and required key sets only; it does not yet diff nested property types, response schemas, or enum narrowing.
Operates on JSON documents. For YAML OpenAPI files, convert or extend the script with a YAML-to-JSON step.

Source and references

OpenAPI Specification: https://spec.openapis.org/oas/latest.html
OpenAPI Specification repository: https://github.com/OAI/OpenAPI-Specification
Claude Code hooks documentation: https://docs.anthropic.com/en/docs/claude-code/hooks

#openapi #json-schema #api #breaking-changes #ci

Source citations

Source methodology →

Add this badge to your README

Show that API Schema Drift Detector - Claude Code Hook is listed on HeyClaude. Paste this Markdown into your README — it renders the badge and links back to this page.

[![Listed on HeyClaude](https://heyclau.de/badge/hooks/api-schema-drift-detector.svg)](https://heyclau.de/entry/hooks/api-schema-drift-detector)

How it compares

API Schema Drift Detector - Claude Code Hook side by side with 2 alternatives on trust, install, platform support, and disclosed safety notes — all from reviewed registry metadata.

1 trust signal differ across this comparison (Submitter).

Field	API Schema Drift Detector - Claude Code Hook PostToolUse hook that compares a just-edited OpenAPI or JSON Schema document against the version committed in git and warns about backward-incompatible drift — removed OpenAPI paths and removed required properties — so breaking API changes are surfaced before they ship. Advisory only; it never blocks the edit. Open dossier	GraphQL Schema Validator - Hooks Validates GraphQL schema files and checks for breaking changes when modified. Open dossier	JSON Schema Validator - Hooks Validates JSON files against their schemas when modified to ensure data integrity. Open dossier
Next steps	Open dossier API JSON Open LLM Open source Newsletter Claim listing	Open dossier API JSON Open LLM Open source Newsletter Claim listing	Open dossier API JSON Open LLM Open source Newsletter Claim listing
Trust
Review status	ReviewedMaintainer reviewed	ReviewedMaintainer reviewed	ReviewedMaintainer reviewed
Package trust	Package not verified	Package not verified	Package not verified
Source provenance	Source-backed	Source-backed	Source-backed
SubmitterDiffers	jony376	—	—
Install risk	Review first	Review first	Review first
Notes	Safety ✓ Privacy ✓	Safety ✓ Privacy ✓	Safety ✓ Privacy ✓
Brand	—	—	—
Category	hooks	hooks	hooks
Source	Source-backed	Source-backed	Source-backed
Author	jony376	JSONbored	JSONbored
Added	2026-06-04	2025-09-19	2025-09-19
Platforms	Claude Code	Claude Code	Claude Code
Harness	Claude Code	Claude Code	Claude Code
Source repo	—	—	—
Safety notes	✓Runs after every Write, Edit, and MultiEdit and only inspects JSON files that declare openapi, swagger, a $schema key, or paths. Stays read-only and runs git show to read the committed version; it never edits, stages, or commits anything. Advisory by design and always exits 0, so it never blocks a write even when drift is detected. Uses key-set comparison heuristics for removed paths and required fields, so it catches common breaking changes but is not a full OpenAPI diff.	✓Runs automatically on its configured Claude Code hook event and executes shell logic that can read, modify, or delete files in your project (and may run builds, installs, or network calls); review the script and scope it to expected paths before enabling.	✓Runs automatically on its configured Claude Code hook event and executes shell logic that can read, modify, or delete files in your project (and may run builds, installs, or network calls); review the script and scope it to expected paths before enabling.
Privacy notes	✓Reads the edited schema file and its committed HEAD version from the local repository only. Prints removed path and required-field names to local hook stderr; it makes no network calls and writes no logs. Path and field names shown in output may reveal internal API surface in your terminal.	✓Receives Claude Code hook input (session metadata, file paths, and tool output) and reads local project files; review what the script logs or forwards to external services and keep credentials out of its output.	✓Receives Claude Code hook input (session metadata, file paths, and tool output) and reads local project files; review what the script logs or forwards to external services and keep credentials out of its output.
Prerequisites	Claude Code CLI with hooks enabled. git, jq, and bash on PATH; the hook fails open and stays silent when git or jq is missing. The schema file must be tracked in git so a committed baseline exists to diff against.	— none listed	— none listed
Install	`mkdir -p .claude/hooks && touch .claude/hooks/api-schema-drift-detector.sh && chmod +x .claude/hooks/api-schema-drift-detector.sh`	`mkdir -p .claude/hooks && touch .claude/hooks/graphql-schema-validator.sh && chmod +x .claude/hooks/graphql-schema-validator.sh`	`mkdir -p .claude/hooks && touch .claude/hooks/json-schema-validator.sh && chmod +x .claude/hooks/json-schema-validator.sh`
Config	`{ "hooks": { "PostToolUse": [ { "matcher": "Write\|Edit\|MultiEdit", "hooks": [ { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/api-schema-drift-detector.sh" } ] } ] } }`	`{ "hooks": { "postToolUse": { "script": "./.claude/hooks/graphql-schema-validator.sh", "matchers": [ "write", "edit" ] } } }`	`{ "hooks": { "postToolUse": { "script": "./.claude/hooks/json-schema-validator.sh", "matchers": [ "write", "edit" ] } } }`
Citations	Source repositorygithub.com 2026-07-18T19:14:44+00:00 Documentationspec.openapis.org Submitted by jony3762026-06-04 Source methodology →	Source repositorygithub.com 2026-07-18T19:14:44+00:00 Documentationgraphql.org Source methodology →	Source repositorygithub.com 2026-07-18T19:14:44+00:00 Documentationjson-schema.org Source methodology →
Claim	Unclaimed	Unclaimed	Unclaimed

Open 3 picks in the interactive comparison tool

Signals

Loading live community signals…

Citation facts

Review trust signals before you adopt

Source and provenance checks

Safety and privacy checks

Package and install checks

Compare-driven decision checks

CLI install

Balanced adoption plan

Pre-adoption checks

Security checks

Rollout

Evidence readiness matrix · balanced

Source provenance

Metadata review

Safety notes

Privacy notes

Package integrity

Install payload

Decision timeline · balanced

Confirm source provenanceRequired

Check metadata review statusRequired

Review safety notesRequired

Review privacy notes

Validate package integrity metadata

Verify install payload and commandsRequired

Prerequisite readiness

Safety & privacy surface

Safety notes

Privacy notes

Prerequisites

Schema details

About this resource

Features

How it works

Use cases

Installation

Requirements

Hook configuration

Limitations

Source and references

Source citations

Add this badge to your README

How it compares

Related resources

GraphQL Schema Validator - Hooks

JSON Schema Validator - Hooks

/docs - Documentation Drafting Custom Command

API Contract Review Gate

Related guides

Claude Code GitHub Actions Review Workflow

Claude Code GitLab CI/CD Workflow

Use HeyClaude API, MCP, and Raycast Together

Signals