The specification should be upgraded to OpenAPI 3.2.0 to take advantage of new streaming place holders

The API surface supports stream across multiple operations (~8 in total as of writing). Using the new semantics introduced by OpenAPI 3.2.0 would be beneficial as it'd enable client code and documentation generation. But that would also clean up the content of the description itself, making it more meaningful semantically.

We should be using the item schema property and not the schema one. This is because of the stream nature, and the fact that streams DO NOT contain the "array information" (the [ and ] in JSON).

The special considerations section will be interesting for any implementation work. So will this full example of how to correctly represent text event streams according to the latest version of the specification.

I hope this helps! Let me know if you have any additional comments or questions

Start by reviewing the roughly eight API operations that support streams and compare their current descriptions with the OpenAPI 3.2.0 item schema and server-sent event guidance linked in the issue. Done means the specification uses the item property rather than schema for stream responses and consistently represents the streams according to the 3.2.0 semantics.