Skip to content

Port format / integer changes from 3.1.1 #4053

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.

Sign up for GitHub

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

Merged
merged 1 commit into from
Aug 28, 2024
Merged

Port format / integer changes from 3.1.1 #4053

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 26 additions & 21 deletions versions/3.0.4.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh wow! I totally forgot about "null" when we were working on the 3.0.4 version. We need to exclude null there too, right?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mikekistler this is the 3.0.4 version- I did this change backwards (3.1.1 first) because 3.1.1 was easier as it uses JSON Schema as-is. Hopefully I didn't miss anything in this PR where null needed to be removed.

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

Expand Down