From 99b0fd81208413f3f62f4ac6435e2c04c60d0697 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Tue, 20 Aug 2024 14:08:39 -0700 Subject: [PATCH 1/8] 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 From c58965197e2affe14c0b3e3f570a4357210e7c63 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Wed, 21 Aug 2024 11:41:58 -0700 Subject: [PATCH 2/8] Use older JSON spec consistently. Co-authored-by: Ralf Handl --- versions/3.1.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 1bb22eb5aa..cbf1a4283e 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -203,7 +203,7 @@ Models are defined using the [Schema Object](#schema-object), which is a superse 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. +Note that the `type` keyword allows `"integer"` as a value for convenience, but keyword and format applicability does not recognize integers as being distinct from other numbers because [[RFC7159|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. From 898949f3e617646924c660a74711762ee8fd2e2c Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Thu, 22 Aug 2024 08:18:22 -0700 Subject: [PATCH 3/8] Improve table, make section for formats We had an anchor present for data type formats, but without a section headering. At this point, there is enough information to have a section heading. Also took @mikekistler's suggestion on flipping the first two table columns, and tried "JSON Data Type" as a compromise between "Data Model Type" and "Instance Type". --- versions/3.1.1.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index cbf1a4283e..1c8e9e5a8a 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -205,7 +205,9 @@ Data types in the OAS are based on the six types supported by the [JSON Schema S Note that the `type` keyword allows `"integer"` as a value for convenience, but keyword and format applicability does not recognize integers as being distinct from other numbers because [[RFC7159|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. +#### 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 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. @@ -213,15 +215,15 @@ Types that are not accompanied by a `format` property follow the type definition The formats defined by the OAS are: -| [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. | +| `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 above, both `type: number` and `type: integer` are considered to be numbers in the data model. +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 From 4b8378aa92441685095be01184c4517f38329b6f Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Thu, 22 Aug 2024 12:45:29 -0700 Subject: [PATCH 4/8] Sync with registry. Co-authored-by: Mike Kistler --- versions/3.1.1.md | 1 + 1 file changed, 1 insertion(+) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index a8e53d266d..e2a0051360 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -212,6 +212,7 @@ As defined by the [JSON Schema Validation specification](https://tools.ietf.org/ 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: From 1c8f451f06582958d79efb05e52a65bf1031999c Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Thu, 22 Aug 2024 13:11:24 -0700 Subject: [PATCH 5/8] Use "JSON data types" consistently where relevant. Co-authored-by: Mike Kistler --- versions/3.1.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index e2a0051360..c49a936629 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -201,7 +201,7 @@ Note that no aspect of implicit connection resolution changes how [URIs are reso 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. +Data types in the OAS are based on the six JSON data 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 JSON data 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 value for convenience, but keyword and format applicability does not recognize integers as being distinct from other numbers because [[RFC7159|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. From 0b94cf5b9026b1737407bba35d064e3340ebebb2 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Fri, 23 Aug 2024 13:14:49 -0700 Subject: [PATCH 6/8] More tweaks about integers. --- versions/3.1.1.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index c49a936629..83c730838d 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -199,11 +199,13 @@ Note that no aspect of implicit connection resolution changes how [URIs are reso ### Data Types -Models are defined using the [Schema Object](#schema-object), which is a superset of JSON Schema Specification Draft 2020-12. +Models are defined using the [Schema Object](#schema-object), which is a superset of the JSON Schema Specification Draft 2020-12. -Data types in the OAS are based on the six JSON data 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 JSON data 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. +Data types in the OAS are based on the six JSON data types supported by the [JSON Schema's data model](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-4.2.1): array, boolean, null, number, object, or string. -Note that the `type` keyword allows `"integer"` as a value for convenience, but keyword and format applicability does not recognize integers as being distinct from other numbers because [[RFC7159|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. +JSON Schema keywords and `format` values operate on these six JSON data 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 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 From 151f31693b38c7a07457a6f9a3177edf8b392dab Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Mon, 26 Aug 2024 11:14:12 -0700 Subject: [PATCH 7/8] Clarifications from mikekistler on OAS data type vs JSON schema kwd/fmt restrictions Clarifies that OAS data modeling is based on the types in the `type` validation keyword, but JSON Schema keywords and formats apply (or not) based on the JSON instance data model, which does not include integers. Co-authored-by: Mike Kistler --- versions/3.1.1.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 83c730838d..e9ffe241d6 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -199,11 +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 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. -Data types in the OAS are based on the six JSON data types supported by the [JSON Schema's 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 JSON data 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. +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. From 8f626a53b3ed86f6621c01a49c63d02fa864b439 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Tue, 27 Aug 2024 09:47:38 +0200 Subject: [PATCH 8/8] Update versions/3.1.1.md --- versions/3.1.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index e9ffe241d6..6ba383541c 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -210,7 +210,7 @@ Note that the `type` keyword allows `"integer"` as a value for convenience, but #### 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 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. +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.