Merge pull request #4045 from handrews/format

Clarify data model types and formats

Author: ralfhandl

versions/3.1.1.md

@@ -199,25 +199,35 @@ Note that no aspect of implicit connection resolution changes how [URIs are reso
 
 ### Data Types
 
-Data types in the OAS are based on the types supported by the [JSON Schema Specification Draft 2020-12](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-4.2.1).
-Note that `integer` as a type is also supported and is defined as a JSON number without a fraction or exponent part.
-Models are defined using the [Schema Object](#schema-object), which is a superset of JSON Schema Specification Draft 2020-12.
+Data types in the OAS are based on the types defined by the [JSON Schema Validation Specification Draft 2020-12](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00#section-6.1.1):
+"null", "boolean", "object", "array", "number", "string", or "integer".
+Models are defined using the [Schema Object](#schema-object), which is a superset of the JSON Schema Specification Draft 2020-12.
 
-<a name="data-type-format"></a>As defined by the [JSON Schema Validation specification](https://tools.ietf.org/html/draft-bhutton-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.
+
+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.  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.
+
+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://tools.ietf.org/html/draft-bhutton-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-bhutton-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`             | `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         |                              |
+| `password` | string         | A hint to obscure the value. |
+
+As noted under [Data Type](#data-types), both `type: number` and `type: integer` are considered to be numbers in the data model.
 
 #### Working With Binary Data