MOAR updates

Author: webron

versions/3.0.md

@@ -144,14 +144,15 @@ By convention, the OpenAPI Specification (OAS) file is named `openapi.json` or `
 
 ### Data Types
 
-Primitive data types in the OAS are based on the types supported by the [JSON-Schema Draft 4](http://json-schema.org/latest/json-schema-core.html#anchor8).
-Models are described using the [Schema Object](#schemaObject) which is a subset of JSON Schema Draft 4.
+Primitive data types in the OAS are based on the types supported by the [JSON-Schema Draft Wright 00](https://tools.ietf.org/html/draft-wright-json-schema-00#section-4.2) (also known as, JSON Schema Draft 05). Note that `integer` as a type is also supported and is defined as a JSON number without a fraction or exponent part. `null` is not supported as a value.
+Models are described using the [Schema Object](#schemaObject) which is an extended subset of JSON Schema Draft 05.
 
 <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.
+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.
+
 The formats defined by the OAS are:
 
 
@@ -2214,8 +2215,8 @@ definitions:
 A simple object to allow referencing other definitions in the specification.
 It can be used to reference parameters and responses that are defined at the top level for reuse.
 
-The Reference Object is a [JSON Reference](http://tools.ietf.org/html/draft-pbryan-zyp-json-ref-02) that uses a [JSON Pointer](http://tools.ietf.org/html/rfc6901) as its value.
-For this specification, only [canonical dereferencing](http://json-schema.org/latest/json-schema-core.html#anchor27) is supported.
+The Reference Object is a [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) that uses a [JSON Pointer](http://tools.ietf.org/html/rfc6901) as its value.
+For this specification, only [External references](https://tools.ietf.org/html/draft-wright-json-schema-00#section-8.2.2) are supported ([Internal references](https://tools.ietf.org/html/draft-wright-json-schema-00#section-8.2.1) are not supported).
 
 ##### Fixed Fields
 Field Name | Type | Description
@@ -2260,9 +2261,9 @@ $ref: 'definitions.yaml#/Pet'
 
 The Schema Object allows the definition of input and output data types.
 These types can be objects, but also primitives and arrays.
-This object is an extended subset of the [JSON Schema Specification Draft 4](http://json-schema.org/).
+This object is an extended subset of the [JSON Schema Specification Wright Draft 00](http://json-schema.org/), also known as JSON Schema Draft 05.
 
-Further information about the properties can be found in [JSON Schema Core](http://json-schema.org/latest/json-schema-core.html) and [JSON Schema Validation](http://json-schema.org/latest/json-schema-validation.html).
+Further information about the properties can be found in [JSON Schema Core](https://tools.ietf.org/html/draft-wright-json-schema-00) and [JSON Schema Validation](https://tools.ietf.org/html/draft-wright-json-schema-validation-00).
 Unless stated otherwise, the property definitions follow the JSON Schema specification as referenced here.
 
 The following properties are taken directly from the JSON Schema definition and follow the same specifications:
@@ -2290,11 +2291,11 @@ The following properties are taken from the JSON Schema definition but their def
 - oneOf - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema.
 - anyOf - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema.
 - not - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema.
-- items - Value MUST be an object and not an array. Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. `items` MUST be present of the `type` is `array`.
+- items - Value MUST be an object and not an array. Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. `items` MUST be present if the `type` is `array`.
 - properties - Property definitions MUST be a [Schema Object](#schemaObject) and not a standard JSON Schema (inline or referenced).
 - additionalProperties - Value can be boolean or object. If object, definition MUST be a [Schema Object](#schemaObject) and not a standard JSON Schema (inline or referenced).
-- $ref - As a [Reference Object](#referenceObject).
-- description ([CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation).
+- $ref - A [Reference Object](#referenceObject).
+- description - [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation.
 - format - See [Data Type Formats](#dataTypeFormat) for further details. While relying on JSON Schema's defined formats, the OAS offers a few additional predefined formats.
 - default - Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object.
 
@@ -2307,8 +2308,8 @@ Field Name | Type | Description
 ---|:---:|---
 <a name="schemaNullable"></a>nullable | `boolean` | Allows sending a `null` value for the defined schema. Default value is `false`.
 <a name="schemaDiscriminator"></a>discriminator | `string` | Adds support for polymorphism. The discriminator is the schema property name that is used to differentiate between other schema that inherit this schema. The property name used MUST be defined at this schema and it MUST be in the `required` property list. When used, the value MUST be the name of this schema or any schema that inherits it. See [Composition and Inheritance](#schemaComposition) for more details.
-<a name="schemaReadOnly"></a>readOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "read only". This means that it MAY be sent as part of a response but MUST NOT be sent as part of the request. If property is marked as `readOnly` being `true` and is in the `required` list, the `required` will take effect on the response only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`.
-<a name="schemaWriteOnly"></a>writeOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "write only". This means that it MAY be sent as part of a request but MUST NOT be sent as part of the response. If property is marked as `writeOnly` being `true` and is in the `required` list, the `required` will take effect on the request only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`.
+<a name="schemaReadOnly"></a>readOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "read only". This means that it MAY be sent as part of a response but SHOULD NOT be sent as part of the request. If property is marked as `readOnly` being `true` and is in the `required` list, the `required` will take effect on the response only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`.
+<a name="schemaWriteOnly"></a>writeOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "write only". This means that it MAY be sent as part of a request but SHOULD NOT be sent as part of the response. If property is marked as `writeOnly` being `true` and is in the `required` list, the `required` will take effect on the request only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`.
 <a name="schemaXml"></a>xml | [XML Object](#xmlObject) | This MAY be used only on properties schemas. It has no effect on root schemas. Adds Additional metadata to describe the XML representation format of this property.
 <a name="schemaExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema. 
 <a name="schemaExample"></a>example | Any | A free-form property to include an example of an instance for this schema.