The API specification includes a reusable Page schema as a wrapper for the response of several endpoints e.g. GET /services.
Page defines a number of properties but none of them are required. This means that from a schema validation perspective, an empty response i.e. { } is valid. I don't believe that this is the desired behaviour, because Page also includes the empty parameter which is a boolean to indicate if the result set is empty.
I think that Page.empty should be made a required attribute of Page, so that responses MUST include it even if it is just informing the user that the result set is empty.
I think that we can make an argument that this is a PATCH upgrade which corrects an oversight/bug from when the spec was originally implemented. It is otherwise a MAJOR upgrade since, strictly speaking, it breaks backwards compatibility. I think that the fact an empty result passes schema validation is enough of a justification that this is a bug when implemented in a validator workflow, that this should be classed as a PATCH, but others may have other opinions.
The fix is simple, add the following to the bottom of the Page schema in the openapi.json file components/schemas/Page:
The API specification includes a reusable
Pageschema as a wrapper for the response of several endpoints e.g.GET /services.Pagedefines a number of properties but none of them are required. This means that from a schema validation perspective, an empty response i.e.{ }is valid. I don't believe that this is the desired behaviour, becausePagealso includes theemptyparameter which is a boolean to indicate if the result set is empty.I think that
Page.emptyshould be made a required attribute ofPage, so that responses MUST include it even if it is just informing the user that the result set is empty.I think that we can make an argument that this is a PATCH upgrade which corrects an oversight/bug from when the spec was originally implemented. It is otherwise a MAJOR upgrade since, strictly speaking, it breaks backwards compatibility. I think that the fact an empty result passes schema validation is enough of a justification that this is a bug when implemented in a validator workflow, that this should be classed as a PATCH, but others may have other opinions.
The fix is simple, add the following to the bottom of the
Pageschema in the openapi.json filecomponents/schemas/Page: