Pass argument to `$ref` in OpenAPI 3

Question

Assume I have following schema to reuse later using $ref:

"schemas": {
      "Order": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "petId": {
            "type": "integer",
            "format": "int64"
          }
        }
      }

But I have another schema similar to this:

"schemas": {
      "Order": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "itemId": {
            "type": "integer",
            "format": "int64"
          }
        }
      }

Only difference between them is itemId and petId, I want to create only one schema and pass itemId or petId when referencing. How to accomplish this? Are there any alternative solutions?

Answer 1

There's no way to pass arguments along a schema reference, really.

What we could do in your case is to have a base Order schema with just the common properties, and then separate schemas for petId/itemId Orders that utilize allOf.

Check this answer for another example (or this for a more concrete one!).