Proposal: Rename “spec” when referring to JSON/YAML spec files

[reidpr]

Presently, we use “spec” and “specification” to refer to both the CDI specification itself as well as the JSON/YAML files that instruct what to do for a (capital D) device.

IMO this leads to confusion. For example, in the first section of SPEC.md, we have “modifications to the spec” (line 15) and “the spec is is still under active development” (line 18), both referring to the CDI specification itself, but also “spec loading fails” (line 36), referring to the JSON/YAML files.

Disambiguation is of course possible, based on context or clarifying language. However, IMO we should spend users’ cognitive effort elsewhere.

I propose that before 1.0 we rename the files to clarify this. Options include but are not limited to:

• description
• prescription
• definition
• declaration
• catalog(ue)
• enumeration
• requirements
• provision

e.g., “prescription file”

Thanks for considering this.