Skip to content

Commit a9fe16f

Browse files
committed
Better handling of empty/undefined in table
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`
1 parent 4847876 commit a9fe16f

File tree

1 file changed

+5
-4
lines changed

1 file changed

+5
-4
lines changed

versions/3.0.4.md

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1146,10 +1146,11 @@ Assume a parameter named `color` has one of the following values:
11461146

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

1149-
* The value _e/s_ denotes the empty string
1149+
* The value _empty_ denotes the empty string, and is unrelated to the `allowEmptyValue` field
11501150
* The behavior of combinations marked _n/a_ is undefined
1151-
* 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
1151+
* 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
11521152
* 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
1153+
* 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
11531154
* 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.
11541155

11551156
[`style`](#dataTypeFormat) | `explode` | `empty` | `string` | `array` | `object`
@@ -1158,8 +1159,8 @@ matrix | false | ;color | ;color=blue | ;color=blue,black,brown | ;color=R,100,G
11581159
matrix | true | ;color | ;color=blue | ;color=blue;color=black;color=brown | ;R=100;G=200;B=150
11591160
label | false | . | .blue | .blue,black,brown | .R,100,G,200,B,150
11601161
label | true | . | .blue | .blue.black.brown | .R=100.G=200.B=150
1161-
simple | false | _e/s_ | blue | blue,black,brown | R,100,G,200,B,150
1162-
simple | true | _e/s_ | blue | blue,black,brown | R=100,G=200,B=150
1162+
simple | false | _empty_ | blue | blue,black,brown | R,100,G,200,B,150
1163+
simple | true | _empty_ | blue | blue,black,brown | R=100,G=200,B=150
11631164
form | false | ?color= | ?color=blue | ?color=blue,black,brown | ?color=R,100,G,200,B,150
11641165
form | true | ?color= | ?color=blue | ?color=blue&color=black&color=brown | ?R=100&G=200&B=150
11651166
spaceDelimited | false | _n/a_ | _n/a_ | ?color=blue%20black%20brown | ?color=R%20100%20G%20200%20B%20150

0 commit comments

Comments
 (0)