Context

This issue was first noticed in elements. The resulting dereferenced and bundled file is changing the original definition of the schema.

Current Behavior

When dereferencing and bundling the following oas schema:
file1.yaml :

openapi: 3.1.0 info: title: Test version: version paths: /operation: post: requestBody: content: application/json: schema: type: object properties: AAAAA: $ref: 'file2.yaml' description: AAAAA foo: bar examples: - AAAAA BBBBB: $ref: 'file2.yaml' description: BBBBB examples: - BBBBB 

file2.yaml:

title: referenced type: string 

you get the following output from the bundler:

{ openapi: "3.1.0", info: { title: "Test", version: "version" }, paths: { "/operation": { post: { requestBody: { content: { "application/json": { schema: { type: "object", properties: { AAAAA: { description: "AAAAA", title: "referenced", type: "string", foo: "bar", }, BBBBB: { $ref: "#/paths/~1operation/post/requestBody/content/application~1json/schema/properties/AAAAA", description: "BBBBB", examples: ["BBBBB"], }, }, }, }, }, }, }, }, }, }; 

This is changing the original definition of #/paths/~1operation/post/requestBody/content/application~1json/schema/properties/BBBBB
from

 BBBBB: title: referenced type: string description: BBBBB examples: - BBBBB 

to (depending on how description is handled by the particular ref resolver)

 BBBBB: description: BBBBB examples: - BBBBB title: "referenced", type: "string", foo: "bar", 

Expected Behavior

The bundler should bundler the shared reference into the document in a way that does not change the definition. OR we need to decide if we are going to lean more into OAS schema rules and not allow ref siblings that aren't description, or summary and remove all other siblings to ensure the definition doesn't change.

Possible Workaround/Solution

Us an allOf to include additional values for your property so that the ref can be in its own object

Steps to Reproduce

1. Write a test that uses let schema = await $RefParser.bundle(path.rel("specs/bundle/file1.yaml")); pointing to the file1.yaml provided in the current behavior section. Ensure you also place file2.yaml in the same dir so that it can dereference properly.
2. See how the file resolves and bundles the references

Environment

• Version used:
• Environment name and version (e.g. Chrome 39, node.js 5.4):
• Operating System and version (desktop or mobile):
• Link to your environment/workspace/project: