Swagger 3 ref. component in component at top level

Question

VehicleBaseAttributes:
  type: object
  properties:
    id:
      type: integer
      format: int64
    model:
      type: string
    doors:
      type: integer
VehicleExtendedAttributes:
  type: object
  properties:
    $ref: '#/components/schemas/VehicleBaseAttributes'
    pricehistory:
      type: array
      items:
        title: PriceHistory
        type: object
        properties:
          priceWOT:
            type: number
          taxes:
            type: number
          additionalCosts:
            type: number
          price:
            type: number
          createdByUserId:
            type: string
          createdDate:
            type: string
    dealerHistory:
      type: array
      items:
        title: DealerHistory
        type: object
        properties:
          name:
            type: string
          phone:
            type: string
          createdByUserId:
            type: string
          createdDate:
            type: string

In the above example I intended to have a basic set of attributes defined, then offer an extended version that used the base version.

Obviously in the VehicleExtendedAttributes I don't want to nest the VehicleBaseAttributes in a separate attribute, instead for them to be added to the top level, resulting in an output of something like:

  type: object
  properties:
    id:
      type: integer
      format: int64
    model:
      type: string
    doors:
      type: integer
    pricehistory:
      type: array
      items:
        title: PriceHistory
        type: object
        properties:
          priceWOT:
            type: number
          taxes:
            type: number
          additionalCosts:
            type: number
          price:
            type: number
          createdByUserId:
            type: string
          createdDate:
            type: string
    dealerHistory:
      type: array
      items:
        title: DealerHistory
        type: object
        properties:
          name:
            type: string
          phone:
            type: string
          createdByUserId:
            type: string
          createdDate:
            type: string

The problem is this results in an error:

Schema error at components.schemas['VehicleExtendedAttributes']
should have required property '$ref'
missingProperty: $ref
Jump to line 342
Schema error at components.schemas['VehicleExtendedAttributes']
should match exactly one schema in oneOf
Jump to line 342
Schema error at components.schemas['VehicleExtendedAttributes'].properties['$ref']
should be object
Jump to line 345

Possible duplicate of [Swagger composition / inheritance](https://stackoverflow.com/questions/31025120/swagger-composition-inheritance) — Helen, Feb 04 '18 at 19:22

score 1 · Accepted Answer · answered Feb 04 '18 at 19:22

You need allOf to do model composition. The value of allOf is a list of subschemas ($referenced or inline) that together compose a single schema.

VehicleExtendedAttributes:
  allOf:
    - $ref: '#/components/schemas/VehicleBaseAttributes'
    - type: object
      properties:
        pricehistory:
          type: array
          ...
        dealerHistory:
          type: array
          ...

Further info:

Swagger Inheritance and Composition here on Stack Overflow
Composition and Inheritance (Polymorphism) section of the OpenAPI 3.0 Specification
Model Composition, Inheritance and Polymorphism
oneOf, anyOf, allOf, not

Swagger 3 ref. component in component at top level

1 Answers1