openapi-wit 1.0.0

Bidirectional bindings between OpenAPI (Swagger) and WIT
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

# Type System

Definitions are for [OpenAPI v3.1.0](https://spec.openapis.org/oas/latest.html):

| JSON Schema Type | OpenAPI Format Modifier | WIT Type    |
| :--------------- | :---------------------- | :---------- |
| `null`           | -                       | `option<T>` |
| `boolean`        | -                       | `bool`      |
| `object`         | -                       | `record`    |
| `array`          | -                       | `list<T>`   |
| `number`         | -                       | `float64`   |
| `number`         | `float`                 | `float32`   |
| `number`         | `double`                | `float64`   |
| `string`         | -                       | `string`    |
| `string`         | `password`              | `string`    |
| `integer`        | `int32`                 | `s32`       |
| `integer`        | `int64`                 | `s64`       |
| `integer`        | `int64`                 | `s64`       |

## Discussion

The base `number` type without any qualifier here is mapped to `float64`. The
JSON Schema specification mentions it should actually be:

> An arbitrary-precision, base-10 decimal number value, from the JSON "number"
> value.

But we want to be able to use `serde-json` for this, which defines `number` [as
an
`f64`](https://docs.rs/serde_json/latest/serde_json/value/struct.Number.html#method.from_f64).
WIT does not (yet?) support arbitrary-precision floating point numbers, so in
the absence of any constraining information we should just pick the biggest
number we can support.

WIT also has no notion of `null` in the type system; instead it uses the
`option` type to indicate a value may or may not be present. A field which can
only ever be `null` should be rejected in any encoding - in Rust terms we'd want
to translate that to a type of `Option<!>` (only `None` can be constructed) - or
`Option<Unreachable>` (an empty enum akin to `!`). But in WIT we can't do either of these things, so a field that's hard-coded to only ever be `none` should be rejected to prevent any ambiguities in the encoding.

Regarding password stings: for the sake of simplicity we should treat this as a
regular string for the time being. However in the future we may want to define a
generic type `sensitive<T>` which can hold strings whose contents are sensitive
and should never be printed or displayed. This will require a non-trivial type
system addition though, as we'll also want to consider secret encoding /
decoding schemes, if only to ensure we're making the right tradeoffs. So to not
have that conversation right now, we're just treating password strings as
regular strings.

## See Also

- [OpenAPI `v3.1.0` specifcation](https://spec.openapis.org/oas/latest.html#openapi-document)
- [`webidl-wit`](https://github.com/MendyBerger/webidl-wit/tree/main)
- [`serde_json::value::Number`](https://docs.rs/serde_json/1.0.61/serde_json/value/struct.Number.html)
- [json schema draft RFC](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-01#section-4.2.1)