search

OAI / OpenAPI-Specification

The OpenAPI Specification Repository
https://openapis.org
Apache License 2.0
28.52k stars 9.05k forks source link

Inconsistent usage of quotes in yaml examples #1720

Open ndjensen opened 5 years ago

ndjensen commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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

MikeRalphson commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

So by "where" you mean...?

ioggstream commented 5 years ago

https://github.com/OAI/OpenAPI-Specification/compare/master...ioggstream:patch-1 Here?

alecwcp commented 4 years ago

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 commented 3 years ago

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