overriding and extending references

[florianhof]

Problem I would like to use deprecated to move a property from let's say a property status from class/schema A to class/schema B. Sadly, declaring the property A.status as deprecated also marks the whole type Status as deprecated and all its references like B.status.

Whish I would like to benefit from OpenAPI 3.1 (over 3.0) to define siblings to $ref. See more in https://github.com/Redocly/redoc/issues/2042#issuecomment-1155294637 First, additional / sibling attributes like deprecated would extend a property. Second, some special sibling attributes like description would override the value. It is common to have an attibute's description more specific than the type's description.

Alternative I couldn't imagine any viable alternative.

Details The java code I have:

@Schema(description = "status blabla.")
class Status {}
class A {
   @Schema(description = "status blabla. Deprecated, now on B::status", deprecated = true)
   @Deprecated Status status; // old place
}
class B {
   @Schema(description = "status blabla.")
   Status status; // new place
}

The current result:

{... , 
  "components": {
    "schemas": [
      "Status": {
        "deprecated": true, 
        ...
      },
      "A": {
        "properties": [
          "status": {
            "$ref": "#/components/schemas/Status"
          }, ...
        ], ...
      }, ...
    ]
  }
}

The desired result (valid since OpenAPI 3.1):

{... , 
  "components": {
    "schemas": [
      "Status": {
        "deprecated": false, 
        "description": "status blabla", 
        ...
      },
      "A": {
        "properties": [
          "status": {
            "$ref": "#/components/schemas/Status",
            "deprecated": true,
            "description": "status blabla. Deprecated, now on B::status",
          }, ...
        ], ...
      }, ...
    ]
  }
}