Skip to content

Commit

Permalink
Better handling of empty/undefined in table
Browse files Browse the repository at this point in the history
This was confusing, and my initial use of _e/s_ was too novel.
Switch the column heading to "undefined" to align with RFC6570
and make clear that it is not about `allowEmptyValue`
  • Loading branch information
handrews committed Jun 10, 2024
1 parent a30a9cf commit 3228429
Showing 1 changed file with 5 additions and 4 deletions.
9 changes: 5 additions & 4 deletions versions/3.0.4.md
Original file line number Diff line number Diff line change
Expand Up @@ -1120,10 +1120,11 @@ Assume a parameter named `color` has one of the following values:

The following table shows examples, as would be shown with the `example` or `examples` keywords, of the different serializations for each value.

* The value _e/s_ denotes the empty string
* The value _empty_ denotes the empty string, and is unrelated to the `allowEmptyValue` field
* The behavior of combinations marked _n/a_ is undefined
* The `empty` column refers to values that [RFC6570 §2.3](https://www.rfc-editor.org/rfc/rfc6570.html#section-2.3) describes as "undefined", and is unrelated to the `allowEmptyValues` field
* The `undefined` replaces the `empty` column in previous versions of this specification in order to better align with [RFC6570 §2.3](https://www.rfc-editor.org/rfc/rfc6570.html#section-2.3) terminology, which describes certain values including but not limited to `null` as "undefined" values with special handling; notably, the empty string is _not_ undefined
* For `form` and the non-RFC6570 query string styles `spaceDelimited`, `pipeDelimited`, and `deepObject`, each example is shown prefixed with `?` as if it were the only query parameter; see [Appendix C](#usingRFC6570Implementations) for more information on constructing query strings from multiple parameters, and [Appendix D](#serializingHeadersAndCookies) for warnings regarding `form` and cookie parameters
* Note that the `?` prefix is not appropriate for serializing `application/x-www-form-urlencoded` HTTP message bodies, and MUST be stripped or (if constructing the string manually) not added when used in that context; see the [Encoding Object](#encodingObject) for more information
* The examples are percent-encoded as required by RFC6570 and RFC3986; see [Appendix E](#percentEncodingAndFormMediaTypes) for a thorough discussion of percent-encoding concerns, including why unencoded `|` (`%7C`), `[` (`%5B`), and `]` (`%5D`) seem to work in some environments despite not being compliant.

[`style`](#dataTypeFormat) | `explode` | `empty` | `string` | `array` | `object`
Expand All @@ -1132,8 +1133,8 @@ matrix | false | ;color | ;color=blue | ;color=blue,black,brown | ;color=R,100,G
matrix | true | ;color | ;color=blue | ;color=blue;color=black;color=brown | ;R=100;G=200;B=150
label | false | . | .blue | .blue,black,brown | .R,100,G,200,B,150
label | true | . | .blue | .blue.black.brown | .R=100.G=200.B=150
simple | false | _e/s_ | blue | blue,black,brown | R,100,G,200,B,150
simple | true | _e/s_ | blue | blue,black,brown | R=100,G=200,B=150
simple | false | _empty_ | blue | blue,black,brown | R,100,G,200,B,150
simple | true | _empty_ | blue | blue,black,brown | R=100,G=200,B=150
form | false | ?color= | ?color=blue | ?color=blue,black,brown | ?color=R,100,G,200,B,150
form | true | ?color= | ?color=blue | ?color=blue&color=black&color=brown | ?R=100&G=200&B=150
spaceDelimited | false | _n/a_ | _n/a_ | ?color=blue%20black%20brown | ?color=R%20100%20G%20200%20B%20150
Expand Down

0 comments on commit 3228429

Please sign in to comment.