Normalize relative ref paths to avoid duplicating schemas

[ctreatma]

Currently, if an OpenAPI spec contains multiple relative $refs that resolve to the same external resource, but those refs reach that resource through different relative paths, swagger-parser may treat them as distinct references and create duplicate resolved components.

For example, given references such as:

From the spec root: $ref: ./components/schemas/Thing.yaml
From a file under components/paths: $ref: ../../components/schemas/Thing.yaml

both references can ultimately identify the same Thing.yaml resource, but their paths may contain different relative segments when they reach the resolver. The parser can therefore resolve the same schema more than once, producing components such as Thing and Thing_1 instead of reusing Thing.

This change normalizes URI references before they are used as keys by ResolverCache. Equivalent paths containing . or .. segments therefore share the same resolution and external-file cache entries, while the original reference is still used when loading and deserializing the resource.

Because normalization is performed in ResolverCache, the behavior applies consistently to reference types resolved through the cache rather than being limited to schemas.

Fixes #2016, fixes #1518.

[nmarriotti]

Just ran into this issue today. Glad to see a fix is on the way (hopefully soon). Thanks!

[ctreatma]

I rebased on the latest from master to confirm that the issue described in this PR still exists and that the changes in this PR are sufficient to resolve it.

[ctreatma]

@MichakrawSB I see that this PR has been assigned to me but I'm not clear what needs to be done to move it forward. Is there something I need to address before the GitHub Actions workflows can be approved to run on this PR?

[ewaostrowska]

Hi @ctreatma! Thank you for the PR :)
I reworked the normalization to keep the fix small and focused.

Instead of using Paths, normalization now happens in ResolverCache via URI.normalize(). The Paths approach followed OS filesystem rules, so on Windows it could produce backslashes like ..\schemas\Foo.yaml. OpenAPI $ref values are URI references and must use /, so that was a correctness issue on Windows regardless of the duplicate-schema problem you were fixing.

The original $ref string is preserved for loading and error reporting — only the cache key is normalized. Because canonicalization sits in ResolverCache, it applies to every loadRef caller: PathsProcessor, OperationProcessor, ParameterProcessor, and SecuritySchemeProcessor, not just schemas. The cache is the single point where ref identity is decided, so normalizing there guarantees consistent behavior regardless of which processor resolves the ref first.

I expanded the regression tests to cover #2016, #1518, #1886, URI fragments, URL and file refs, invalid URI fallback, and a non-schema ApiResponse case.