Swagger 3 ref. component in component at top level - swagger

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

Answer 1

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