3.0.4: minor nits #4001
3.0.4: minor nits #4001
Conversation
and two other uses of it in this document
handrews
left a comment
handrews
left a comment
There was a problem hiding this comment.
All of these changes are helpful!
|
(oh wait it's a draft... well, I'll review it again when you're done :-) |
| ```abnf | ||
| expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source ) | ||
| source = ( header-reference / query-reference / path-reference / body-reference ) | ||
| expression = "$url" / "$method" / "$statusCode" / "$request." source / "$response." source |
There was a problem hiding this comment.
Are we fine with the fact that ABNF literal text strings enclosed in double-quotes are case-insensitive?
For example "$url" matches values $uRl, $url, $URL and any other case variation.
Do we assume this to be general knowledge, or should we call it out?
|
@ralfhandl could you include this clarification? |
|
|
||
| | Field Name | Type | Description | | ||
| | ----------------------------------------------- | :-----------------------------------------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | <a name="schema-nullable"></a>nullable | `boolean` | A `true` value adds `"null"` to the allowed type specified by the `type` keyword, only if `type` is explicitly defined within the same Schema Object. Other Schema Object constraints retain their defined behavior, and therefore may disallow the use of `null` as a value. A `false` value leaves the specified or default `type` unmodified. The default value is `false`. | |
There was a problem hiding this comment.
The old wording seems to mean
Mentally put the string value of
typeinto an array and add the string"null"to this array, then interpret the array in the JSON Schema sense because OpenAPI explicitly forbids array values for thetypekeyword in the preceding section.
The new text hopefully avoids this mental gymnastics and the possible confusion of null as an allowed value and "null" as an additional string item in the array value of the JSON Schema type keyword.
There was a problem hiding this comment.
Not only are array values for type forbidden, but null is also forbidden.
null is not supported as a type
But I'm not sure the new wording is better. In particular, the "allowed values" reference could be confused with enum. Oh, but actually we should add null to the enum if it exists. JSON Schema says:
Elements in the array MAY be of any type, including null.
An instance validates successfully against this keyword if its value is equal to one of the elements in this keyword's array value.
Oh my.
There was a problem hiding this comment.
I agree with @mikekistler - I find the new wording more confusing. I would go with something like:
This keyword only takes effect if
typeis explicitly defined within the same Schema Object. Atruevalue indicates that bothnullvalues and values of the type specified bytypeare allowed. Other Schema Object constraints retain their defined behavior, and therefore may disallow the use ofnullas a value. Afalsevalue leaves the specified or defaulttypeunmodified. The default value isfalse.
There was a problem hiding this comment.
Took over Henry's proposal
ralfhandl
requested review from
a team,
handrews,
lornajane,
mikekistler and
miqui
| The `example` and `examples` fields are mutually exclusive, and if either is present it SHALL _override_ any `example` in the schema. | ||
|
|
||
| Serializing with `schema` is NOT RECOMMENDED for `in: cookie` parameters, `in: header` parameters that use HTTP header parameters (name=value pairs following a `;`) in their values, or `in: header` parameters where values might have non-URL-safe characters; see [Appendix D](#appendix-d-serializing-headers-and-cookies) for details. | ||
| Serializing with `schema` is NOT RECOMMENDED for `in: "cookie"` parameters, `in: "header"` parameters that use HTTP header parameters (name=value pairs following a `;`) in their values, or `in: "header"` parameters where values might have non-URL-safe characters; see [Appendix D](#appendix-d-serializing-headers-and-cookies) for details. |
There was a problem hiding this comment.
I'm curious about the convention we are using for string values here and elsewhere. The original text has in: cookie", which in YAML is valid and I think is preferred over the new text in: "cookie"`. The new text is not valid JSON. So what is our convention and why did we choose this?
There was a problem hiding this comment.
@mikekistler Please see the PR description:
- fixed fields are monospaced
This is the predominant style for fixed fields in the existing text.
- field values are monospaced in JSON notation:
true,false,null,"header", ...
This is done for example in the first table in section https://spec.openapis.org/oas/v3.0.3.html#fixed-fields-9, and I find it helpful that field names and field "values" are clearly distinguished, so I applied this pattern wherever I wondered whether something is a field name or a field value.
The second table in the same section does not use that convention and is rather hard to read. For example
When
styleisform, the default value istrue.
Here form is the content of a JSON string: is true also the content of a JSON string, or is it a JSON boolean? How much context do I have to read to figure that out?
The pattern in: query was introduced by Henry in 3.0.4, and I first tried to rephrase that into a style already present in 3.0.3:
if
inis"query"
That felt clumsy in some places, so I opted for in: "query" etc., combining conventions 5 and 6.
The PR description is my stab at an "editor's style guide", and of course open for discussion, and destined for documentation, for example in CONTRIBUTING.md
There was a problem hiding this comment.
Sorry I glossed over the PR description, and thank you for writing this!
On the particular style choice, I think I would slightly prefer YAML to JS, just to avoid adding another syntax style to the doc, but I can live with either as long as we are consistent.
4 participants
Mostly harmonization of terminology and formatting:
monospacedmonospacedtrue,false,null,"header", ...in: "header", combining rules 5 and 6arrayorobject" - "type" is not monospaced, so the monospaced values aren't enclosed in double quotes, I find this easier to read