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

Related rules

Further reading

Last updated on View as Markdown
Was this helpful?