schema-no-optional-nullable-properties
Since 0.9.0 · In the rulesets: Recommended at warning, Strict at error, All at error
This rule disallows schema properties that are both optional and nullable.
Rule details
An optional nullable property represents an absent value in two ways: the property
may be omitted, or it may be present with the value null. Requiring a property
to be nullable or allowing it to be omitted makes the API contract unambiguous.
A property is nullable when its schema, or the schema it references, allows null:
- a
nulltype, e.g.type: [string, 'null']; nullable: truein OpenAPI 3.0 documents;nullinenumor asconst;- an
anyOforoneOfbranch allowingnull, e.g.anyOf: [{$ref: ...}, {type: 'null'}]; - an
allOfwhose every member allowsnull.
A property counts as required when the schema, one of its allOf members, or a schema
using it in allOf lists it in required.
In PATCH request bodies and application/merge-patch+json documents, null means
“remove this value” (RFC 7396), so optional nullable properties are expected there and
the rule skips them and every schema they contain. Turn the rule off when omission and an
explicit null mean two different things in your API.
Configuration
An object with one optional property:
ignorePatchBodies: skip the schemas ofPATCHrequest bodies and merge-patch documents. Defaults totrue.
commands:
lint:
rules:
schema-no-optional-nullable-properties:
- warning
- ignorePatchBodies: false
Examples
Good. The nullable property is required.
components:
schemas:
User:
type: object
required: [middleName]
properties:
middleName:
type: [string, 'null']
Good. The optional property cannot be null.
components:
schemas:
User:
type: object
properties:
middleName:
type: string
Bad. middleName can be omitted or set to null.
components:
schemas:
User:
type: object
properties:
middleName:
type: [string, 'null']
Turn it off or change its severity
In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.rules has the details.
commands:
lint:
rules:
schema-no-optional-nullable-properties: off