media-type-item-schema
Since 0.13.0 · In the rulesets: Recommended at warning, Strict at error, All at error
This rule checks that a request body or response sent as a stream describes each item with
itemSchema (x-itemSchema in OpenAPI 3.0 and 3.1).
Rule details
The streams are server-sent events (text/event-stream), JSON Lines and JSON text sequences.
JSON Lines are application/jsonl, application/jsonlines,
application/x-jsonlines, application/ndjson, application/x-ndjson and types ending in
+jsonl. JSON text sequences are application/json-seq. The rule does not check
application/geo+json-seq or multipart/mixed, which OpenAPI 3.2 also lists as sequential.
schema applies to the whole body, read as an array of its items, so a client can check it only
once the stream has ended. itemSchema, new in OpenAPI 3.2, applies to each item as it arrives.
API Genie’s generators, mock and doc components read it.
The rule reports ... is a stream: describe each item with itemSchema instead of the whole body with schema when the media type has a schema, and ... is a stream: describe each item with itemSchema when it has neither. In OpenAPI 3.0 and 3.1 documents the messages name
x-itemSchema.
A media type with both schema and itemSchema passes, so a document can keep schema for tools
that read only it. With both, apigenie-server answers from schema, not item by item
(Responses). A media type whose $ref does not lead to an
entry of components/mediaTypes in the same document is skipped, such as one to another file. The
rule can’t see what it holds.
Turn the rule off when clients read the whole stream before they use it. A short export described
by schema as an array with items is one.
Examples
Good.
paths:
/orders/export:
get:
responses:
"200":
description: One order per line
content:
application/jsonl:
itemSchema:
$ref: "#/components/schemas/Order"
Bad. schema describes the whole stream as one order.
paths:
/orders/export:
get:
responses:
"200":
description: One order per line
content:
application/jsonl:
schema:
$ref: "#/components/schemas/Order"
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:
media-type-item-schema: off