Service Object Descriptor

This page describes the data format and restrictions of a Service Object descriptor

Important Format Restrictions:

For spatial queries, a channel named location with type ‘geo_point‘ must be added to a stream It will  represent the latitude and longitude as comma separated values: “34.5445 , 3.5533”

Firs level properties

  • name“: String representing a human readable name of the device. This is an OPTIONAL field but users are heavily encouraged to fill it with some basic information
  • description“: String representing a human readable description of the device. This is an OPTIONAL field but users are heavily encouraged to fill it with some basic information
  • public“: Boolean that describes if the data associated to this Service Object is private (false) and only visible by its owner (identified by its the API KEY) or it is public (true) and anyone can see this data stream. This is an OPTIONAL field, and by default it is assumed all data is PRIVATE if not stated otherwise.
  • URL“: String representing a location where the device or information about it can be found. This is an OPTIONAL field.
  • streams“: Any device can have 0-n sensors that can collect data periodically or sporadically. Each sensor has an associated data stream (a sensor stream) where sensor readings are pushed and made available. This is a MANDATORY field.
  • customFields“: An array of text properties that provides an extension point to define WO specific properties. This is a OPTIONAL field. This is the only field that will be affected by following UPDATE operations performed on the Service Object.
  • actions“: Array of actuations implemented on the device that can be invoked by its owner through this Service Object. More information on this subject can be found in this section. This is a MANDATORY field, and if no information is to be provided, an empty array must be provided at least.

Stream properties

  • channels“: Each stream might have one or more dimensions, which are dependent on the specific domain. We call these dimensions channels. The definition of the channels is domain specific, but typically, each channel will have a set of custom fields which are multiple key-value pairs for that particular reading. This is a MANDATORY field.
  • description“: human readable description of the stream.This is an OPTIONAL field but users are heavily encouraged to fill it with some basic information
  • type“: string describing the nature of the sensor generating this data stream. For informational purposes only. This is an OPTIONAL field but users are heavily encouraged to fill it with some basic information

Channel properties

  • type“: One of string, number, boolean” or geo_point“. This is a MANDATORY field. Notice that in the case of using geo_point, the expected format is a string containing a pair <latitude, longitude>. Example: “34.5445 , 3.5533″. If the name of the channel is “location“, then the servIoTicy platform will offer geo-located search capabilities for all data channels of the corresponding stream.
  • unit“: string describing the nature of the units used for representing the data. This is an OPTIONAL field provided for informational purposes only.

Actions properties

  • name“: String representing the name that identifies the action. It must be a unique name within the Service Object. This is a MANDATORY field. Details about how to implement actions on the devices can be found in this section.
  • description“: string describing the action and the parameters that it accepts. This is an OPTIONAL but users are heavily encouraged to provide this information.

Sample Service Object Descriptor

This example describes a sample Service Object that could be created for a Cell Phone with accelerometer, GPS and temperature sensors. It would provide raw data for the accelerometer (stream “accelerometer”) and geo-located data for the temperature (stream “located-temperature”). Later on, geo-located queries could be performed on the temperature data.