Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Inconsistent usage of quotes in yaml examples #1720

Closed
ndjensen opened this issue Oct 19, 2018 · 10 comments
Closed

Inconsistent usage of quotes in yaml examples #1720

ndjensen opened this issue Oct 19, 2018 · 10 comments
Labels
editorial Wording and stylistic issues examples requests for more or better examples in the specification Housekeeping
Milestone

Comments

@ndjensen
Copy link

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
Copy link
Member

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
Copy link
Member

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
Copy link
Contributor

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

@MikeRalphson
Copy link
Member

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
Copy link
Contributor

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
Copy link
Member

So by "where" you mean...?

ioggstream added a commit to ioggstream/OpenAPI-Specification that referenced this issue Dec 21, 2018
## This PR

Define a quoting rules for yaml examples.
@ioggstream
Copy link
Contributor

master...ioggstream:patch-1 Here?

@alecwcp
Copy link

alecwcp commented Oct 31, 2019

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
Copy link
Member

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

@handrews handrews added the examples requests for more or better examples in the specification label Jan 28, 2024
@handrews handrews added the editorial Wording and stylistic issues label May 24, 2024
@ralfhandl ralfhandl added this to the v3.0.4 milestone Jul 4, 2024
@ralfhandl
Copy link
Contributor

Should be fixed now via

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
editorial Wording and stylistic issues examples requests for more or better examples in the specification Housekeeping
Projects
None yet
Development

No branches or pull requests

7 participants