Let's consider the OpenAPI (aka swagger) sample (also on the cover image):
Person:
type: object
properties:
first_name:
type: string
middle_name:
type: string
last_name:
type: string
Is everything fine with it? What do you think? Is it designed well? How hard could it be to design a decent JSON Schema?
Before we proceed. There's an obsession going on around APIs. Several engineers are advocating for it. And this is great! Formats of OpenAPI, JSON Schema etc are not so great though. I want to write about this.
I published this as a thread on my Twitter, follow me there if you are interested in what I write about.
Required in Schemas
The schema from above is not good. It validates successfully the following JSON objects:
{}
{
"first_name": "Vladimir"
}
{
"last_name": "Sapronov"
}
It’s because all properties in JSON schema are not required by default. And since it’s JavaScript-centric, it makes a lot of sense. Everything is non-required in JS, especially when it comes to types.
Here’s the corrected schema:
Person:
required:
- first_name
- last_name
type: object
properties:
first_name:
type: string
middle_name:
type: string
last_name:
type: string
And here’s why it is sub-optimal: most object properties are required in real life. I would argue the ratio is around 80% required VS 20% optional. So it makes sense to design the spec syntax towards what is more common.
In any code (the other side of any API) non-required properties force you to verify if the property was supplied. So it bloats your code with a lot of if and null coalescing (??) operators. You should make as many properties required as you can.
Finally, it’s just a bad design. Even if there was a need to force everyone to explicitly declare their properties as required: why is this not a part of the property definition? Instead, it hangs out there at the top of the schema. Which is forcing developers to repeat most of the field names twice. Eeeew!
I have noticed that many developers are just unaware of this required field of the object schema and omit it, leading to all their properties being optional.
It's pretty easy to fix the design of JSON Schema. Here's one option:
requiredByDefault: true
...
Person:
type: object
properties:
first_name:
type: string
middle_name:
type: string
required: false
last_name:
type: string
Required in Operations
Parameters of operations also might be either required or not. Let's consider the operation below:
/fancy:
get:
operationId: fancy
parameters:
- in: query
name: person
required: true
schema:
type: string
Have you noticed how the required field is placed in the OpenAPI endpoint parameter? It’s within the parameter definition and it’s a boolean flag. So within the one specification format, the same thing is designed in two different ways: the required flag outside of a property definition and the required flag inside of a parameter definition.
- in: query
name: person
required: true
required:
- first_name
properties:
first_name:
type: string
At this point, it's obvious that required should be part of the parameter/property definition. The parameter design is a bit better but OpenAPI didn’t propagate the approach to JSON Schema properties.
The one common thing is that required is false by default for both: parameter and property. This is opposite to common sense programming logic: if you declare a param it is required by default unless you explicitly made it optional. There are no parameters in programming which are optional by default.
There was a ring bell to OpenAPI designers about this required being false by default. Path params can’t be optional. OpenAPI docs say: “If the parameter location is path, this property is REQUIRED and its value MUST be true.” Required by default would eliminate this.
The fix with requiredByDefault that was mentioned above would also work just fine for operations making all parameters required by default.
This story about required flag design is just a small example of OpenAPI design inconsistencies. More of those inconsistencies in this series...
