diff --git a/versions/3.0.md b/versions/3.0.md index 1d6a2d02a9..e089d1ecde 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -51,7 +51,7 @@ The HTTP Status Codes are used to indicate the status of the executed operation. ### Format The files describing the RESTful API in accordance with the OpenAPI Specification are represented as JSON objects and conform to the JSON standards. YAML, being a superset of JSON, can be used as well to -represent a OAS (OpenAPI Specification) file. +represent a OAS (OpenAPI Specification) file. For example, if a field is said to have an array value, the JSON array representation will be used: @@ -67,6 +67,11 @@ All field names in the specification are **case sensitive**. The schema exposes two types of fields. Fixed fields, which have a declared name, and Patterned fields, which declare a regex pattern for the field name. Patterned fields can have multiple occurrences as long as each has a unique name. +In order to preserve the ability to round-trip between YAML and JSON formats, YAML version [1.2](http://www.yaml.org/spec/1.2/spec.html) is recommended along with some additional constraints: + +- Tags MUST be limited to those allowed by the [JSON Schema ruleset](http://www.yaml.org/spec/1.2/spec.html#id2803231) +- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset + ### File Structure The OAS representation of the API is made of a single file. However, parts of the definitions can be split into separate files, at the discretion of the user. This is applicable for `$ref` fields in the specification as follows from the [JSON Schema](http://json-schema.org) definitions.