How diffs are generated
Intello compares normalized OpenAPI snapshots to produce change events—the rows you see under Changes with severity badges. This page explains what “breaking” means, how severity is assigned, and where the engine cannot see risk.
Normalization
Before diffing, Intello canonicalizes the OpenAPI model:
- Ordering-insensitive comparisons for maps and arrays where appropriate.
- Stable representation of types, parameters, and security bindings.
Cosmetic edits (whitespace, description-only tweaks that don’t affect machine-readable schema) may not surface as events.
Breaking vs non-breaking
Breaking changes are those that typically force client updates or create runtime failures if ignored. Examples:
- Removing an operation or parameter
- Changing a parameter type incompatibly
- Adding a required field or property
- Removing enum values clients relied on
Non-breaking changes still matter for compliance and roadmap planning but may not warrant paging:
- Adding optional properties
- Adding new operations
- Pure documentation updates (often invisible post-normalization)
Each event exposes:
severity:safe|risky|breakingbreaking: boolean flag for contract posture
Use both: some policies key off the boolean, others off the ordinal severity.
Fan-out and deduplication
A single schema edit can touch many operations. Intello assigns a cause_key so:
- List UIs can collapse related rows.
- Alerts dispatch once per root cause rather than spamming N messages.
See Changes and classification.
Limitations (explicit)
Intello reasons about declared OpenAPI contracts—not live traffic:
- Undocumented behavior (extra properties accepted at runtime) won’t appear until the vendor documents them.
- Server-side validation may tighten without schema updates—no contract diff will fire.
- Rate limits, SLAs, and incident posture are out of scope for spec diffing.
- GraphQL and gRPC require different models—only OpenAPI paths documented here apply.