Is this supposed to be a string or a JSON value?

[gregsdennis]

OpenAPI-Specification/examples/v3.0/api-with-examples.yaml

Line 52 in 9dff244

value: |

The YAML here yields a multiline string, but the other values use a JSON value. Was the string a mistake?

I note that in the corresponding .json file, it's also an encoded string, so it's probably correct. Why would this be?

[handrews]

@jeremyfiel didn't this come up in one of our Slack discussions?

[jeremyfiel]

I believe we did have some discussion on it but can't find anything at the moment.

The value keyword expects a string and the only way to define an object schema is to encode it as a string. value doesn't allow schemas if that were the example representation

[gregsdennis]

The value keyword expects a string and the only way to define an object schema is to encode it as a string.

OpenAPI-Specification/examples/v3.0/api-with-examples.yaml

Line 91 in 9dff244

value:

This line is the exact same keyword, but this is parsed as an object, not a string. Why is there a difference?

(I suppose I should have mentioned this comparison at first.)

[darrelmiller]

@jeremyfiel The value property is defined as Any.

To represent examples of media types that cannot naturally represented in JSON or YAML, use a string value to contain the example, escaping where necessary.

There is nothing to stop someone representing a JSON or YAML as a string also. A consumer would have to do some reconciliation between the expected datatype of the parameter/content and the data type of the example value.

[gregsdennis]

There is nothing to stop someone representing a JSON or YAML as a string also.

I would say that text implies that JSON/YAML should not be embedded in a string. I understand that it's not a hard requirement, but the implication seems quite apparent to me.

[handrews]

This is answered here:

• Ambiguities Regarding Parameter Example Validation #3041 (comment)

and that issue is in the 3.0.4 milestone to be clarified. Closing this as a duplicate.