diff --git a/versions/3.0.md b/versions/3.0.md index 2969ea65c5..ce9d8c81ba 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -126,7 +126,7 @@ 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. -By convention, it is RECOMMENDED that the OpenAPI Specification (OAS) file be named `openapi.json` or `openapi.yaml`. +It is RECOMMENDED that the OpenAPI definition file be named following convention: `openapi.json` or `openapi.yaml`. ### Data Types @@ -136,10 +136,10 @@ Note that `integer` as a type is also supported and is defined as a JSON number Models are described using the [Schema Object](#schemaObject) which is an extended subset of JSON Schema Specification Wright Draft 00. Primitives have an optional modifier property: `format`. -OAS uses several known formats to more finely define the data type being used. -However, the `format` property is an open `string`-valued property, and can have any value to support documentation needs. -Formats such as `"email"`, `"uuid"`, etc., can be used even though they are not defined by this specification. -Types that are not accompanied by a `format` property follow their definition from the JSON Schema. Tools that do not recognize a specific `format` MAY default back to the `type` alone, as if the `format` was not specified. +OAS uses several known formats to define in fine detail the data type being used. +However, to support documentation needs, the `format` property is an open `string`-valued property, and can have any value. +Formats such as `"email"`, `"uuid"`, and so on, can be used even though undefined by this specification. +Types that are not accompanied by a `format` property follow the type definition in the JSON Schema. Tools that do not recognize a specific `format` MAY default back to the `type` alone, as if the `format` is not specified. The formats defined by the OAS are: @@ -156,7 +156,7 @@ binary | `string` | `binary` | any sequence of octets boolean | `boolean` | | | date | `string` | `date` | As defined by `full-date` - [RFC3339](http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14) dateTime | `string` | `date-time` | As defined by `date-time` - [RFC3339](http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14) -password | `string` | `password` | Used to hint UIs the input needs to be obscured. +password | `string` | `password` | A hint to UIs to obscure input. ### Rich Text Formatting Throughout the specification `description` fields are noted as supporting CommonMark markdown formatting.