Dereferencing behavior on OpenAPI 3.1 schemas

[erunion]

Hi there! We have a fork that we're trying to wind down with the updates that yall have been doing here and one hang up we have is regarding dereferencing OpenAPI 3.1 schemas. Within the specification they allow you to have summary and description live alongside a $ref, with that summary and description taking precedence over any that may exist within the referenced schema.

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#reference-object

Looking at the new onDereference handler it at first glance seems like it would be be able to support this but it neither allows you to mutate the schema you have, as it's called after the schema has been dereferneced¹, nor does it surface the other schema elements to onDereference that live alongside the $ref property:

import $RefParser from ".";

const schema = {
  required: ['name'],
  type: 'object',
  definitions: {
    name: {
      type: 'string',
      description: "Someone's name",
    },
  },
  properties: {
    name: {
      $ref: '#/definitions/name',
    },
    secretName: {
      $ref: '#/definitions/name',
      description: "Someone's secret name",
    },
  },
  title: 'Person',
};

(async () => {
  await $RefParser.dereference(schema, {
    dereference: {
      onDereference: (path: any, value: any, parent: any, parentPropName: any) => {
        console.log('[onDereference]', { path, value, parent, parentPropName });
      },
    }
    });
})();

[onDereference] {
  path: '#/definitions/name',
  value: { type: 'string', description: "Someone's name" },
  parent: {
    name: { type: 'string', description: "Someone's name" },
    secretName: {
      '$ref': '#/definitions/name',
      description: "Someone's secret name"
    }
  },
  parentPropName: 'name'
}
[onDereference] {
  path: '#/definitions/name',
  value: { type: 'string', description: "Someone's name" },
  parent: {
    name: { type: 'string', description: "Someone's name" },
    secretName: { type: 'string', description: "Someone's name" }
  },
  parentPropName: 'secretName'
}

Because this work is exclusive to OpenAPI 3.1 schemas I don't know if it makes a whole lot of sense to be the default dereferencing behavior here, but do you have any ideas on how we could be able to support this within this library? We would love to get rid of our fork (that supports this specific behavior) so if we could maybe pull this in via an opt-in option of some sort, if you're into that, we'd happily PR it.

Footnotes

1. https://github.com/APIDevTools/json-schema-ref-parser/blob/70626d3189ce7b3d94f0f90076d21c20aa621d61/lib/dereference.ts#L126-L127 ↩

[jonluca]

Sure - I'm open to either a flag, or a new callback, or new parameters to the existing callback. If you make a PR I'll merge it in