Dereferenced value is semantically different than provided schema

[brendarearden]

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: