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 datafor any other property, often a payload field written next todata;The data of a server-sent event is text: give it type string and describe its JSON with contentMediaType and contentSchemawhendatais an object or an array;The item schema of text/event-stream describes an event: an object with the fields data, event, id and retrywhen 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