# event-stream-item-schema

Source: https://api-genie.dev/docs/linter/openapi/rules/event-stream-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 the `itemSchema` of `text/event-stream` (`x-itemSchema` in OpenAPI 3.0 and
3.1) describes a server-sent event.

## Rule details

Each item of a server-sent event stream is an event, and an event has only four fields: `data`,
`event`, `id` and `retry`. The payload travels as the text of `data`; a JSON payload is that text,
parsed. OpenAPI 3.2 describes that JSON with `contentMediaType` and `contentSchema` on `data`. API
Genie's generators read it from `data` in the item schema's own `properties`. The mock also finds
it in `allOf`, and in the `oneOf` or `anyOf` branch whose `event` is the generated event's.

The rule looks at the properties of the item schema and of its `allOf`, `anyOf` and `oneOf`
branches, following `$ref` within the document; in OpenAPI 3.1 and 3.2 it also reads the keywords
written beside a `$ref`. It reports the properties of a schema shared by several streams once. It
reports:

- `... is not a field of a server-sent event (data, event, id, retry); put the payload in data`
  for any other property, often a payload field written next to `data`;
- `The data of a server-sent event is text: give it type string and describe its JSON with
  contentMediaType and contentSchema` when `data` is an object or an array;
- `The item schema of text/event-stream describes an event: an object with the fields data,
  event, id and retry` when no branch has any property.

Without an item schema the rule reports nothing; `media-type-item-schema` reports that case. In
OpenAPI 3.0, `contentMediaType` and `contentSchema` are not keywords of the Schema Object; API
Genie's generators and mock read them inside `x-itemSchema` all the same. Turn the rule off while
the document's clients read `itemSchema` as the parsed payload of `data` rather than as the event.

## Examples

**Good**. Each event is a `delta` or a `done`, with a JSON payload in `data`.

```yaml
paths:
  /chat:
    post:
      responses:
        "200":
          description: The answer, as it is written
          content:
            text/event-stream:
              itemSchema:
                type: object
                required: [data]
                properties:
                  event:
                    enum: [delta, done]
                  data:
                    type: string
                    contentMediaType: application/json
                    contentSchema:
                      $ref: "#/components/schemas/Delta"
                  id:
                    type: string
```

**Bad**. The payload's field `text` stands next to `data`, and `data` is an object.

```yaml
paths:
  /chat:
    post:
      responses:
        "200":
          description: The answer, as it is written
          content:
            text/event-stream:
              itemSchema:
                type: object
                properties:
                  text:
                    type: string
                  data:
                    type: object
```
