OpenAPI specs: what works and what breaks

Intello’s engine targets OpenAPI 2.0 and 3.x documents (JSON or YAML)—the same files you paste or link when you add a dependency in the app. This page documents practical constraints: parser behavior, security hardening, and vendor quirks that affect diffs.

Supported inputs

• JSON and YAML OpenAPI definitions.
• Specs reachable via HTTPS GET for spec_source=url.
• Files within configured size limits (tens of MB—check deployment; extremely large specs may fail at fetch/parse).

External references ($ref)

For security, Intello does not resolve arbitrary external $ref targets that would cause the worker to fetch uncontrolled URLs or local files. Specs should be self-contained or use refs Intello’s parser can resolve safely within the fetched document.

Best practice: vendor-publish bundled OpenAPI (all schemas inlined) for monitoring.

Normalization before diff

Snapshots store a normalized form of the OpenAPI model. Normalization:

• Stabilizes ordering and representation so benign formatting churn does not spam change events.
• Can hide purely cosmetic differences while preserving semantic edits.

If you expect a field-level diff in Intello but only changed comments, you may see no event—that is intentional noise reduction.

What generates change events

Representative categories:

• Operations added/removed/deprecated
• Parameter additions/removals/type changes
• Schema shape changes on requests/responses
• Security scheme changes affecting operations
• Enum membership changes and required field toggles

Exact kind strings appear in Changes and classification.

Common vendor failure modes

Symptom	Likely cause
parse stage failures	Invalid OpenAPI per parser rules; vendor uses nonstandard extensions.
Empty diff but spec “changed”	Vendor reformatted without semantic change; normalization deduped.
Exploded event count	Shared schema touched many operations—use cause grouping instead of per-row triage.
Fetch failures	Auth required, IP allowlists, WAF blocks, ephemeral signed URLs.

YAML safety

The parser includes guards against YAML bombs (excessive anchors/aliases). Pathological YAML may be rejected even when the vendor publishes it.

Testing a spec locally

1. Download the OpenAPI file your dependency uses.
2. Validate with a strict OpenAPI linter locally (Spectral, swagger-cli, etc.).
3. Fix structural errors, then re-point spec_url or upload flow if supported.

Related topics

• How diffs are generated
• Add a dependency
• Troubleshooting syncs