Custom JSON Schema

 

The Service Access Points supports the transparent pass through of customer blob data when the Service Access Point is setup to in “Raw Socket” / “Blob” mode.

Service Access Points also support use of customer’s own bespoke JSON format. This service allows the customer devices to send IoT data in their original device application JSON data structure and eliminate the need to redesign or change the device IoT application.

A predefined Custom JSON Schema is then used to locate and extract specific key/values out of the device JSON data to, for example extract the device identity, authentcate the device, extract payload and retrieve additional information such as power usage information, signal strength and more.

The predefined Custom JSON Schema is only applied on the uplink messages from the device.

The downlink message payloads submitted into the platform by the customer for onward delivery to devices are usually already in the device JSON data structure (the JSON format that the device understands). In other words downlink payload is passed on to the device as received. If Charset transcoding is configured on the service template then payload is transcoded to the customer configured device delivery encoding schema” prior to the data being sent. If no charset transcoding is configured then the data is transmitted to the device transparently.

Note that the JSON data from device must be in a valid JSON format (i.e. according to RFC 7159) and a valid Custom JSON Schema must be defined on your private Service Access Point in order to successfully handle/ingest data from your IoT devices when the SAP framework is set to Custom JSON.

 

The Custom Schema service is simple to use and can be enabled by pre-defining the required attributes as listed below and the corrending path where they can be located/extracted from the device application custom JSON data structure. Defining Custom JSON Schema is quick and straightforward and uses the dotted notatio as below examples.

The required attributes that must be defined in the Custom Schema are:

• udid (the unique device identity on the platform)
• at (authentication token)
• data (device payload)

The udid may be left out if  “device_id” AND “customer_id” are defined or if the device  “imsi” and “customer_id” are defined.

Other attributes that can be extracted but are optional (can be omitted) are:

• msgid (message_id)
• trpn (traffic_routing_profile_number)
• lat (gps location lat)
• long (gps location long)
• ss (signal strength)
• pw (power usage info)
• tmst (unix timestamp)

The above values are akin to the SimplyTiny data format attributes. More info about the attributes can be found in the SimplyTiiny documentation.

Example #1:

A customer device application uses a prorietery JSON format, the device sends all messages in this format and this is therefore what will be received on the platform Service Access Point used by the device for the transaction. For example the proprietery JSON data received is as follows:

A predefined Cusom JSON Schema that will extract the device UDID and other key values from this proprietery JSON data would like like this:

 

Example #2:

In this example rather than using the platform UDID, the device proprietery JSON data contains the Device SIM CARD IMSI as the means for device identity.

Note that to use the IMSI or the Custom Device ID as the means to identity a device.

1. The IMSI or Device ID value of the device must be configured in the device object on the platform in the relevant device identity fields such as the IMSI field or Device ID field.
2. The values configured in the device object on the platform must match the values in the JSON data received from the device.
3. In addition, the customer id (cid) must also be supplied in the JSON data from the device. The customer id is the id of the customer account on the platform.

Sample Device Application custom JSON Data

Custom JSON Schema to configure on SAP to extract the required and or desired attributes: