This style guide documents guidelines and recommendations for structuring JSON files and objects. The JSON specification can be found at JSON.org. This style guide addresses conventions for names, data types, abbreviations, etc., to provide for a standard look and feel for JSON files.
The remainder of this Style Guide uses the following definitions:
Property - a name/value pair within a JSON object
Property Name - the name portion of a name/value pair
Property Value - the value portion of a name/value pair
Do not use Envelope Style (or Enveloping) in which the top level object is a named property. Rather, follow the industry practice of rendering the top level object's child properties directly with no named property at the beginning.
No comments - don't use comments in JSON / JsonSchema. JsonSchema provides specific support for examples and descriptions. JSON files free from comments are a conventional feature of this lightweight format.
When we have properties that need to go together they should be an Object and introduce a level of hierarchy.
No extraneous layers, layers that don't add value to the thing being transmitted instance schema. For an example the OrgInfo or Party Aggregates in the BMS.
Property Name Guidelines
Property Names shall use camelCase, in which the property names begin with a lower-case letter and consist of words, acronyms, numbers, and abbreviations concatenated with each subsequent one beginning with an upper case letter.
Singular vs. Plural - use plural property name for arrays, singular names for all other properties.
Arrays should consist of bare objects without enveloping.
CIECA has a historical store of property names (in their historical formats they're often referred to as columns, fields, elements, or tags), and words/acronyms/abbreviations from which they are built. Take care to extend the word lists and property name lists only with truly new terms/concepts (for example BMS standardized on Uuid (for Universally Unique Identifier) so don't be that guy that adds GUID (for Globally Unique Identifier) to the word list). Also try to avoid breaking the record for the longest property name (currently 35 characters) without a very good reason.
Treat acronyms in property names like any other word, representing them in all lower case at the beginning of a property name, and with an initial upper case letter when they appear later in a property name.
CIECA has a BMS appendix with a list of standard abbreviations. Contribute new abbreviations when necessary and only when necessary.
Existing CIECA BMS xml and JSON schemas use UpperCamelCase, upper case acronyms, etc., which don't follow the current style guide. This style guide describes the current best practices for new APIs' use of JSON.
Naming Convention that Desc should be used for property that describe something in a string.
Property Value Guidelines
Property Values must be booleans, numbers, strings, objects, or null.
Consider omitting optional properties with empty/null values, especially when the alternative is to construct meaningless values (e.g. a date in the year 0001) to satisfy formatting constraints.
Enumerated types: Enum values should be represented as strings.
Property Values Data Types
Dates should be formatted as recommended by RFC 3339