Basic Data Format - open-inc/openware GitHub Wiki

The data retrieved from an open.WARE instance is formatted as JSON. The structure looks as follows:

Data Model

Data Structure

{
  "id": "UNIQUE_ID_IN_SOURCE",
  "source": "UNIQUE_NAME_OF_SOURCE",
  "name": "HUMAN READABLE NAME",
  "meta": {},
  "user": "SAME_AS_SOURCE",
  "valueTypes": [
    {
      "name": "Number Example",
      "unit": "s",
      "type": "Number"
    },
    {
      "name": "String example",
      "unit": "",
      "type": "String"
    },

    {
      "name": "Boolean Example",
      "unit": "",
      "type": "Boolean"
    },
    {
      "name": "Geo example",
      "unit": "",
      "type": "Geo"
    },
    {
      "name": "Generic Example",
      "unit": "",
      "type": "Object"
    }
  ],
  "values": [
    {
      "date": 1655622190774,
      "value": [
        5,
        "Test",
        false,
        {
          "type": "Feature",
          "geometry": {
            "type": "Point",
            "coordinates": [125.6, 10.1]
          },
          "properties": {
            "name": "Dinagat Islands"
          }
        },
        { "foo": "bar" }
      ]
    }
  ]
}

Fieldname	Description
id	Unique Identifier within source; globally unique if combined with source
source	Unique Identifier for source; globally unique if combined with id
name	Human readable name of the data source/sensor, e.g. 'Server HQ'
meta	Store meta information about the data source. Can be used to store data, that might be required by third party systems. In the default implemenation this information is not stored immidiately but only after certain periods. Can be any JSON-Structure
valueTypes	Array describing the values that this data source contains. E.g. for multidimensional sensors such as environment it might contain three entries for temperature, humidity and heat index. Each entry must be an JSON object containing a name, a unit and an type property. The type value must be any of the available types
values	Array containing values (actual sensor data). Each entry must be an JSON object containing a date and a value property. The date field contains a unix timestamp in milliseconds. The value field is an array conaining values, as described in 'valueTypes'-field

Value Types within an Data Object

There are 5 basic types that are used throughout the open.WARE system. All sensor information that should be stored within the system should be assigned one of the types stated in the table below. By assigning a type, the system knows how to handle the data and different services (e.g. aggregation) is automatically available.

ValueType	Description
Number	The number type should be used for all numeric values. The system does not differentiate between Integers and Floats. If a value is of type Number aggregation services can be used. Internally the value is mapped to a Java Double, thus the max and min values limits apply
String	Can be any string
Boolean	Can be true or false. If you send data to your open.WARE instance and indicate a boolean value type, the system will automatically try to convert truthy values to true and falsy values to false
Geo	Any GeoJSON Object
Object	Any valid JSON object

User Model

User are also represented as JSON-Structure. Typically you don't have to deal with user objects when accessing the API. Nevertheless as it is sometimes necessary to understand what data about users is stored, we want to explain the most basic user data model:

{
  "uid": "ID_OF_USER",
  "name": "NAME_OF_THE_USER",
  "session": "Last known session of user",
  "data": "Additional data about the user, that can be different based on the user adapter used",
  "email": "Mail-adress of the user",
  "roles": "Array of Strings, which represent role-names the user has been assigned to",
  "permissions": "Array of permissions, that describe what data a user can read/write"
}