You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/oas.md
+14-4Lines changed: 14 additions & 4 deletions
Original file line number
Diff line number
Diff line change
@@ -169,12 +169,22 @@ The [schema](#schema) exposes two types of fields: _fixed fields_, which have a
169
169
170
170
Patterned fields MUST have unique names within the containing object.
171
171
172
-
In order to preserve the ability to round-trip between YAML and JSON formats, YAML version [1.2](https://yaml.org/spec/1.2/spec.html) is RECOMMENDED along with some additional constraints:
172
+
**Note:** While APIs may be described by OpenAPI Descriptions in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML.
173
173
174
-
* Tags MUST be limited to those allowed by [YAML's JSON schema ruleset](https://yaml.org/spec/1.2/spec.html#id2803231), which defines a subset of the YAML syntax and is unrelated to [[JSON-Schema-2020-12|JSON Schema]].
175
-
* Keys used in YAML maps MUST be limited to a scalar string, as defined by the [YAML Failsafe schema ruleset](https://yaml.org/spec/1.2/spec.html#id2802346).
174
+
##### JSON and YAML Compatibility
176
175
177
-
**Note:** While APIs may be described by OpenAPI Descriptions in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML.
176
+
In order to preserve the ability to round-trip between YAML and JSON formats, YAML version [1.2](https://yaml.org/spec/1.2/spec.html) is RECOMMENDED along with the additional constraints listed in [[!RFC9512]][Section 3.4](https://www.rfc-editor.org/rfc/rfc9512.html#name-yaml-and-json).
177
+
178
+
Previous versions of this specification expressed this requirement in terms of [YAML's JSON schema ruleset](https://yaml.org/spec/1.2/spec.html#id2803231), which defines a subset of the YAML syntax and is unrelated to [[JSON-Schema-2020-12|JSON Schema]].
179
+
Despite its name, this ruleset supports features that are not part of JSON, such as distinguishing between integers and floats (see [Data Types](#data-types)) or supporting `!!float .nan` as a value.
180
+
OAD authors SHOULD NOT rely on any YAML features supported by YAML's JSON schema ruleset that are listed as having interoperability challenges in RFC9512.
181
+
182
+
#### Character Encoding
183
+
184
+
Note that as stated in [[RFC8259|JSON]][Section 8.1](https://www.rfc-editor.org/rfc/rfc8259.html#section-8.1), only JSON encoded using UTF-8 is interoperable, which is extended to JSON-compatible YAML in [[!RFC9512]][Section 3.4](https://www.rfc-editor.org/rfc/rfc9512.html#name-yaml-and-json).
185
+
186
+
This specification assumes that all OADs are encoded using UTF-8.
187
+
If an implementation chooses to support additional character encodings, the behavior of any feature relying on the assumption of UTF-8 encoding is implementation-defined.
0 commit comments