JSON References aren't properly URL-decoded

[JamesMessinger]

Swagger Editor erroneously shows "Reference could not be resolved" errors for JSON references that contain URL-encoded characters. For example, "#/definitions/foo%20bar" instead of "#/definitions/foo bar". According to RFC 6901, sections 5 & 6, JSON pointers should be URL-encoded.

Here's a simplistic example: https://gist.github.com/BigstickCarpet/5ad1a760acbb598d38c5dbba223eb9bd

And here's a more real-world example: https://gist.github.com/BigstickCarpet/e867ccd425e730634ee71f43c462a34f

As far as I know, Swagger Editor uses json-refs under the hood to do its JSON Pointer decoding. json-refs has the correct logic for decoding URL-encoded JSON Pointers, so maybe Swagger Editor is just using an older version of json-refs? Maybe @whitlockjc can provide more info.

[glen-84]

I think this is affecting Swagger UI as well.

[saharj]

This is a Sway issue.

[glen-84]

@saharj Thanks, I've submitted apigee-127/sway#72.

[shockey]

The resolution is fixed in 3.x, but there's an incorrect "Definition is never used" warning when using the correctly escaped $ref (with %20).

[glen-84]

When this is fixed, I can bundle my spec and reduce the file size by over 50%.

[glen-84]

Actually no, I'm still seeing:

Semantic error at paths./blogs/{id}/posts.get.responses.200.schema.items.$ref
$refs must reference a valid location in the document

With this file.

Is https://editor.swagger.io/ using the latest version?

[shockey]

Yeah, you're right @glen-84, this has cropped back up.

Reopening!

[shockey]

This is going to land in a few parts (this week):

1. Extending Swagger-Client to handle percent-encoded $refs, while still allowing unescaped values* so that we don't break anyone's documents
2. Adding validators for unescaped $ref values in Swagger-Editor
3. Taming the validators that complain about escaped $ref values

*I usually don't allow non-spec behavior to hang around, but since the correct way to do this has been broken and the incorrect way has been working, I imagine we have a lot of this in the wild. I've made a note in the codebase to consider dropping this behavior in v4.