Inconsistent usage of quotes in yaml examples

[ndjensen]

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.

[MikeRalphson]

The YAML specification is referenced within the OAS specification, and so we defer the quoting rules to that spec. E.g. a $ref value containing a # character requires quoting so it isn't seen as beginning a comment.

Is there a best practice?

I think we should avoid recommending any stylistic choices for the YAML/JSON representations of the OAS document object graph. A simplistic example would be white-space in JSON. There are obvious pros and cons to having formatted versus 'minified' JSON depending on your use-case.

Consistency in examples, i.e. to reduce cognitive load when learning the OAS, is I think a fair point, and a PR for discussion would, I'm sure, be welcomed.

[darrelmiller]

I go back and forth between, "we should use different styles to highlight that multiple ways work" and "we should just be consistent". The challenge of course is deciding what are the "standard" conventions.

I accept that we are making it harder to learn by distracting people with unnecessary variations. I suppose the rule could be no quoting unless really necessary and default to double quote unless single quote is necessary.

[ioggstream]

I agree with @darrelmiller. Where should I PR that?

[MikeRalphson]

Examples can be PR'd against the master branch if they're external to the spec, otherwise the v3.0.3-dev branch and 3.0.3.md file.

[ioggstream]

I meant PR the rule @darrelmiller was proposing:

the rule could be no quoting unless really necessary and default to double quote unless single quote is necessary

[MikeRalphson]

So by "where" you mean...?

[ioggstream]

master...ioggstream:patch-1 Here?

[alecwcp]

This seems a good idea to make the use of quotes as consistent as possible. Any plans for this to be brought into the spec?

[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.

[ralfhandl]

Should be fixed now via

• Markdown updates for 3.0.4 #3932
• Markdown updates for 3.1.1 #3991
• Markdown updates for 3.2.0 #4025

and by regularly running the format-markdown npm script after future spec changes.