Merge pull request #635 from OAI/issue-575

clarification about YAML

Author: fehguy

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.