Structure of JSON schemas in the OpenAPI documentation
The JSON schemas describing the resources in the OpenAPI documentation are generated mainly from a custom YAML file describing the resources, with the help of a script, so that we first maintain files expressed at a higher level than the OpenAPI specification format.
This documentation helps the developer understand how the JSON schemas are structured in the generated OpenAPI specification.
Primer
In our resource YAML file, fields can be marked namely in the following manners:
| Marker | Description |
|---|---|
x-no-update |
Non-updatable field. Used for stuff that can/must be given on create, but that cannot be changed after. x- marker because this is non-standard OpenAPI and is just used during the generation process. |
readOnly |
Read-only field. Used for non-updatable fields that cannot be created by the API clients (e.g., automatically generated surrogate keys / UUIDs). |
nullable |
Nullable field. |
default |
Field with a default value. |
In addition, we define required fields as the following:
NOT read only AND NOT nullable AND NO default value AND NOT explicitely marked
required: false
This allows not having to manually specify a required attribute everywhere,
and rather infer it from more meaningful information that we make explicit in
our resource YAML file.
JSON schema structure
With the previous information, we can now show the structure of JSON schemas generated by our script:
| Schema | OpenAPI name | Contains |
|---|---|---|
| Update | [resource]_update_request |
All properties except the non-updatable and read-only ones |
| Create | [resource]_create_request |
Update schema + non-updatable fields + marking required fields |
| Response | [resource]_response |
All fields for the resource, including read-only fields (such as audit fields), with all non-nullable fields marked as required |
Sometimes, there is no create operation for the resource. In such cases, we simply do not generate the Create schema, so that the OpenAPI linter does not reject our generated OpenAPI specification because of unused schemas. We still generally keep the base structure with Update and Create data so the generation is more uniform across all resources.
