Skip to content

Commit 18a125b

Browse files
committed
Add section on JSON-compatible data formats
1 parent 39af4a7 commit 18a125b

1 file changed

Lines changed: 10 additions & 0 deletions

File tree

src/oas.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3063,6 +3063,16 @@ properties:
30633063
Some applications might leave the string as a string regardless of programming language, while others might notice the `format` and use it as a `datetime.datetime` instance in Python, or a `java.time.ZonedDateTime` in Java.
30643064
This specification only requires that the data is valid according to the schema, and that [annotations](#extended-validation-with-annotations) such as `format` are available in accordance with the JSON Schema specification.
30653065

3066+
##### JSON-Compatible Data
3067+
3068+
Some media types are more-or-less compatible with JSON, in which case their JSON-compatible subsets can be modeled the same way as JSON. Some examples include:
3069+
3070+
* `text/toon`, which is an alternate encoding format for the JSON data model, although with some constraints such as object property ordering that are not defined by JSON
3071+
* `application/toml`, which is mostly an alternate encoding for a subset of JSON data structures, but also distinguishes between integers and floats in a way that JSON and JSON Schema do not
3072+
* `application/yaml`, which has much more functionality than JSON, but provides guidance on JSON compatibility in [[RFC9512]] [Section 3.4](https://www.rfc-editor.org/rfc/rfc9512.html#section-3.4)
3073+
3074+
In many cases, modeling these media types as if they were JSON will suffice, but care must be taken in areas where the specifications diverge. See the [OpenAPI Media Type Registry](#openapi-media-type-registry) for guidance on specific JSON-like data formats.
3075+
30663076
##### Non-JSON Data
30673077

30683078
Non-JSON serializations can be substantially different from their corresponding data form, and might require several steps to parse.

0 commit comments

Comments
 (0)