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

3.1.1: minor nits #4014

Merged
merged 2 commits into from
Aug 14, 2024
Merged

3.1.1: minor nits #4014

merged 2 commits into from
Aug 14, 2024

Conversation

ralfhandl
Copy link
Contributor

This is a port of

Mostly harmonization of terminology and formatting:

  1. first mention of a normative reference or an OAS-defined Object in a (sub)*section is a link, additional mentions are not
  2. OAS-defined Foo Bar Objects are written in this style, and are not monospaced
  3. "example" instead of "sample" - this spec is not about statistics
  4. "OpenAPI Object" instead of "root"
  5. fixed fields are monospaced
  6. field values are monospaced in JSON notation: true, false, null, "header", ...
  7. combination of fixed field name with example value uses JS notation: in: "header", combining rules 5 and 6
  8. exception to 5-7 is colloquial use, for example "values of type array or object" - "type" is not monospaced, so the monospaced values aren't enclosed in double quotes, I find this easier to read
  9. "attribute" is only used in the XML context and means "XML attribute"
  10. use Oxford commas, avoid Shatner commas

@ralfhandl ralfhandl added editorial Wording and stylistic issues approved pr port PRs that just port an approved PR to another version labels Aug 13, 2024
@ralfhandl ralfhandl added this to the v3.1.1 milestone Aug 13, 2024
Copy link
Contributor

@mikekistler mikekistler left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good! 👍

@ralfhandl ralfhandl merged commit b016683 into OAI:v3.1.1-dev Aug 14, 2024
1 check passed
@ralfhandl ralfhandl deleted the 3.1.1/minor-nits branch August 14, 2024 16:22
ralfhandl added a commit to ralfhandl/OpenAPI-Specification that referenced this pull request Aug 15, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
approved pr port PRs that just port an approved PR to another version editorial Wording and stylistic issues
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants