Home / Docs

Documentation

How DiffMon works across monitoring, alerts, security, and API integration.

Smart schema validation

How DiffMon classifies API diffs into schema vs value changes, with severity, fingerprints, and troubleshooting.

Smart schema validation

Smart schema validation (SSV) helps you separate real API contract drift from normal value churn.

Plan availability: Pro and above.

Instead of only saying "hash changed", DiffMon classifies JSON changes into:

  • schema_change (shape/type drift)
  • value_change (content changed, shape stable)
  • mixed (both)

When SSV runs

SSV runs automatically when all of these are true:

  1. Monitor target type is api.
  2. Fetch mode is content.
  3. Response body can be parsed as JSON.
  4. JSON select/ignore rules are applied first.

If these conditions are not met, DiffMon falls back to legacy hash diffing.

What users see in the app

On monitor history and incidents, you get:

  • classification badge (schema_change, value_change, mixed, unchanged)
  • schema hash transition (fromSchemaHash -> toSchemaHash)
  • schema/value change counters
  • top changed JSON paths
  • per-change severity (critical, high, medium, info)

This helps triage quickly:

  • prioritize schema_change and mixed
  • treat value_change as lower-risk unless business-critical

Severity model

SSV emits severity on every change record:

CategoryOperationSeverity
schemareplacecritical
schemaremovehigh
schemaaddmedium
valuereplaceinfo
valueadd / removeinfo

Webhook behavior

For diff.detected, webhook payloads include:

  • diff_summary with classification, schema_changes, value_changes
  • changes[] with path, category, op, severity
  • diff_fingerprint for dedupe/grouping

This allows stable downstream routing and automation without re-implementing diff logic.

Configuration best practices

  1. Keep API monitors on content mode when you need contract drift detection.
  2. Use selectJsonPaths to focus monitoring on a stable subset (for example, only data.items).
  3. Use ignoreJsonPaths for known volatile fields (timestamps, IDs, rotating tokens).
  4. Review top changed paths before broadening ignore rules.

Troubleshooting

Common monitor errors/warnings you may see:

CodeMeaningAction
SELECT_RULES_INVALID_JSON_PATHInvalid select JSON path syntaxFix selectJsonPaths format
IGNORE_RULES_INVALID_JSON_PATHInvalid ignore JSON path syntaxFix ignoreJsonPaths format
SELECT_RULES_INVALID_JSONResponse is not valid JSON while select rules are configuredVerify endpoint response format
IGNORE_RULES_INVALID_JSONResponse is not valid JSON while ignore rules are configuredVerify endpoint response format
SELECT_OR_IGNORE_RULES_INVALID_JSONResponse is not valid JSON while both rule sets are configuredVerify endpoint response format
UNEXPECTED_MIMEResponse format does not match expected type and body is not parseable as JSONCheck upstream response/content type
mime_mismatch_json (warning)Body parsed as JSON, but Content-Type is not JSONAsk provider to fix content-type header
schema_analysis_failed (warning)Schema extraction failed; hash diff still availableCheck payload shape and logs, then retry