Arnica WebScript - data struct conventions for nano services

April 15, 2019 by Igor Lozhkin
Web services and nano services talk to each other. They exchange data by sending query string parameters, posted content, HTTP headers, updating and reading data sets in database, or using shared application state. 

Sharing single value properties is easy to agree on. Sharing database-based data sets doesn't require any agreement - just follow database formats. However, sharing data structures, which go beyond single values but do not have supporting database tables, requires agreement on the data exchange standards.  

The data exchange standard has to specify conventions for property names and data serialization formats.

Property names

Property names may follow one of the following conventions:
  • camelPropertyNameConvention
  • PascalPropertyNameConvention
  • snake_property_name_convention
  • kebab-property-name-convention
We adopted Snake convention for property names.

Both Camel and Pascal convention were avoided because some languages use all caps or all lower case when serializing or de-serializing properties to/from JSON or XML, or have special meaning for the cap/small first letter (for example, in Golang hidden properties must start with small letter and exportable properties must start with capital letter).

Kebab convention was avoided because most languages do not allow dash to be part of a property name.

Also, property names should follow general rules for system identifiers, i.e. should not start with a number and should not include spaces or special characters.

Data serialization format

We use only most basic data types: string, number, boolean, and provide notation for null value.

Datetime values are serialized as yyyy-mm-ddThh:mm:ss for both JSON and XML, and use attribute type="dateTime" for XML.

Bolean values are serialized as true/false for JSON and as 1/0 for XML and use attribute type="boolean" for XML.

Null values are serialized as null for JSON, and as empty values with attribute type="null" for XML.

Numeric values are serialized as unquoted values in JSON, and use attribute type="number" for XML.

String values are serialized as quoted values in JSON, and use attribute type="string" for XML.