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

Related rules

Further reading

Was this helpful?