From 34d1aec817ee3422bf7737235892f337e1b2fc5a Mon Sep 17 00:00:00 2001 From: Kristine Hahn Date: Wed, 7 Jun 2017 05:27:06 -0700 Subject: [PATCH 1/4] plain language edits --- 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 2969ea65c5..f487d581a5 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -96,8 +96,8 @@ 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. +The files describing the RESTful API in accordance with this specification consist of JSON objects and conform to the JSON standards. An OAS file written in +YAML, a superset of JSON, also complies with this specification. For example, if a field has an array value, the JSON array representation will be used: @@ -107,18 +107,18 @@ For example, if a field has an array value, the JSON array representation will b } ``` -While the API is described using JSON, it does not impose a JSON input/output to the API itself. +While the API is described using JSON, input to and output from the API is not required to be JSON. 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. +Multiple occurrences of patterned fields need to have unique names. 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). ### File Structure From 557c6db6cad55de2c36982e433d970330d9fdd7a Mon Sep 17 00:00:00 2001 From: Kristine Hahn Date: Thu, 8 Jun 2017 16:35:24 -0700 Subject: [PATCH 2/4] DavidBiesack's changes --- versions/3.0.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index f487d581a5..69fa61e3a2 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -106,20 +106,19 @@ For example, if a field has an array value, the JSON array representation will b "field": [...] } ``` - -While the API is described using JSON, input to and output from the API is not required to be JSON. - 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. -Multiple occurrences of patterned fields need to have unique names. +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). +**Note:** While APIs are described with JSON or YAML Open API documents, the API request and response bodies and other content are not required to be JSON or YAML. + ### File Structure The OAS representation of the API is made of a single file. From 2269858809d8e0bb80fa72b922ffe5839e997e3c Mon Sep 17 00:00:00 2001 From: Kristine Hahn Date: Thu, 8 Jun 2017 17:00:12 -0700 Subject: [PATCH 3/4] earth2marsh change --- 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 69fa61e3a2..2ed15baac8 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -117,7 +117,7 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA - 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 with JSON or YAML Open API documents, the API request and response bodies and other content are not required to be JSON or YAML. +**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 From 82be76e05f89cef207c3b40bce1f4c69c8b439cf Mon Sep 17 00:00:00 2001 From: Kristine Hahn Date: Fri, 9 Jun 2017 06:34:48 -0700 Subject: [PATCH 4/4] agreed upon wording of an API description definition --- versions/3.0.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 2ed15baac8..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 consist of JSON objects and conform to the JSON standards. An OAS file written in -YAML, a superset of JSON, also complies with this specification. +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: