Merge pull request #4053 from handrews/format-304

Port format / integer changes from 3.1.1

Author: ralfhandl

versions/3.0.4.md

@@ -176,32 +176,37 @@ Note that no aspect of implicit connection resolution changes how [URLs are reso
 
 ### Data Types
 
-Data types in the OAS are based on the types supported by the [JSON Schema Specification Wright Draft 00](https://tools.ietf.org/html/draft-wright-json-schema-00#section-4.2).
-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 type (see [`nullable`](#schema-nullable) for an alternative solution).
-Models are defined using the [Schema Object](#schema-object), which is an extended subset of JSON Schema Specification Wright Draft 00.
+Data types in the OAS are based on the non-`null` types supported by the [JSON Schema Validation Specification Draft Wright-00](https://datatracker.ietf.org/doc/html/draft-wright-json-schema-validation-00#autoid-32):
+"boolean", "object", "array", "number", "string", or "integer".
+See [`nullable`](#schema-nullable) for an alternative solution to "null" as a type.
+Models are defined using the [Schema Object](#schema-object), which is an extended subset of JSON Schema Specification Draft Wright-00.
 
-<a name="data-type-format"></a>Data types can have an optional modifier keyword: `format`.
-OAS uses several known formats to define in fine detail the data type being used.
-However, to support documentation needs, the `format` keyword is open `string`-valued and can have any value.
-Formats such as `"email"`, `"uuid"`, and so on, MAY be used even though they are not defined by this specification.
-The OpenAPI Initiative also hosts a [Format Registry](https://spec.openapis.org/registry/format/) for formats defined by OAS users and other specifications. Support for any registered format is strictly OPTIONAL, and support for one registered format does not imply support for any others.
+JSON Schema keywords and `format` values operate on JSON "instances" which may be one of the six JSON data types, "null", "boolean", "object", "array", "number", or "string", with certain keywords and formats [only applying to a specific type](https://datatracker.ietf.org/doc/html/draft-wright-json-schema-validation-00#section-4.1).  For example, the `pattern` keyword and the `date-time` format only apply to strings, and treat any instance of the other five types as _automatically valid._  This means JSON Schema keywords and formats do **NOT** implicitly require the expected type.  Use the `type` keyword to explicitly constrain the type. 
 
-Types that are not accompanied by a `format` keyword 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.
+Note that the `type` keyword allows `"integer"` as a value for convenience, but keyword and format applicability does not recognize integers as being of a distinct JSON type from other numbers because [[RFC7159|JSON]] itself does not make that distinction.  Since there is no distinct JSON integer type, JSON Schema defines integers mathematically.  This means that both `1` and `1.0` are [equivalent](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-4.2.2), and are both considered to be integers.
+
+#### Data Type Format
+
+As defined by the [JSON Schema Validation specification](https://datatracker.ietf.org/doc/html/draft-wright-json-schema-validation-00#section-7.3), data types can have an optional modifier keyword: `format`. As described in that specification, `format` is treated as a non-validating annotation by default; the ability to validate `format` varies across implementations.
+
+The OpenAPI Initiative also hosts a [Format Registry](https://spec.openapis.org/registry/format/) for formats defined by OAS users and other specifications. Support for any registered format is strictly OPTIONAL, and support for one registered format does not imply support for any others. 
+
+Types that are not accompanied by a `format` keyword 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. 
+For the purpose of [JSON Schema validation](https://datatracker.ietf.org/doc/html/draft-wright-json-schema-validation-00#section-7.1), each format should specify the set of JSON data types for which it applies. In this registry, these types are shown in the "JSON Data Type" column.
 
 The formats defined by the OAS are:
 
-| [`type`](#data-types) | [`format`](#data-type-format) | Comments                                                                                  |
-| -------------------- | --------------------------- | ----------------------------------------------------------------------------------------- |
-| `integer`            | `int32`                     | signed 32 bits                                                                            |
-| `integer`            | `int64`                     | signed 64 bits (a.k.a long)                                                               |
-| `number`             | `float`                     |                                                                                           |
-| `number`             | `double`                    |                                                                                           |
-| `string`             | `byte`                      | base64 encoded characters - [RFC4648](https://www.rfc-editor.org/rfc/rfc4648#section-4)   |
-| `string`             | `binary`                    | any sequence of octets                                                                    |
-| `string`             | `date`                      | As defined by `full-date` - [RFC3339](https://www.rfc-editor.org/rfc/rfc3339#section-5.6) |
-| `string`             | `date-time`                 | As defined by `date-time` - [RFC3339](https://www.rfc-editor.org/rfc/rfc3339#section-5.6) |
-| `string`             | `password`                  | A hint to obscure the value.                                                              |
+| `format`    | JSON Data Type | Comments                     |
+| ----------- | -------------- | ---------------------------- |
+| `int32`     | number         | signed 32 bits               |
+| `int64`     | number         | signed 64 bits (a.k.a long)  |
+| `float`     | number         |                              |
+| `double`    | number         |                              |
+| `byte`      | string         | base64 encoded characters - [RFC4648](https://www.rfc-editor.org/rfc/rfc4648#section-4) |
+| `binary`    | string         | any sequence of octets       |
+| `date`      | string         | As defined by `full-date` - [RFC3339](https://www.rfc-editor.org/rfc/rfc3339#section-5.6) |
+| `date-time` | string         | As defined by `date-time` - [RFC3339](https://www.rfc-editor.org/rfc/rfc3339#section-5.6) |
+| `password`  | string         | A hint to obscure the value. |
 
 #### Working with Binary Data