From e9cff3e7e6990306897a1409125a6d998d962ba8 Mon Sep 17 00:00:00 2001
From: "Henry H. Andrews" <andrews_henry@yahoo.com>
Date: Sun, 21 Apr 2024 12:46:01 -0700
Subject: [PATCH] Support streaming JSON formats such as json-seq

These formats can easily be modeled as if they were JSON arrays,
with fairly minimal new tooling requirements.
---
 versions/3.2.0.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)

diff --git a/versions/3.2.0.md b/versions/3.2.0.md
index fa620cb55e..2c2f3a42ee 100644
--- a/versions/3.2.0.md
+++ b/versions/3.2.0.md
@@ -2350,6 +2350,12 @@ There are two ways to define the value of a discriminator for an inheriting inst
 - Override the schema name by overriding the property with a new value. If a new value exists, this takes precedence over the schema name.
 As such, inline schema definitions, which do not have a given id, *cannot* be used in polymorphism.
 
+###### Streaming JSON
+
+Several media types, including but not limited to `application/json-seq` (defined in [RFC7464](https://datatracker.ietf.org/doc/html/rfc7464)), allow sending sequences of JSON documents separated by some sort of delimiter.  These formats can be modeled with [Schema Objects](#schemaObject) by treating the sequence as an array of JSON data.
+
+Since JSON Schema implementations do not support these formats directly, validating JSON streams requires either converting the stream to a single array document or manually applying the correct subschema(s) to each JSON document in the stream.  The latter approach is more suitable for indefinite-length streams where all documents (or all documents after a specific number of initial documents) are expected to be valid against the same subschema.
+
 ###### XML Modeling
 
 The [xml](#schemaXml) property allows extra definitions when translating the JSON definition to XML.
@@ -2693,6 +2699,79 @@ components:
         - packSize
 ```
 
+###### Modeling JSON Streams
+
+A stream consisting of a single metadata document followed
+by an indefinite number of data documents consisting of
+numeric measurements with units:
+
+```JSON
+"content": {
+  "application/json-seq": {
+    "schema": {
+      "type": "array",
+      "prefixItems": [{
+        "$comment": "Metadata for all subsequent data documents",
+        "type": "object",
+        "required": ["subject", "dateCollected"],
+        "properties": {
+          "subject": {
+            "type": "string",
+          },
+          "dateCollected": {
+            "type": "string",
+            "format": "date-time",
+          }
+        }
+      }],
+      "items": {
+        "$comment": "A JSON document holding data",
+        "type": "object",
+        "required": ["measurement", "unit"],
+        "properties": {
+          "measurement": {
+            "type": "number"
+          },
+          "unit": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+```YAML
+content:
+  application/json-seq:
+    schema:
+      type: array
+      prefixItems:
+      - $comment: Metadata for all subsequent data documents
+        type: object
+        required:
+        - subject
+        - dateCollected
+        properties:
+          subject:
+            type: string
+          dateCollected:
+            type: string
+            format: date-time
+      items:
+        $comment: A JSON document holding data
+        type: object
+        required:
+         - measurement
+         - unit
+        properties:
+          measurement:
+            type: number
+          unit:
+            type: string
+```
+
 #### <a name="discriminatorObject"></a>Discriminator Object
 
 When request bodies or response payloads may be one of a number of different schemas, a `discriminator` object can be used to aid in serialization, deserialization, and validation.  The discriminator is a specific object in a schema which is used to inform the consumer of the document of an alternative schema based on the value associated with it.