What "required" in OpenAPI really means
Given the following OpenAPI definition, which of the below objects are valid. Just 1. or 1. and 2 ..
Person:
required:
- id
type: object
properties:
id:
type: string
-
{"id": ""}
-
{"id": null}
-
{}
It boils down to the question of whether "required = true" means "nonzero value" or "property must be present".
The JSON schema validator at https://json-schema-validator.herokuapp.com/ says 2. is invalid because it null
does not satisfy the constraint.Note type: string
that it does not complain because it id
is null, but because null
it is not a string ... BUT, how important is this for OpenAPI / Swagger?
source to share
Keyword required
in OpenAPI has the same meaning as in JSON Schema :
required
An object instance is valid against this keyword if its property set contains all the elements in this key array.
The wording in the latest JSON Schema specification (although not the one used by OpenAPI) is clearer:
An instance of an object is valid against this keyword if each element of the array is the name of a property in the instance .
That is, it required
means that "the property must be present", regardless of the value. Values type
, format
etc. Property values are separate constraints that are evaluated separately from required
, but together as a combined schema.
In your example:
-
{"id": ""}
:- ✓ checks for
required
- ✓ the value is
""
checked fortype: string
- ✓ checks for
-
{"id": null}
IMPOSSIBLE:- ✓ checks for
required
- ✗
null
DOES NOT check compliancetype: string
- ✓ checks for
-
{}
IMPOSSIBLE:- ✗ DOES NOT check compliance
required
- ✗ DOES NOT check compliance
Note that null
as the type is not supported in OpenAPI, OpenAPI 3.0 adds an attribute nullable
to indicate what the value can be null
. So {"id": null}
this OpenAPI 3.0 schema will check:
Person: required: - id type: object properties: id: type: string nullable: true # <----
source to share
OpenAPI favors JSON Schema in these matters and from what I can tell in JSON Schema null is a valid string.
It should be noted that the null character (\ u0000) is valid in a JSON string.
My reading of the definition required is that having a property implies validity.
Update: I seem to be wrong. It seems that JSON Schema does not consider the value null
to be equivalent to \ u0000. This would mean that null is not a valid string value.
source to share