🐞 Swagger Editor 5.03 -- Invalid validation error when using \$ref inside operation callbacks

[mdaneri]

Description

When documenting OpenAPI callbacks in an operation using the callbacks
object, Swagger Editor 5.03 incorrectly rejects valid callback
component references ($ref) with the following errors:

Callback Object values must be of Path Item Object shape
Callback Object values must be of Path Item Object shape

The validator seems to assume that callback entries are always
Callback Objects, ignoring that the OpenAPI 3.0.x specification
explicitly allows Reference Objects ($ref) at this location.

According to the OpenAPI 3.0.4 spec:

• operation.callbacks is defined as:
  Map[string, Callback Object | Reference Object]
• A Callback Object is a map of:
  {expression} -> Path Item Object
• A Reference Object ($ref) is valid and should not be treated
  as a Callback Object itself

Swagger Editor fails validation even when $ref points to a valid
callback component, blocking editing and schema verification.

---

Expected behavior

Swagger Editor should:

• Accept callback entries that are $ref Reference Objects
• Resolve and validate the referenced callback component (which is
  already in Path Item Object shape)
• Not enforce Path Item Object shape on the $ref itself

---

Actual behavior

Swagger Editor incorrectly applies Path Item Object validation to the
$ref entry instead of validating the resolved referenced object.

---

Steps to reproduce

1. Open Swagger Editor 5.03
2. Load this minimal valid OpenAPI snippet:

{
  "openapi": "3.0.4",
  "paths": {
    "/v1/payments": {
      "post": {
        "summary": "Create payment",         
        "responses": { "201": { "description": "Created" } },
        "callbacks": {
          "reservation": { "$ref": "#/components/callbacks/reservationCallback" }
        }
      }
    }
  },
  "components": {
    "callbacks": {
      "reservationCallback": {
        "{$request.body#/callbackUrls/reservation}/v1/orders/{orderId}/reservation": {
          "post": {
            "summary": "Reservation callback",
            "responses": { "204": { "description": "Accepted" } }
          }
        }
      }
    }
  }
}

1. Observe validation failure

---

Environment

• Swagger Editor version: 5.03
• Browser: Any (UI validation)
• Spec version used: 3.0.4 / 3.0.x family
• Issue type: False negative schema validation error

---

Additional notes

This breaks real-world designs where callback components are reused and
referenced from operations, especially for:

• Webhooks
• Async payment status notifications
• Reservation/shipping/order event callbacks
• Code generators relying on $ref reuse

---

Suggested fix

Ensure callback validation runs against:

1. Inline Callback Object → validate
   {expression} -> Path Item Object
2. $ref Reference Object → resolve first, then validate resolved
   content, not the $ref entry itself

---

References

• OpenAPI 3.0.4 spec definition for operation.callbacks
• Reference Objects allowed in callback maps

---

Thank you! Let me know if you need me to generate an even smaller
minimal repro or attach references.