Unable to resolve schema.example.$ref

[mailingmuthu]

As per the definition in https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#fixed-fields-13 we have swagger.json where we have defined schema example with "$ref": "../examples/example1.json" as given below. But npm swagger-parser (3.3.0) .dereference() is throwing error like file not found, error resolving $ref.

Is there anything we defined against standards or issue with swagger-parser lib resolving $ref ?

swagger.json: "responses": { "200": { "description": "Successful response", "schema": { "$ref": "./credit_card.json", "example": { "$ref": "../examples/example1.json" } } } },

Api tree: API | |__examples/example1.json | |__schema/swagger.json

Error: { "name": "Error", "message": "Error resolving $ref pointer "/temp/../../blah/blah/../../examples/example1.json". "/temp/../../blahblah../../examples/example1.json" not found.", "stack": "Error: Error resolving $ref pointer "/temp/../../blah/blah/../../examples/example1.json". "/temp/../../blah/blah/../../examples/example1.json" not found. at ono (/temp/../../../../../../swagger-parser/node_modules/ono/lib/index.js:67:20) at $Refs._resolve (/temp/../../../../../../../node_modules/swagger-parser/node_modules/json-schema-ref-parser/lib/refs.js:150:11) at /temp/../../../../../..//node_modules/swagger-parser/node_modules/json-schema-ref-parser/lib/dereference.js:49:29 at Array.forEach (native) at crawl (/temp/../../../../../../../node_modules/swagger-parser/node_modules/json-schema-ref-parser/lib/dereference.js:40:22) at /temp/../../../../../../../node_modules/swagger-parser/node_modules/json-schema-ref-parser/lib/dereference.js:61:22 at Array.forEach (native) at crawl (/temp/../../../../../../../node_modules/swagger-parser/node_modules/json-schema-ref-parser/lib/dereference.js:40:22) at /temp/../../../../../../../node_modules/swagger-parser/node_modules/json-schema-ref-parser/lib/dereference.js:71:22 at Array.forEach (native)" }

[JamesMessinger]

Can you double-check the full file path in the error message, to make sure it's correct. My guess is that some part of the path is missing or misspelled.

Error: Error resolving $ref pointer "/temp/../../blah/blah/../../examples/example1.json".
"/temp/../../blah/blah/../../examples/example1.json" not found.

I've tested external $ref paths pretty thoroughly, so it should work fine.

[mailingmuthu]

Yes path is correct. I just replaced and masked the error path in Issue description. Error "not found" is not something like File not found. It is Array element not found in $ref (code attached below). Could you please try like the sample below (you can see clearly if you do JSON formate) you will get the error.

"responses": { "200": { "description": "Successful response", "schema": { "$ref": "./credit_card.json", "example": { "$ref": "../examples/example1.json" } } } }

json-schema-ref-parser/lib/refs.js: var $ref = this._$refs[withoutHash]; if (!$ref) { Error throws here}

[JamesMessinger]

Ok. Now I see what you're talking about. And you're right, the file paths have nothing to do with it.

The bad news: This is, in fact, a bug The good news: There's an easy workaround for the time being

First, let's dissect the problem. Here's an example schema that reproduces the problem:

swagger: '2.0'
info:
  version: 1.0.0
  title: Issue #36
paths:
  /pets:
    get:
      responses:
        200:
          description: Successful response
          schema:
            $ref: credit-card.yaml            # <-- This $ref resolves fine
            example:
              $ref: credit-card-example.yaml  # <-- This $ref doesn't get resolved

Interestingly, the above example does work if you use internal references rather than external ones:

swagger: '2.0'
info:
  version: 1.0.0
  title: Issue #36
paths:
  /pets:
    get:
      responses:
        200:
          description: Successful response
          schema:
            $ref: "#/definitions/credit-card"                    # <-- This $ref resolves fine
            example:
              $ref: "#/definitions/credit-card-example/example"  # <-- This $ref resolves fine
definitions:
  credit-card:
    type: object
    properties:
      number:
        type: string

  credit-card-example:
    type: object
    example:
      number: 1234-5678-9012-3456

However, there's an easy workaround for now. Just put the example inside the credit-card schema:

swagger.yaml

swagger: '2.0'
info:
  version: 1.0.0
  title: Issue #36
paths:
  /pets:
    get:
      responses:
        200:
          description: Successful response
          schema:
            $ref: credit-card.yaml        # <-- This $ref resolves fine

credit-card.yaml

type: object
properties:
  number:
    type: string
example:
  $ref: credit-card-example.json          # <-- This $ref resolves fine

credit-card-example.json

{
  "number": "1234-5678-9012-3456"
}

[mailingmuthu]

Thanks for your time to analyze on this issue. As per your suggestion, temporarily we are using "Just put the example inside the credit-card schema". May i know when you have planned to resolve this bug or already resolved, any update on this? Thanks in advance.

[JamesMessinger]

I'm pretty sure I already know where the bug is, and it shouldn't be hard to fix at all. That said... my schedule is super busy right now, so I may not have time to get this fixed for a while.

[mailingmuthu]

Could you please direct me where exactly the issue is and fix. so that i can try if possible and time permits.

[JamesMessinger]

Sure! I'd certainly appreciate your help. I'm pretty sure the bug is in the crawl() method in resolve.js

[philsturgeon]

Help offered but not received.