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