This content originally appeared on DEV Community and was authored by Vladimir Sapronov
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. There are a number of engineers advocating for it. And this is great! Formats of OpenAPI, AsyncAPI, JSON Schema etc are not so great though. I would like to write about this.
I published this as a thread in my Twitter, follow me there if you are interested in what I write about.
The schema from above is not good. It validates successfully following JSON objects.
{} // empty object
{
"first_name": "Vladimir" // only first_name is provided
}
{
"last_name": "Sapronov" // only last_name is provided
}
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: # you need to specify this!!!
- 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 absolutely makes sense to design the spec syntax towards what is more common.
In any code (which is 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 not aware of this required field of the object schema and omit it which leads to all their properties being optional.
It's pretty easy to fix the design of JSON Schema. Here's one option:
requiredByDefault: true # makes all properties
# required by default
...
Person:
type: object
properties:
first_name:
type: string
middle_name:
type: string
required: false # if some property is not required
last_name: # it should be specified explicitly
type: string
This is just a teeny tiny example of how required is broken in pretty much all specs based on JSON Schema. I'm going to describe more flaws of OpenAPI in this thread of posts.
This content originally appeared on DEV Community and was authored by Vladimir Sapronov
Vladimir Sapronov | Sciencx (2022-06-03T17:52:36+00:00) OpenAPI Flaws – Required in Schemas. Retrieved from https://www.scien.cx/2022/06/03/openapi-flaws-required-in-schemas/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.