From bc59244cf3edfe517c34881c67cc280e116a710d Mon Sep 17 00:00:00 2001 From: Tony Tam Date: Fri, 8 Apr 2016 06:14:53 -0700 Subject: [PATCH 1/3] clarification about YAML --- versions/3.0.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/versions/3.0.md b/versions/3.0.md index 1d6a2d02a9..32d8e1f289 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -51,7 +51,12 @@ 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 YAML, version `1.1` is supported for OAS documents. + +As YAML has a superset of features, the following YAML features are NOT supported by the OAS: + +* YAML Merge. Consider using JSON Pointers instead +* Numeric keys. All numeric keys should be quoted For example, if a field is said to have an array value, the JSON array representation will be used: From 5e74e77763b2a65edc34a138b0f3baed6220e71f Mon Sep 17 00:00:00 2001 From: Darrel Date: Mon, 23 May 2016 10:29:56 -0400 Subject: [PATCH 2/3] Updated YAML constraints --- versions/3.0.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 32d8e1f289..69f0197bcf 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -51,12 +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. For YAML, version `1.1` is supported for OAS documents. - -As YAML has a superset of features, the following YAML features are NOT supported by the OAS: - -* YAML Merge. Consider using JSON Pointers instead -* Numeric keys. All numeric keys should be quoted +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: @@ -72,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 scalars defined by the JSON 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. From 3720cb42dd4cc4663979fcdbf3826bd5d7adea89 Mon Sep 17 00:00:00 2001 From: Darrel Date: Mon, 23 May 2016 12:48:02 -0400 Subject: [PATCH 3/3] Limited YAML map keys to strings --- versions/3.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.md b/versions/3.0.md index 69f0197bcf..e089d1ecde 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -70,7 +70,7 @@ The schema exposes two types of fields. Fixed fields, which have a declared 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 scalars defined by the JSON schema ruleset +- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset ### File Structure