3.0.4: minor nits #4001

ralfhandl · 2024-08-07T17:00:36Z

Mostly harmonization of terminology and formatting:

first mention of a normative reference or an OAS-defined Object in a (sub)*section is a link, additional mentions are not
OAS-defined Foo Bar Objects are written in this style, and are not monospaced
"example" instead of "sample" - this spec is not about statistics
"OpenAPI Object" instead of "root"
fixed fields are monospaced
field values are monospaced in JSON notation: true, false, null, "header", ...
combination of fixed field name with example value uses JS notation: in: "header", combining rules 5 and 6
exception to 5-7 is colloquial use, for example "values of type array or object" - "type" is not monospaced, so the monospaced values aren't enclosed in double quotes, I find this easier to read
"attribute" is only used in the XML context and means "XML attribute"
use Oxford commas, avoid Shatner commas

and two other uses of it in this document

handrews

All of these changes are helpful!

handrews · 2024-08-08T23:35:47Z

(oh wait it's a draft... well, I'll review it again when you're done :-)

ralfhandl · 2024-08-09T15:06:35Z

versions/3.0.4.md

@@ -2409,22 +2411,22 @@ This mechanism is used by [Link Objects](#link-object) and [Callback Objects](#c
 The runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax

 ```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


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?

handrews · 2024-08-11T19:55:03Z

@ralfhandl could you include this clarification?

Appendix on RFC6570-derived behavior + allowReserved (3.0.4) #3818 (comment)

See OAI#3818 (comment)

ralfhandl · 2024-08-12T09:42:52Z

versions/3.0.4.md

@@ -2682,7 +2684,7 @@ Other than the JSON Schema subset fields, the following fields MAY be used for f

 | 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`. |


The old wording seems to mean

Mentally put the string value of type into 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 the type keyword 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.

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.

I agree with @mikekistler - I find the new wording more confusing. I would go with something like:

This keyword only takes effect if type is explicitly defined within the same Schema Object. A true value indicates that both null values and values of the type specified by type are allowed. 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.

Took over Henry's proposal

mikekistler

Looks good. 👍

mikekistler · 2024-08-12T15:34:17Z

versions/3.0.4.md

 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.


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?

@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 style is form, the default value is true.

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 in is "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

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.

mikekistler

Looks good. 👍

3.0.4: minor nits

06460d1

ralfhandl changed the base branch from main to v3.0.4-dev August 7, 2024 17:00

Section 4.3.2

4339178

handrews added this to the v3.0.4 milestone Aug 7, 2024

handrews added the editorial Wording and stylistic issues label Aug 7, 2024

ralfhandl added 5 commits August 8, 2024 15:20

servers array at different levels

7f37999

language, formatting

b5d529c

braces according to Wikipedia

8abc73d

and two other uses of it in this document

Mismatch between table description and table heading

cb05844

Update 3.0.4.md

1aed970

handrews previously approved these changes Aug 8, 2024

View reviewed changes

ralfhandl mentioned this pull request Aug 9, 2024

Specify that tag names are case-sensitive #3999

Closed

ralfhandl added 3 commits August 9, 2024 09:49

Update 3.0.4.md

3a26bfc

Double-quotes around string values

cc55021

Formatting of string values

1fa3eda

ralfhandl dismissed handrews’s stale review via 1fa3eda August 9, 2024 11:12

ralfhandl added 6 commits August 9, 2024 13:15

Style Examples values

22a1553

Responses

70325c4

X Object always with Capital O

2b01041

casing

4aaeaa9

Pure YAML

ddbab4a

Fewer commas, formatting, ABNF indentation

91e8577

ralfhandl commented Aug 9, 2024

View reviewed changes

Formatting of string value

35edf64

handrews mentioned this pull request Aug 11, 2024

Appendix on RFC6570-derived behavior + allowReserved (3.0.4) #3818

Merged

ralfhandl added 2 commits August 12, 2024 09:30

Second pattern is problematic

439e8eb

See OAI#3818 (comment)

Rephrased to avoid contradicting other spec text

b12c1b2

ralfhandl commented Aug 12, 2024

View reviewed changes

ralfhandl added 7 commits August 12, 2024 13:20

Schema Object

9f1f1eb

Discriminator Object

5a27cfd

XML Object

b4926b4

Security

43039d0

Appendix C

9a6fa8e

Appendix D

8f2bb44

Appendix E

f1bdced

ralfhandl marked this pull request as ready for review August 12, 2024 14:12

ralfhandl requested review from handrews, lornajane, miqui, mikekistler and a team August 12, 2024 14:12

ralfhandl mentioned this pull request Aug 12, 2024

Open Community (TDC) Meeting, Thursday 15 August 2024 #4003

Closed

Field instead of attribute

8a8d9bb

mikekistler previously approved these changes Aug 12, 2024

View reviewed changes

mikekistler reviewed Aug 12, 2024

View reviewed changes

mikekistler self-requested a review August 12, 2024 15:34

Henry's proposal on nullable

e284595

ralfhandl dismissed mikekistler’s stale review via e284595 August 13, 2024 06:36

miqui approved these changes Aug 13, 2024

View reviewed changes

mikekistler approved these changes Aug 13, 2024

View reviewed changes

ralfhandl merged commit bd5a6d1 into OAI:v3.0.4-dev Aug 13, 2024
1 check passed

ralfhandl deleted the 3.0.4/nits branch August 13, 2024 13:38

ralfhandl mentioned this pull request Aug 13, 2024

3.1.1: minor nits #4014

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

3.0.4: minor nits #4001

3.0.4: minor nits #4001

ralfhandl commented Aug 7, 2024 •

edited

Loading

handrews left a comment

handrews commented Aug 8, 2024

ralfhandl Aug 9, 2024

handrews commented Aug 11, 2024

ralfhandl Aug 12, 2024

mikekistler Aug 12, 2024

handrews Aug 12, 2024

ralfhandl Aug 13, 2024

mikekistler left a comment

mikekistler Aug 12, 2024

ralfhandl Aug 12, 2024

mikekistler Aug 13, 2024

mikekistler left a comment

3.0.4: minor nits #4001

3.0.4: minor nits #4001

Conversation

ralfhandl commented Aug 7, 2024 • edited Loading

handrews left a comment

Choose a reason for hiding this comment

handrews commented Aug 8, 2024

Choose a reason for hiding this comment

handrews commented Aug 11, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mikekistler left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mikekistler left a comment

Choose a reason for hiding this comment

ralfhandl commented Aug 7, 2024 •

edited

Loading