Validator does not resolve ref's with / in key names

[devjack]

JSON Reference RFC defines an order for resolving & encoding key values in a reference. e.g. a/b should be addressed as a~1b. The validator fails to resolve these edge cases, preventing /some/path from being a valuid $ref.

Checklist

• Validation: I believe my source definition is valid OpenAPI 3.0.x but the validator complains

Detailed Description

The validator fails to resolve ~1 in references correctly, such that the following example fails:

openapi.yml

paths:
    "/":
        $ref: "endpoints/foo.yml#/paths/~1"
    '/{id}':
        $ref: "endpoints/foo.yml#/paths/~1{id}"

endpoints/foo.yml:

paths:
    '/':
        get:
          responses:
            '200':
            ... ... ... and so on ... ... ...

In the above example, the validator incorrectly fails with:

Failed OpenAPI3 schema validation: [
  {
    "keyword": "type",
    "dataPath": "/paths/~1",
    "schemaPath": "#/type",
    "params": {
      "type": "object"
    },
    "message": "should be object",

Background:

RFC 6901 defines a JSON Reference. Specifically (from section 5.):

For example, given the JSON document

 {
     "foo": ["bar", "baz"],
     "": 0,
     "a/b": 1,
  }

The following JSON strings evaluate to the accompanying values:

   ""           // the whole document
   "/foo"       ["bar", "baz"]
   "/foo/0"     "bar"
   "/"          0
   "/a~1b"      1

[devjack]

I've implemented a similar JSON ref parser in python in this project & code. This may help as a reference example.

[devjack]

Seems that the when resolving external references here and here it falls back to resolveInternal() which in tern calls jptr.jptr(root, pointer) here.

Cursory search shows jptr implements ~1 parsing properly.

[devjack]

In trying to develop a simple test case for this I also found that the components/schemas/<name> validation is too specific, not allowing / characters:

e.g.

openapi: 3.0.0
info:
    title: Example API
    description: Tests ~1 resolving in ref
    version: 0.0.1

servers:
  - url: 'https://localhost:8080/'
    description: Example
paths:
    "/":
        get:
          responses:
            '200':
              description: Example
              content:
                application/json:
                  schema:
                    type: array
                    items:
                      $ref: '#/components/schemas/Example~1Respnse'

components:
    schemas:
        "Example/Response":
            required:
                - Id
            properties:
              Id:
                type: string
                format: uuid
                example: "d2014f64-ffdf-487b-8d12-67a20976aca6"

Resulting in:

Gathering...
#/components/schemas/Example/Response
component name invalid
examples/pathrefs.yml
  Example API 0.0.1
  https://localhost:8080/

Failures:
examples/pathrefs.yml

[MikeRalphson]

/ is not valid in a component name.

"All the fixed fields declared above are objects that MUST use keys that match the regular expression: ^[a-zA-Z0-9\.\-_]+$"

Sorry for being terse, on my phone.

[MikeRalphson]

Re: the first point, did you install v2.7.0 from npm, or update a git clone? If the latter, you may need to npm i to bring in the latest version of jgexml / jptr.

[devjack]

@MikeRalphson you're spot on here. Turns out it's not the pointer but the external resolution. I'll open a separate issue w/ details and a partial solution.