diff --git a/versions/3.0.md b/versions/3.0.md index 2969ea65c5..1a8414c23a 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -96,8 +96,7 @@ The available status codes are defined by [RFC7231](http://tools.ietf.org/html/r ### Format -The files describing the RESTful API in accordance with this 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 an OAS file. +An API description that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format. For example, if a field has an array value, the JSON array representation will be used: @@ -106,19 +105,18 @@ For example, if a field has an array value, the JSON array representation will b "field": [...] } ``` - -While the API is described using JSON, it does not impose a JSON input/output to the API itself. - 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. +Patterned fields MUST have unique names within the containing object. 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](http://yaml.org/spec/1.2/spec.html#id2802346) +- 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](http://yaml.org/spec/1.2/spec.html#id2802346). + +**Note:** While APIs are described by OpenAPI documents in YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML. ### File Structure