event-stream-item-schema

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.

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.

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

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:
      event-stream-item-schema: off

Related rules

Further reading

Last updated on View as Markdown
Was this helpful?