Merge pull request OAI#1154 from krishahn/edit-filestruc-datatypes

edit-filestruc-datatypes

Author: RobDolinMS

versions/3.0.md

@@ -124,7 +124,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`.
 
 ### <a name="dataTypes"></a>Data Types
 
@@ -134,10 +134,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.
 
 <a name="dataTypeFormat"></a>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:
 
@@ -154,7 +154,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.
 
 ### <a name="richText"></a>Rich Text Formatting
 Throughout the specification `description` fields are noted as supporting CommonMark markdown formatting.