Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support streaming JSON formats such as json-seq #3735

Closed
wants to merge 1 commit into from
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 79 additions & 0 deletions versions/3.2.0.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down