From 99b0fd81208413f3f62f4ac6435e2c04c60d0697 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Tue, 20 Aug 2024 14:08:39 -0700 Subject: [PATCH] Clarify data model types and formats --- versions/3.1.1.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index ca1ffda82b..1bb22eb5aa 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -199,10 +199,12 @@ 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 six types supported by the [JSON Schema Specification Draft 2020-12 data model](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-4.2.1): array, boolean, null, number, object, or string. JSON Schema keywords and `format` values operate on these six types, 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 type for convenience, but keyword and format applicability does not recognize integers as being distinct from other numbers because [[JSON]] itself does not make that distinction. JSON Schema defines integers [mathematically](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-6.3), meaning that both `1` and `1.0` are considered to be integers for the purpose of the `type` keyword. + 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 property: `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. @@ -211,13 +213,15 @@ Types that are not accompanied by a `format` property follow the type definition 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. | +| [Data Model Type](#data-types) | [`format`](#data-type-format) | Comments | +| ------------------------------ | ----------------------------- | ---------------------------- | +| number | `int32` | signed 32 bits | +| number | `int64` | signed 64 bits (a.k.a long) | +| number | `float` | | +| number | `double` | | +| string | `password` | A hint to obscure the value. | + +As noted above, both `type: number` and `type: integer` are considered to be numbers in the data model. #### Working With Binary Data