# media-type-item-schema

Source: https://api-genie.dev/docs/linter/openapi/rules/media-type-item-schema

A rule of the OpenAPI linter, which reads OpenAPI 3.0, 3.1 and 3.2 documents. 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](/docs/reference/server/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**.

```yaml
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.

```yaml
paths:
  /orders/export:
    get:
      responses:
        "200":
          description: One order per line
          content:
            application/jsonl:
              schema:
                $ref: "#/components/schemas/Order"
```
