Linter rulesOpenAPIpatch-request-body-partial

patch-request-body-partial

Since 0.9.0

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.

Configuration

This rule accepts an object with the following options:

  • 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.

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

When Not to Use It

Many APIs use PATCH for an update whose only field is required, such as the body of a comment. Disable the rule, or list those properties in allowedRequired, when PATCH does not mean a partial update in your API.

Compatibility

This rule is compatible with all OpenAPI 3.x versions.

Related rules

Further reading