Skip to content

Commit 898949f

Browse files
committed
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".
1 parent c589651 commit 898949f

File tree

1 file changed

+11
-9
lines changed

1 file changed

+11
-9
lines changed

versions/3.1.1.md

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -205,23 +205,25 @@ Data types in the OAS are based on the six types supported by the [JSON Schema S
205205

206206
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.
207207

208-
<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 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.
208+
#### Data Type Format
209+
210+
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.
209211

210212
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.
211213

212214
Types that are not accompanied by a `format` property 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.
213215

214216
The formats defined by the OAS are:
215217

216-
| [Data Model Type](#data-types) | [`format`](#data-type-format) | Comments |
217-
| ------------------------------ | ----------------------------- | ---------------------------- |
218-
| number | `int32` | signed 32 bits |
219-
| number | `int64` | signed 64 bits (a.k.a long) |
220-
| number | `float` | |
221-
| number | `double` | |
222-
| string | `password` | A hint to obscure the value. |
218+
| `format` | JSON Data Type | Comments |
219+
| ---------- | -------------- | ---------------------------- |
220+
| `int32` | number | signed 32 bits |
221+
| `int64` | number | signed 64 bits (a.k.a long) |
222+
| `float` | number | |
223+
| `double` | number | |
224+
| `password` | string | A hint to obscure the value. |
223225

224-
As noted above, both `type: number` and `type: integer` are considered to be numbers in the data model.
226+
As noted under [Data Type](#data-types), both `type: number` and `type: integer` are considered to be numbers in the data model.
225227

226228
#### Working With Binary Data
227229

0 commit comments

Comments
 (0)