Public Page

JSON Style Guide

Owned by Paulette Reed
Last updated: Apr 19, 2022
3 min read

JavaScript Object Notation (JSON) is an open standard data interchange format that uses human-readable text to exchange data in name-value pairs.

Introduction

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.

Definitions

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

General Guidelines

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

Example

 {
       "createDateTime": "2001-06-01T21:30:00Z",
       "insured": {
              "firstName": "C-35Optional",
              "lastName": "C-60Optional",
              "address": {
                     "address1": "address Line 1",
                     "city": "City",
                     "stateProvince": "SD"
              },
              "email": "other.email-with-hyphen@example.com",
              "phoneNums": [
                     {
                           "type": "WP",
                           "phoneNum": "858-5552222",
                           "preferredInd": true
                     },
                     {
                           "type": "FX",
                           "phoneNum": "858-5553333"
                     }
              ],
              "partyTypes": [
                     "Primary Contact"
              ]
       }
}

The excerpt above illustrates several concepts discussed in this style guide:

  1. Envelope Style (or Enveloping), i.e. a top level named object is not used, but rather after the opening bracket the two properties "createDateTime" and "insured" and immediately rendered.

  2. camelCase (notable for lower case initial letters) is used for all the property names except

  3. Array properties have plural names ("phoneNums", "partyTypes") and the arrays contain bare (i.e. unnamed) items (e.g. phoneNumber objects, "partyType" enumeration")

  4. Dates are formatted as strings following the RFC 3339recommendations