profile
viewpoint

Ask questionsInconsistent usage of quotes in yaml examples

This is a minor nitpick but as someone unfamiliar with the OpenAPI specifcation and yaml until now, I found it confusing at first. There is inconsistent usage of quotes in the yaml examples in the 3.0.2 specification (and presumably earlier).

Specifically, there are places where the yaml examples have content 'application/json' and other spots where it has application/json. Same confusion applies to other content values. A notable example is the file uploads section where it has content application/octet-stream without quotes, 'image/jpeg' and 'image/png' with single quotes, and then multipart/form-data without quotes.

I also noticed inconsistencies with the $ref: value where for example it has $ref: "#/components/schemas/Pet" with double quotes and $ref: '#/components/schemas/SomePayload' with single quotes.

Is there a best practice? Reading the examples it wasn't immediately clear to me when I should quote vs not quote, and if single quote vs double quote is more standard.

OAI/OpenAPI-Specification

Answer questions MikeRalphson

@ioggstream sorry to come back to this after so long. I don't think this recommendation should be in the spec itself, as people should be free to quote (and indent etc) their OpenAPI documents in any way which is valid.

However, a PR to a (new) README.md file in the examples subdirectory would I think be a good idea so our own examples can aim for consistency.

useful!
source:https://uonfu.com/
answerer
Mike Ralphson MikeRalphson Postman, Inc. Newbury. UK http://mermade.github.io My hovercard is full of eels. I will not buy this repository; it is scratched.
Github User Rank List