Stuck on an issue?

The problem with simply keeping the $ref property (or renaming it) is that the same object can be referenced in many different places, so which $ref do you keep?

@JamesMessinger That’s a great catch!

Thinking about it more, I wonder if a simpler and more general-purpose approach might be to avoid setting a property at all, and exposing an onDereference hook instead.

One possible API:

const result = await $RefParser.dereference('schema.json', {
  onDereference(originalSourceSchema, dereferencedSchema, originalRefPath, absoluteRefPath) {
    // ...
  }
})

A consumer might then use this API to build up a mapping:

const map = new Map

const result = await $RefParser.dereference('schema.json', {
  onDereference(originalSourceSchema, dereferencedSchema, originalRefPath, absoluteRefPath) {
    if (!map.has(dereferencedSchema)) {
      map.set(dereferencedSchema, new Set)
    }
    map.get(dereferencedSchema).add(originalRefPath)
  }
})

This approach has a few benefits over the Symbol-based approach:

• It’s strictly backwards-compatible, while I can come up with some convoluted cases where the Symbol-based approach is not
• It more closely sticks to the JSON-Schema spec, and avoids having to monkey-patch in properties specific to json-schema-ref-parser (in practice, this would mostly affect consumers that use TypeScript)
• It supports use cases that the Symbol-based approach does not (say, also collecting the original $ref-containing schemas)
• It’s extensible without additional breaking changes. eg. down the line we could introduce a 5th parameter for the onDereference callback, without breaking clients (not so for the Symbol-based approach)

Author of json-schema-to-typescript here. We’d love this features, as it would unblock a handful of issues related to emitting more intelligent TypeScript types.

As specific example, consider the following JSON Schema:

{
  additionalProperties: false,
  definitions: {
    a: {type: 'string'},
    b: {type: 'number'}
  },
  properties: {
    c: {
      additionalItems: false,
      items: [{$ref: '#/definitions/a'}, {$ref: '#/definitions/b'}],
      type: 'array'
    }
  },
  title: 'X,
  type: 'object'
}

We’d like to emit the following TypeScript types for this schema:

type A = string
type B = number

type X = {
  c: [] | [A] | [A, B]
}

Today, we accomplish this by always emitting standalone type names (here, A and B) for tuple members. However, this isn’t the right behavior; it would be nice to refine our heuristic, where we look for the presences of $refs as a sign that a type is meant to be reused, and therefore, named (we already use ids and titles for this today).

To do that, we’d love a way to know what a schema’s original $ref pointed to. Any key name is fine for us, though you might consider using a Symbol in order to avoid a backwards-incompatible change to this library, and to avoid colliding with existing keys.

As a side note: It’s possible to infer something like this today (roughly: traverse over a dereferenced schema and its source schema at the same time, and annotate the dereferenced schema where you see a $ref in its source schema). But this is a hack that doesn’t work when a source node is in another file, since $RefParser.resolve(..).get(..) returns a dereferenced schema, not a source schema.

Please let me known if this is not something you’re interested in, and I’ll go ahead and fork json-schema-ref-parser so we can patch it in for our use case.