patch-request-body-partial
Since 0.9.0 · In the rulesets: Strict at error, All at error
This rule checks that PATCH request bodies do not require properties.
Rule details
PATCH applies a partial modification to a resource (RFC 5789). With a merge patch
(RFC 7396) the client sends only the properties to change, so none of them should be
required. A PATCH body with required properties forces clients to resend values they do
not want to change, which is what PUT is for.
The rule checks object schemas of PATCH request bodies, including the properties
required by their allOf members. application/json-patch+json bodies are skipped: they
are arrays of operations, whose properties are rightly required. The rule reports
PATCH request body requires ...; partial updates should not require properties.
Many APIs use PATCH for an update whose only field is required, such as the body of a comment:
list those properties in allowedRequired, or turn the rule off when PATCH does not mean a
partial update in your API.
Configuration
An object with one optional property:
allowedRequired: names of properties which may be required, for example a version used for optimistic locking. Defaults to none.
commands:
lint:
rules:
patch-request-body-partial:
- warning
- allowedRequired: [version]
Examples
Good. Every property is optional.
paths:
/users/{id}:
patch:
requestBody:
content:
application/merge-patch+json:
schema:
type: object
properties:
name:
type: string
email:
type: string
Bad. Clients must send name even to change only email.
paths:
/users/{id}:
patch:
requestBody:
content:
application/json:
schema:
type: object
required: [name]
properties:
name:
type: string
email:
type: string
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:
patch-request-body-partial: off