Merge pull request OAI#4027 from OAI/markdown-style-guide

Add markdown style guide to CONTRIBUTING

.markdownlint.yaml

@@ -0,0 +1,16 @@
+# Unordered list symbol
+MD004:
+ style: asterisk
+
+# Unordered list indentation
+MD007:
+ indent: 2
+
+MD012: false # allow blank lines
+
+MD013:
+ line_length: 800
+ tables: false
+
+MD024: false # duplicate headings
+MD033: false # inline HTML

CONTRIBUTING.md

@@ -35,6 +35,35 @@ Schemas are only changed _after_ the specification is changed. Changes are made
 
 * Issue #3576: [What is our authoritative spec URL and how do people find it?](https://github.com/OAI/OpenAPI-Specification/issues/3576)
 
+## 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](https://www.npmjs.com/package/markdownlint),
+as configured by the `.markdownlint.json` file in the root of the project.
+
+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 Foo Bar Objects are written in this style, and are not monospaced
+3. "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.
+
+### 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"
+
 ## Release Process and Scope
 
 * Issue #3528: [3.x.y patch release approach](https://github.com/OAI/OpenAPI-Specification/issues/3528)
@@ -95,7 +124,7 @@ The OpenAPI Initiative uses GitHub Projects to manage work _outside_ of the spec
 
 ### Discussions
 
-We are beginning (as of mid-2024) to use GitHub [discussions](https://github.com/OAI/OpenAPI-Specification/discussions?discussions_q=is%3Aopen) for open-ended topics such as major enhancements. 
+We are beginning (as of mid-2024) to use GitHub [discussions](https://github.com/OAI/OpenAPI-Specification/discussions?discussions_q=is%3Aopen) for open-ended topics such as major enhancements.
 
 * Issue #3518: [Define criteria for filing/closing issues vs discussions](https://github.com/OAI/OpenAPI-Specification/issues/3518)