operation-document-not-primitive

Since 0.0.1 · In the rulesets: Strict at warning, All at warning

This rule checks that every request body and response body is an object or an array, not a string, a number or a boolean.

Rule details

A primitive body cannot grow: a response that is a bare string has nowhere to put a second field when one is needed, so the change breaks every client. An object or an array names what it holds, takes new fields without a new version, and leaves room for an error shape next to the data.

The rule looks at the schema of every media type of a request body or a response and reports Operation request or response body is not an object or array when the schema is missing or has neither object nor array among its types. The rule is in the strict and all rulesets.

Examples

Good. The body is an array of users.

paths:
  /users:
    get:
      responses:
        "200":
          description: A list of users.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"

Bad. A string: a name, a message, or both?

paths:
  /users:
    get:
      responses:
        "200":
          description: A list of users.
          content:
            application/json:
              schema:
                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:
      operation-document-not-primitive: off
Was this helpful?