Third call signature not mentioned in the docs

[qm3ster]

I am interested in

dereference(path: string, schema: string | JSONSchema4, options?: $RefParser.Options, callback?: (err: Error | null, schema: JSONSchema4 | null) => any): Promise<JSONSchema4>

used in bcherny/json-schema-to-typescript
Is there a discussion of this way somewhere?

[JamesMessinger]

Hi @qm3ster. You're right that the 4-parameter function signature isn't currently documented. I'll add that to my to-do list... or I'm always willing to accept a PR. 😄

Basically, the signature ends up being this:

dereference(path, schema, options?, callback?);

The last two parameters are optional, so if you're ok with the default options, and you're using Promises instead of callbacks, then your code could look something like this:

const mySchema = {
  "openapi": "3.0.0",
  "info": {
    "title": "test api",
    "version": "1.2.3",
  },
  "paths": {
    "/": {
      "get": {
        "responses": {
          "200": {         
            "description": "response"
          }
        }
      }
    }
  }
};

let result = await dereference("http://example.com/schema.json", mySchema);

[qm3ster]

I'm just trying to understand the exhaustive list of what can go in the first parameters.

• dereference(path: string makes sense. It takes a path and goes and grabs that schema, I would immediately assume using the resolvers.
• dereference(schema: JSONSchema4 | JSONSchema6 takes the ready schema, passed in as a JS object structure. Also makes sense.
• But dereference(path: string, schema: string | JSONSchema4 | JSONSchema6 scares the 💩 out of me!
  • Why can schema be a string? Is it a JSON string of the schema? Or is it a path to get it from, like the first signature I mentioned?
  • What is the path we are providing? Are we overriding the $id inside the schema? Are we overriding it just for resolving or will it affect the $id property on the output object?

[JamesMessinger]

The schema parameter can't be a string if path is also provided. It looks like the TypeScript definition is incorrect. The confusion probably arose because the documentation was written before the path parameter was added.

The json-schema-to-typescript repo that you referenced appears to be fine though. It's passing a path (string) and a schema (object), which is ok.

[qm3ster]

Yeah, but what is the path doing in that situation?
Does it take precedence over $id of the schema object?
Does it mutate that property inside the input object?
Does it replace it in the output resolved object?

[JamesMessinger]

The schema parameter effectively overrides the $id of the schema. It does not mutate the $id inside the schema or replace it in the output. The $id is just completely ignored. This is because json-schema-ref-parser isn't aware of the $id property at all.

[qm3ster]

Crystal clear, captain!