CIECA Architecture Committee understands that everyone is looking forward to building OpenAPIs. CIECA is aware of members concern about “how can we get going on ‘CIECA’ JSON/REST interfaces before CIECA itself finalizes its JSON/REST standards?”. Old timers may recognize the similarity to the process of building “EMS XML” interfaces decades ago while members were waiting for BMS XML to be released. 

CIECA Architecture Committee would like to recommend the below steps for working through JSON interfaces based on BMS XML messages that follow the outlines of the process we’re undertaking as an architecture committee. This only gets you partway there, through the “science” part of art vs. science dynamic when we can’t guess the outcome of many weeks of committee discussions and compromises still ahead. 

The Process: 

• Gather the tag names from your BMS messages
• Convert the tag names to camelCase per CIECA JSON Style Guide guidelines 
• Structure repeating elements (XML style) to arrays with plural names (JSON style)
• Build JSON instances with examples of your current messages
• Optionally build json-schemas to describe your JSON instances
• Flatten objects by removing extraneous hierarchy
• Remove properties that are no longer used and remain for backward compatibility
• Bring your proposal to CIECA for review and recommendations.  (Product Committee(s) review, Architecture Committee review, SAB Review).

CIECA's CAPIS (CIECA Application Programming Interface Standard) JSON (JavaScript Object Notation) is envisioned together with REST (Representational State Transfer) and OpenAPI to have some fundamental differences that also need to be factored in:

• BMS's Request-Response structure which exchanges Rq and Rs messages will be implemented in CAPIS as an unnamed payload (suitable for Create/Read/Update operations) with responses typically exchanged as HTTP response codes. Therefore, messages names (e.g. DispositionAddRq/Rs, DispositionChgRq/Rs, DispositionStsRq/Rs) aren't expected to be part of the CAPIS standards
• Rules/principles like the above are regular things we learn and document in our ongoing committee development process

JSON Schema is a vocabulary that allows you to annotate and validate JSON documents. The JSON Schema specification can be found at

json-schema.org. 

CIECA wants to maximize JSON Schema's features that allow extensibility, in particular set the additionalProperties property to true and not use required enumerations for version numbers. CIECA's experience with XML schema has been very few complaints from trading partners about missing or inappropriate tags and values, and many more urgent production problems from schema validation errors. Trading Partners have very limited desire to upgrade versions and iterative agile development necessitates a new approach that doesn't require synchronizing on schema updates with our entire user community for deployments.

CIECA's XML schemas featured a cascade of include files for incorporating services, messages, code lists, and common/simple type definitions. JsonSchema can resolve references to code lists and type definitions in external files, but schemas are not included within parent schemas in the same way. CIECA's JsonSchema style will continue to gather code lists, and common/simple type definitions in external files to support schemas for individual services/messages.

Schema Building Procedures

Always make sure that you are referencing the property definition.

• 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 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.

• 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. (Examples:  adasCode instead of ADASCode, newOemPart instead of newOEMPart)

• Acronyms should always be used when they are on the CAPIS list

• 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).

• Avoid breaking the record for the longest property name (currently 35 characters) without a very good reason.

• The use of sub+word, the second word should not be captitalized (Examples:  subcategory, subtype)

• CIECA has a BMS appendix with a list of standard abbreviations. Contribute new abbreviations when necessary and only when necessary.

• abbreviation of qty should be used for number of, county, and qty.

• abbreviation of amt should always be used instead of the word amount

• 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.

• Service does not need to be abbreviated.

• Do not use underbar in names.  (Examples:  lineItemQty instead of lineItem_Qty)

• 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.

• Dates should be formatted as recommended by, RFC 3339 - Date and Time on the Internet: Timestamps (ietf.org)

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

 {

    "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"

    ]

 }

}

• 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