$ref with other keywords doesn't work

[zyoshoka]

Description

In the specifications up to the JSON Schema Draft 7, if you included other keywords in an object using $ref, they were ignored¹, but starting with the Draft 2019-09, you are allowed to include other properties in $ref². Since the OAS 3.1.0 is 100% compatible with the Draft 2020-12³, the OAS 3.1.0 allows such usage, but openapi-typescript does not reflect it in the type definition.

Name	Version
openapi-typescript	7.0.0-next.8
Node.js	21.7.1
OS + version	macOS 14.4

Reproduction

1. Generate type definitions using the following document:

OpenAPI document

{
  "openapi": "3.1.0",
  "info": {
    "title": "Example API",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://example.com/api"
    }
  ],
  "security": [],
  "paths": {
    "/example": {
      "get": {
        "operationId": "getExample",
        "summary": "Get example",
        "responses": {
          "200": {
            "description": "Get successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/example",
                  "properties": {
                    "b": "number"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "example": {
        "type": "object",
        "properties": {
          "a": {
            "type": "string"
          }
        },
        "required": [
          "a"
        ]
      }
    }
  }
}

2. Then you get the following result:

content: {
  "application/json": components["schemas"]["example"];
};

Expected result

I think this would have to be:

content: {
  "application/json": components["schemas"]["example"] & { b?: number };
};

Checklist

• My OpenAPI schema passes the Redocly validator (npx @redocly/cli@latest lint)
• I’m willing to open a PR (see CONTRIBUTING.md)

Footnotes

1. https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-01#section-8.3 ↩

2. https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-02#section-8.2.4.1 ↩

3. https://www.openapis.org/blog/2021/02/18/openapi-specification-3-1-released ↩

[drwpow]

This is a good addition! I think 6.x or 7.x (beta) could support this addition without it being a breaking change. Would love a PR for this if anyone is able to provide one!

[armaneous]

Not sure if I should create another issue for this, but I think it might be related to the above. In the case of composition, required gets ignored in this scenario:

{
    ...
    "components": {
        "schemas": {
            "Foo": {
                "type": "object"
                "properties": {
                    "id": {
                        ...
                    }
                }
            },
            "Bar": {
                "allOf": [
                    { "$ref": "#/components/schemas/Foo" },
                    { "required": ["id"] }
                ]
            }
        }
    }
}