Grammar and style check

[stevespringett]

The CycloneDX specification must have grammar and style checks. Ideally, checks would be performed:

• On demand via GitHub Action
• On PRs - fail if grammar or style violations occur

Grammar check should adhere to ISO House Style where British English is used to describe the specification, but is not required for the specification itself. The ISO House Style also requires American English for certain words with Greek origin (e.g. standardization - with a 'z' not an 's').

Acceptance criteria:

• Scoped to JSON Schema only. Checks for XML and Protobuf are optional and nice-to-have.

• Schema properties

  • American English spell check on property names
  • Enforce lower camel case on property names

• Property titles:

  • Titles must be sentence case
  • British English (ISO House Style) spell check enforced

• Property descriptions (description and meta:enum)

  • Descriptions must be sentence case
  • Descriptions must form at least one complete sentence
  • Descriptions must end in a single full-stop (.)
  • British English (ISO House Style) spell check enforced
  • Grammar check
  • Ensure RFC-2119 style capitalization of MUST, SHOULD, etc are NOT used in descriptions

• Enumeration values

  • TODO: Define

Experiments

I have been experimenting with spelling and grammar checks with GitHub Actions in my personal repo. See
https://github.com/stevespringett/jsonschema-grammar-action and https://github.com/stevespringett/jsonschema-grammar-action/tree/main/.github/workflows

References

The Ecma Rules for Editing and Distribution may be used as reference in addition to the ISO House Style.