Understanding OpenAPI URL Canonicalization and Path Matching

Learn why OpenAPI does not mandate URL canonicalization for trailing slashes and how URL equivalence depends on URI standards like RFC3986 and RFC9110.
---
This video is based on the question https://stackoverflow.com/q/79412454/ asked by the user 'Luis Abreu' ( https://stackoverflow.com/u/15848/ ) and on the answer https://stackoverflow.com/a/79412542/ provided by the user 'Henry Andrews' ( https://stackoverflow.com/u/15845464/ ) at 'Stack Overflow' website. Thanks to these great users and Stackexchange community for their contributions.

Visit these links for original content and any more details, such as alternate solutions, latest updates/developments on topic, comments, revision history etc. For example, the original title of the Question was: OpenAPI specification and URL canonicalization

Also, Content (except music) licensed under CC BY-SA https://meta.stackexchange.com/help/l...
The original Question post is licensed under the 'CC BY-SA 4.0' ( https://creativecommons.org/licenses/... ) license, and the original Answer post is licensed under the 'CC BY-SA 4.0' ( https://creativecommons.org/licenses/... ) license.

If anything seems off to you, please feel free to drop me a comment under this video.
---
The Problem: URL Matching in OpenAPI Validators

When using OpenAPI validators, you might notice inconsistent behavior in path matching, especially concerning trailing slashes.

For example:

/abc/path matches your API path.

/abc/path/ (with a trailing slash) does not match.

This raises the question: Does OpenAPI require URL canonicalization (normalization) before path matching?



Why OpenAPI Defers to URI Standards for URL Equivalence

OpenAPI Specification (OAS) does not define how to normalize or canonize URLs for path matching. Instead, it defers to established URI and HTTP standards:

RFC 3986 – Defines generic URI syntax and normalization principles.

RFC 9110 – Specifies HTTP semantics including path equivalence rules.

Key Point on Trailing Slashes:

According to RFC 9110, only a path consisting solely of a slash (/) is considered equivalent to an empty path.

There is no standard equivalence stating /abc/path is the same as /abc/path/.

This means:

It is entirely valid for an API to treat these as different paths.

OpenAPI cannot enforce treating trailing slash variants as equivalent.

It's a convention, not a requirement, to consider trailing slashes interchangeable.



Best Practices and What to Expect

Design your API paths consistently: Decide whether to include or exclude trailing slashes and document your choice clearly.

Configure your server or gateway to normalize URLs if you want consistent handling.

Validate using tools that respect these standards, understanding there is no guaranteed equivalence.



Additional Context: OpenAPI Spec Evolution

Existing tools like OASComply were early attempts to address ambiguities in OpenAPI specs.

The OpenAPI community continues to improve specification clarity (versions 3.0.4, 3.1.1, and upcoming 3.2).

Ambiguities around URL normalization remain inherent due to the flexibility allowed by HTTP standards.



Summary

OpenAPI leaves URL canonicalization and equivalence to standard URI rules. Since no standard equates a path with and without a trailing slash, validators that treat these paths differently are compliant. Consistency in API design and awareness of these standards are essential to avoid surprises.



References:

RFC 3986: URI Generic Syntax

RFC 9110: HTTP Semantics