rough rough rough WIP

versions/3.1.0.md

@@ -2276,11 +2276,16 @@ This object is an extended subset of the [JSON Schema Specification Wright Draft
 For more information about the properties, see [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.
 
-##### Properties 
+##### Properties
 
-The following properties are taken directly from the JSON Schema definition and follow the same specifications:
+OpenAPI v3.1 is a JSON Schema vocabulary which eetends JSON Schema Core and Validation vocabularies. As such any keyword available for those vocabularies is by definition available in OpenAPI, and will work the exact same way, including but not limited to:
 
 - title
+- type
+- required
+- allOf
+- oneOf
+- andOf
 - multipleOf
 - maximum
 - exclusiveMaximum
@@ -2294,46 +2299,50 @@ The following properties are taken directly from the JSON Schema definition and
 - uniqueItems
 - maxProperties
 - minProperties
-- required
 - enum
-
-The following properties are taken from the JSON Schema definition but their definitions were adjusted to the OpenAPI Specification. 
-- type - Value MUST be a string. Multiple types via an array are not supported.
-- allOf - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema.
-- 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 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. Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. Consistent with JSON Schema, `additionalProperties` defaults to `true`.
+- propertyNames
+- contains
+- const
+- examples
+- if / then / else
+- dependentRequired / dependentSchemas
+- deprecated
+- additionalItems
+- additionalProperties
+- unevaluatedItems
+- unevaluatedProperties
+- maxContains
+- minContains
+- readOnly
+- writeOnly
+
+The following properties are taken from the JSON Schema definition but their definitions were adjusted to the OpenAPI Specification.
+
+- exclusiveMinimum - Value can be a numeric value just like JSON Schema, or for backwards compatibility with older drafts it can accept a boolean to act as a modifier to the `minimum` keyword. The numeric value usage is recommended.
+- exclusiveMaximum - Value can be a numeric value just like JSON Schema, or for backwards compatibility with older drafts it can accept a boolean to act as a modifier to the `minimum` keyword. The numeric value usage is recommended.
 - description - [CommonMark syntax](http://spec.commonmark.org/) MAY 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 - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, if `type` is `string`, then `default` can be `"foo"` but cannot be `1`.
+- default - The value MUST conform to the defined type for the Schema Object defined at the same level. For example, if `type` is `string`, then `default` can be `"foo"` but cannot be `1`. This differs from JSON Schema which only RECOMMENDS the default conforms to the schema.
 
 Alternatively, any time a Schema Object can be used, a [Reference Object](#referenceObject) can be used in its place. This allows referencing definitions instead of defining them inline.
 
-Additional properties defined by the JSON Schema specification that are not mentioned here are strictly unsupported.
-
-Other than the JSON Schema subset fields, the following fields MAY be used for further schema documentation:
+In addition to the JSON Schema fields, the following OpenAPI vocabulary fields MAY be used for further schema documentation:
 
 ##### Fixed Fields
 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="schemaNullable"></a>nullable | `boolean` | Allows sending a `null` value for the defined schema. Default value is `false`. Deprecated. Move towards using `"type": "null"` & type arrays , e.g: `"type": ["string", "null"]`.
 <a name="schemaDiscriminator"></a>discriminator | [Discriminator Object](#discriminatorObject) | Adds support for polymorphism. The discriminator is an object name that is used to differentiate between other schemas which may satisfy the payload description. 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 SHOULD NOT be sent as part of the request. If the 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". Therefore, it MAY be sent as part of a request but SHOULD NOT be sent as part of the response. If the 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 of this property.
-<a name="schemaExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema. 
+<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. To represent examples that cannot be naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary.
-<a name="schemaDeprecated"></a> deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is `false`.
 
 This object MAY be extended with [Specification Extensions](#specificationExtensions).
 
 ###### <a name="schemaComposition"></a>Composition and Inheritance (Polymorphism)
 
 The OpenAPI Specification allows combining and extending model definitions using the `allOf` property of JSON Schema, in effect offering model composition.
-`allOf` takes an array of object definitions that are validated *independently* but together compose a single object. 
+`allOf` takes an array of object definitions that are validated *independently* but together compose a single object.
 
 While composition offers model extensibility, it does not imply a hierarchy between the models.
 To support polymorphism, the OpenAPI Specification adds the `discriminator` field.