Skip to content

Latest commit

 

History

History
38 lines (27 loc) · 2.27 KB

style-guide.md

File metadata and controls

38 lines (27 loc) · 2.27 KB
Raw

Style Guide

Contributions to this repository should follow the style guide as described in this section.

Markdown

Markdown files in this project should follow the style enforced by the markdownlint tool, as configured by the .markdownlint.yaml file in the root of the project. The markdownlint tool can also fix formatting, which can save time with tables in particular.

The following additional rules should be followed but currently are not enforced by tooling:

  1. The 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 Objects such as Schema Objects are written in this style, and are not monospaced.
  3. Use "example" instead of "sample" - this spec is not about statistics.
  4. Use "OpenAPI Object" instead of "root".
  5. Fixed fields are monospaced.
  6. Field values are monospaced in JSON notation: true, false, null, "header" (with double-quotes around string values).
  7. A combination of fixed field name with example value uses JS notation: in: "header", combining rules 5 and 6.
  8. An 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.
  9. Use Oxford commas, avoid Shatner commas.
  10. Use <span id="thing"></span> for link anchors. The <a name="thing"></a> format has been deprecated.
  11. Headings use title case and are followed by a blank line.

Plus some suggestions, rather than rules:

  • Use one sentence per line in paragraphs and bullet points, to make diffs and edits easier to compare and understand. A blank line is needed to cause a paragraph break in Markdown.
  • In examples, use realistic values rather than foo/bar.

Use of "keyword", "field", "property", and "attribute"

  • JSON Schema keywords -> "keyword"
  • OpenAPI fixed fields -> "field"
  • property of a "plain" JSON object that is not an OpenAPI-defined Foo Object -> "property"
  • "attribute" is only used in the XML context and means "XML attribute"