bundle() incorrectly escapes certain characters in JSON pointers in $ref's

[fireproofsocks]

This package is awesome, so thank you! However, I believe I have discovered a bug with the bundle() method when it creates a pointer to a location that contains special characters.

When I bundle my schema, I end up with something like this (reduced for simplicity):

{
  "paths":
    "/api/menus/{id}" : {
      "get": {
        "responses": {
           "200": {
              "schema": {
                  "type": "object",
                  "description": "Bundle successfully added my schema object here!"
                  ... etc...
              }
           }
        }
      }
    },
    "/api/menus/{id}/tree": {
       "get": {
          "responses": {
             "200": {
                 "description": "OK",
                 "schema": {
                    "$ref": "#/paths/~1api~1menus~1%7Bid%7D/get/responses/200/schema"
                  }
             }
           }
       }
    }
}

The problematic line is this:

    "$ref": "#/paths/~1api~1menus~1%7Bid%7D/get/responses/200/schema"

When I paste the bundled Swagger data into the online Swagger editor, it cannot resolve that reference (the error shows the line number). However, if I change %7B to { and %7D to }, the reference works and the error goes away.

The spec for JSON pointers is at https://tools.ietf.org/html/rfc6901 -- it's pretty heady, but I'm wondering if maybe things are in the weeds with the %x00-2E / %x30-7D / %x7F-10FFFF et al characters?

Is this a bug? Should { and } remain unescaped?

[JamesMessinger]

The short answer is that this is the correct behavior.

There are actually three different specs at play here: JSON Pointer (RFC 6901), JSON Reference (Draft 3), and URI (RFC 3986). Whenever you create a JSON Reference ($ref), you're actually using all three specs at once. Ultimately, this means that your reference url must be a valid URI, which is why special characters such as { and } get URI-encoded to %7B and %7D.

[fireproofsocks]

Interesting -- thanks for the detailed response. Do you suppose there is a bug in the online swagger editor in that it's not decoding the strings correctly?

[JamesMessinger]

Yeah, it looks like it. It appears that they aren't URL-decoding the $ref string before evaluating it.

A workaround would be to move your external file reference to the definitions section instead. Like this:

{
  "paths": {
    "/api/menus/{id}" : {
      "get": {
        "responses": {
           "200": {
              "schema": {
                "$ref": "#/definitions/menu"
              }
           }
        }
      }
    },
    "/api/menus/{id}/tree": {
       "get": {
          "responses": {
             "200": {
                 "description": "OK",
                 "schema": {
                    "$ref": "#/definitions/menu"
                  }
             }
           }
       }
    }
  },

  "definitions": {
    "menu": {
      "$ref": "menu.json"
    }
  }
}

That should cause the bundle() method to inject the contents of menu.json into the definitions section, and all other $ref strings will point to it there, so there won't be any special characters.

[fireproofsocks]

Thanks! I only ran into this problem when I started automating the building of the bundled swagger file -- for now I can manually define it as you described.

FYI, I opened a bug on the Swagger Editor repo: swagger-api/swagger-editor#1430