Define properties order in Schema objects #2424
Description
At the moment, field defined in schema objects are rendered in the following order
- If there is no composition used then properties are rendered in the same order as defined in the object
- If the composition is used then first properties from a "parent" object are rendered and then properties from of the "child" object are rendered.
Example
Here is a small example
openapi: 3.0.1
info:
title: Swagger Petstore
version: 1.0.0
paths:
/cars:
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Car'
required: true
responses:
405:
description: Invalid input
content: {}
/planes:
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Plane'
required: true
responses:
405:
description: Invalid input
content: {}
components:
schemas:
Vehicle:
type: object
properties:
id:
type: string
manufacturer:
type: string
Car:
allOf:
- $ref: "#/components/schemas/Vehicle"
required:
- id
- make
type: object
properties:
make:
type: string
num_of_wheels:
type: integer
format: int64
Plane:
required:
- id
- manufacturer
type: object
properties:
altitude:
type: integer
allOf:
- $ref: "#/components/schemas/Vehicle"
As you can see both Car and Plane are extended from Vehicle object. Let's have a look how it is rendered:
Properties of the Vehicle are rendered first. Then the properties of Plane and Car are rendered accordingly.
Change order
If to change the order of fields in the Car object, .e.g swap make with num_of_wheels like this
Car:
allOf:
- $ref: "#/components/schemas/Vehicle"
required:
- id
- make
type: object
properties:
num_of_wheels:
type: integer
format: int64
make:
type: string
then the order of rendered fields will change accordingly, but still the properties of the Vehicle will be rendered first.
In some cases this complicates schema readability when the object has dozens of properties. For example, to increase the readability it would be better to list first requires or most important properties and then optional or less important properties.
Suggestion
I would like to ask you what do you think about adding an additional optional property to the Schema object where API designers could define the order of appearance for properties.
Below you can find the example how it may look like in the schema:
Car:
allOf:
- $ref: "#/components/schemas/Vehicle"
required:
- id
- make
type: object
order:
- id
- make
- num_of_wheels
- manufacturer
properties:
num_of_wheels:
type: integer
format: int64
make:
type: string
Here, the order field defines the order in which object properties must be rendered.