`application/vnd.api+json` in yml files loses the `+` on resolve

[langalex]

Running my openapi.yml file though speccy resolve creates invalid files when keys include a + symbol.

Detailed description

My openapi.yml file includes keys that contain a + (file abbreviated for clarity):

get:
  responses:
    200:
      content:
        application/vnd.api+json:
          schema:
            $ref: xyz.json

When running this file through speccy resolve, the resolved file contains the original application/vnd.api+json plus another key on the same level where the plus has been replaced with a space (application/vnd.api json) and the $ref pointing (but incorrectly) to the newly inserted key.

get:
  responses:
    200:
      content:
        application/vnd.api+json:
          schema:
            $ref: "#/paths/get/responses/200/content/application~1vnd.api%2Bjson/schema"
        application/vnd.api json:
          schema:
            some: resolved data

The %2B in the $ref is actually a + again when running it through decodeURIComponent. It looks like somewhere these keys are www-form encoded back and forth and the created the wrong keys.

When removing the +, everythung works as expected and there is no more duplicate key.

I think this is a bug. Not sure if in speccy or one of the dependencies.

Your environment

• Node Version: 10.9.0
• Operating system and version (e.g. Ubuntu 16.04, Windows 7): OSX
• Speccy 0.8.6
• package-lock.json: https://gist.github.com/langalex/da5f0dd7bb9e119df0a8e92c9ae6122a

[MikeRalphson]

@langalex perhaps we can lose the package-lock.json dump for brevity's sake?

Is your response/content key either $refd externally, or the subject of a $ref elsewhere in your document?

[langalex]

@MikeRalphson sorry I thought the package-lock might be important. will do.

the $ref points to another file (a JSON-Schema file)

[MikeRalphson]

Ok, thanks, will try and reproduce.

[langalex]

wow, that was fast, thanks. let me know if I can help.

[dlouzan]

@langalex I find pretty amazing that we found the same issue with a difference of 40 minutes xD I'm copying what I wrote in #243 for reference:

Today I found I'm experiencing some issues when using response types that include + and {} characters, when resolving to external references.

Example:

  /foo:
    get:
      summary: Foo
      operationId: foo
      responses:
        200:
          $ref: "responses.yaml#/components/responses/Foo"

components:
  responses:
    Foo:
      description: Success, returning the root context and list of things
      content:
        application/ld+json:
          schema:
            $ref: "schemas.yaml#/components/schemas/Foo"

When I try to speccy resolve this generates an incorrect yaml file such as below with two equal keys, but one key missing the + (I don't think that's even valid yaml). Also JSON pointers don't seem to work properly when referencing anything including these special characters in the path.

      responses:
        '200':
          description: 'Success, returning the root context and list of things'
          content:
            application/ld+json:
              schema:
                $ref: '#/paths/~1foo/get/responses/200/content/application~1ld%2Bjson/schema'
                x-miro: 'schemas.yaml#/components/schemas/Foo'
            application/ld json:
              schema:
                title: Thing Description graph
                description: A Graph of Things in JSON-LD format.
                type: object
...

[MikeRalphson]

two equal keys, but one key missing the + (I don't think that's even valid yaml).

Just a note that if one key doesn't include the + then the keys aren't equal 😄 and a key with a space in it is valid YAML.

I'm adding some test cases over at oas-kit to narrow down where this issue is happening...

[dlouzan]

Well yes, I didn't mean that they were the same key, just that the linter was trying to create the same entry twice with different values ;-)

But I didn't know you could actually write a multi-word key without quoting, TIL, go figure xD

[dlouzan]

Another note: in my tests, the curly braces are also being url-encoded in the generated $refs:

• original request path:

  /.foos/{fooID}/.bars
    get:
      ...
  

• generated $ref:

  $ref: '#/paths/~1.foos~1%7BfooID%7D~1.bars/get/parameters/0'
  

The swagger documentation actually shows a sample with this and they don't encode them, though I'm not sure which is right:

$ref: '#/paths/~1blogs~1{blog_id}~1new~0posts'

[MikeRalphson]

Curly braces definitely do need encoding in url fragment ids / json pointers. We discussed it on an OpenAPI-Specification TSC call. I don't think we've updated the spec examples yet. The documentation on swagger.io is useful, but not authorative.

[MikeRalphson]

Fix and tests for the + problem have gone into Mermade/oas-kit@2f69f87 - had to move one whole bracket! Will be part of the v5.0.0 release of swagger2openapi which will hopefully be released this week.

[MikeRalphson]

oas-resolver v2.0.0 and reftools v1.0.5 have just been released including the fix for this issue.