-
Notifications
You must be signed in to change notification settings - Fork 9.1k
Clarify data model types and formats #4045
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from 7 commits
99b0fd8
c589651
898949f
2bc4e48
4b8378a
1c8f451
0b94cf5
151f316
8f626a5
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -199,25 +199,34 @@ 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. | ||
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. | ||
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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Now that I understand that JSON Schema actually defines "integer" as a type, why shouldn't we include it here? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. "integer" is a value for the
handrews marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
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. | ||
handrews marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
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 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. | ||
ralfhandl marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
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. | ||
ralfhandl marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
handrews marked this conversation as resolved.
Show resolved
Hide resolved
|
||
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 | ||
|
||
|
Uh oh!
There was an error while loading. Please reload this page.