Notes on identifiers and capitalization conventions

preserves-schema.md

@@ -4,7 +4,7 @@ title: "Preserves Schema"
 ---
 
 Tony Garnock-Jones <tonyg@leastfixedpoint.com>  
-June 2021. Version 0.1.2.
+June 2021. Version 0.1.3.
 
   [abnf]: https://tools.ietf.org/html/rfc7405
 
@@ -92,6 +92,31 @@ with schemas that can be translated into instances
 **Schema.** A collection of definitions, plus an optional schema-wide
 reference to a schema describing embedded values.
 
+## Identifiers and Capitalization Conventions
+
+Throughout, `id` is used in the grammar to denote an *identifier*,
+which is a symbol that matches the regular expression
+`^[a-zA-Z][a-zA-Z_0-9]*$`. This is a lowest-common-denominator
+constraint that allows for a reasonable mapping to the identifiers of
+many programming languages.
+
+Identifiers are case-sensitive. Schemas should be written with an
+awareness of the fact that some programming languages cannot preserve
+case differences. Avoid using two identifiers in the same context that
+differ only in case.
+
+Schemas should be written using the following capitalization
+conventions:
+
+ - `UpperCamelCase` for *definition* names.
+
+ - Either `lowerCamelCase` or `UpperCamelCase` for definition-unique
+   names for alternatives within a union definition.
+
+ - `lowerCamelCase` for *module* names (schema names, package names)
+   and *field* or *variable* names.
+
+
 ## Concrete (DSL) Syntax
 
 In this section, we use an [ABNF][abnf]-like notation to define a
@@ -324,11 +349,6 @@ the given name in the overall record type for a definition. The type
 of value contained in the field will correspond to the `Pattern` or
 `SimplePattern` given.
 
-An `id` is a symbol that matches the regular expression
-`^[a-zA-Z][a-zA-Z_0-9]*$`. This is a lowest-common-denominator
-constraint that allows for a reasonable mapping to the identifiers of
-many programming languages.
-
 ## Appendix: Metaschema
 
 The metaschema defines the structure of the abstract syntax (AST) of