Skip to content

Commit f76be56

Browse files
committed
Fix an example, add more guidance on validation
1 parent caa302a commit f76be56

File tree

1 file changed

+4
-2
lines changed

1 file changed

+4
-2
lines changed

src/oas.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1130,15 +1130,15 @@ examples:
11301130
serializedValue: id=this&id=that&id=theother
11311131
```
11321132

1133-
A free-form query parameter, allowing undefined parameters of a specific type:
1133+
A free-form query parameter, allowing undefined parameters of a `type: "string"`:
11341134
11351135
```yaml
11361136
in: query
11371137
name: freeForm
11381138
schema:
11391139
type: object
11401140
additionalProperties:
1141-
type: integer
1141+
type: string
11421142
style: form
11431143
examples:
11441144
freeForm:
@@ -2258,6 +2258,8 @@ Therefore, such examples can only show the serialized form.
22582258

22592259
The `serializedValue` and `externalSerializedValue` fields show the serialized form.
22602260
These values SHOULD be valid examples of the serialized form, however this is not feasible to enforce in all cases due to some data values having multiple valid representations in certain formats as noted in [Appendix B](#appendix-b-data-type-conversion).
2261+
In some cases, parsing the serialized example and validating the resulting data can eliminate the ambiguity, but in a few cases parsing is also ambiguous, meaning that validation of serialized examples is by necessity a best-effort feature.
2262+
22612263
If either of `dataValue` or `externalDataValue` are also present, the serialized value MUST be a serialization of the data value, and SHOULD be a valid according to the serialization format.
22622264

22632265
When using `serializedValue`, the value MUST be a string that is suitably escaped for inclusion in JSON or YAML in addition to any escaping that is part of the serialization format.

0 commit comments

Comments
 (0)