Asset Data Model

For the organization and discovery of data sources, Organicity platform is relying on the NGSI9/10 information model. As depicted in the following diagram, the underlying data model of NGSI 9/10 consists of Asset Element, Asset Attributes and Attribute Metadata

Asset Data Model

An asset is associated with multiple attributes and each attribute can be associated with various metadata. Each one of the Organicity Sites and probably Organicity Experiments are contributing assets into the facility. Assets can represent various types of urban resources from IoT/sensor devices with sensors attached, smartphones, services, data sources stored as data files (csv, xml, pdf) shared online or references to data­endpoints online (third party APIs and data services). For purposes of clarity of how the data of the various assets can be accessed the Organicity indexed assets can be organized in three major categories:

In order to avoid conflicts with the identification of the assets and facilitating interaction with the entity information to the experimenters, there are specific conventions that should be followed on Asset, Attribute and Metadata definition.

Asset Attributes and Metadata:

Each Asset Element has to be associated with a set of of attributes. Each Asset Attribute might represent various parameters of the asset. In the case of an IoT device or a smartphone it might represent a sensing or actuation capability of the device or a device characteristic (static or not) like the human readable name of the device, its description, its location and so on. In the case of more abstract assets attributes might represent types of observations not produced by physical sensors (e.g., a bus reporting the number of available seats or the number of the route). Each attribute consists of a type shared amongst all Organicity sites, the actual value of the attribute and a list of metadata that describe the value.

By utilizing the proper attributes for the description of Assets various visualization and browsing options are made available through the Urban Data Observatory and the rest of the Organicity tools including: - GeoJson data browsing for attributes of assets referring to specific territories - Time­series data browsing for attributes of assets with historical data - combinations of the above cases

Each Metadata entry represents more characteristics of an attribute, like units of measurement and data types of the attribute value etc.

Common attribute types (e.g., observation types) should be described with same format by the Organicity sites and values should be represented at the same set of units (e.g., distance in meters and temperature in degrees Centigrade).

During the federation of various assets from the Organicity City Sites (Aarhus, London, Santader) a list of common urn names for Asset Types, Attribute Types and Metadata has been created (Get XLS file). It is recommended to use the available names when you are creating your assets.

Types and Identification of Assets

Each entity should have an unique identifier in the form of urn:oc:entity:[site]:[service]:[provider]:[group]:[entityName] where:

Assets could represent devices, places, buildings, and many other entities (including virtual objects). In Organicity, we define a set of OC Entity Types that can be extended in the future to include more complex installations. Each entity has a specific resource type in the form of ​ urn:oc:entityType:[Type]:[Name]​ where:

See XLS for a recommendation list of asset types.

Examples of assets ids and types:

"contextElement": {
  "id": "​urn:oc:entity:london:environmental:hydePark:weatherstation123​",
  "type": "​urn:oc:entityType:weatherstation",
  "attributes": [ … ]
} "
contextElement": {
  "id": "​urn:oc:entity:experimenters:86d7edce-5092-44c0-bed8-da4beaa3fbc6:57eab2c2ad0302ad0b5c92c6:asset1243​",
  "type": "​urn:oc:entityType:smartphone​",
  "isPattern": "false",
  "attributes": [ … ]
}

Asset Attributes

Asset attributes can represent either various urban observations or other things like properties of the asset creating the observations. Attributes can have a name, a type and a value (). Each attribute might represent: - in the case of an IoT device or a smartphone: - a ​ capability ​ of the device (sensing or actuation) - a ​ device attribute​ like: - description of device - location of the device - Management info: - hardware/software characteristics - communication interfaces, - latest activity - etc. - in the case of more abstract resources like a bicycle docking station or bus station and so on, attributes might represent another type of observation like - number of available bicycles or - delay of the next bus - etc. - in the case of of a CKAN resource shared online as a file the attributes encode metadata like: - the creator of the file - last update - the file type: csv,xml, xls, pdf. - the url to download the file - etc. - in the case of of an online web service sharing data attributes might represent - the url to query the web service - the url to retrieve documentation - the type of the web service (REST, SOAP) - etc.

Attribute names​ ​ might be a human readable strings.

Attribute types should follow the format: ​

urn:oc:attributeType:[type]​

The type should encode the type of observation shared in Organicity. Its quite important to describe only the type of observation that is represented and not other details (like the period of observation, the method of observation etc.) in order to facilitate the discovery process and the joining of information. For example is the attribute expressed the speed of vehicles its recommended to use urn:oc:attributeType:speed and then express in metadata level if the speed is per hour or per minute etc.

Attribute MetaData: Some of the aforementioned attribute types might require a specific set of metadata like: Attribute types for sensor measurements require a datatype metadata or Attribute types for sensor measurements require an unit of measurement metadata. Each Metadata represents various characteristics of the associated attribute of the asset. Some examples might be: - device​ description ​ metadata e.g., other languages - device​ location ​ metadata other representation of location like geohashing - sensing ​ metadata: timestamp of the latest value, url of endpoint to retrieve historical data of this device/sensor, description of sensor type, units of measurement and so on. - actuation ​ metadata: url of endpoint to trigger actuation, description of actuation, tbd… - other type of metadata

Examples of Attributes and Metadata

carbonEmission: {
    type: "urn:oc:attributeType:carbonEmission",
    value: "971.336623467994",
    metadata: {
        unit: {
            type: "urn:oc:uom:kilotonne",
            value: "kilotonne"
        },
    TimeInstant: {
        type: "urn:oc:attributeType:ISO8601",
        value: "2013-12-31T23:59:59"
    }
    }
}

See XLS for a recommendation list of asset types.

Geospatial Asset Attributes

:exclamation: :wrench: :earth_asia: Please, notice the Assets Spatial model changed on the past days! :earth_asia: :wrench: :exclamation:

For any questions you can contact us at https://support.zoho.com/portal/organicity/

Asset can have spatial-information attached. It is recommended each assets to have a spatial attribute. For assets that are having a location the asset location format should be used, while other assets with more complex geometries (e.g. polygons for boroughs in the city) the complex geometry format can be used.

Asset Location Format

This is the basic model for adding a simple single point location to an asset.

:exclamation: Notice this changed. Latitude and Longitude pairs work now following the WGS84 Lat Long, EPSG::4326 standard as described below:

Points are always always a string containing a valid latitude-longitude pair, separated by comma.⁠⁠

:wrench: If you used this before you simply need to reverse the longitude and latitude pairs to latitude and logitude as on the example:

{
  "location": {
    "value": "latitude, longitude",
    "type": "geo:point"
  }
}

Example:

{
  "location": {
    "value": "-0.2379, 51.5875",
    "type": "geo:point"
  }
}

Asset Complex Geometry Format

This model supports complex assets geometries representations by supporting standard GeoJSON geometry objects.

:exclamation: Notice this changed: The attribute name should be location instead of geometry and the type should be geo:json instead of oc:geo:json.

Attribute should be named location and type should be geo:json. Coordinates need to follow the longitude, latitude pairs in order to follow the GeoJSON standard

:wrench: If you used this before you simply need to check you are using the location attribute and the geo:json type as on the example below:

{
    "location": {
        "value": {
            "type": "Polygon",
            "coordinates": [
                [
                    [longitude, latitude],
                    [longitude, latitude]
                ]
            ]
        },
        "type": "geo:json"
    }
}

Example:

{
    "location": {
        "value": {
            "type": "Polygon",
            "coordinates": [
                [
                    [100.0, 0.0],
                    [101.0, 0.0],
                    [101.0, 1.0],
                    [100.0, 1.0],
                    [100.0, 0.0]
                ],
                [
                    [100.2, 0.2],
                    [100.8, 0.2],
                    [100.8, 0.8],
                    [100.2, 0.8],
                    [100.2, 0.2]
                ]
            ]
        },
        "type": "geo:json"
    }
}

More GeoJSON examples can be found in GeoJSON IETF Spec. Additionally, the following GeoJSON Tutorial might be useful in understanding the format.

Other designated Asset Attributes

There is a number of attributes that can be used for an asset that encode several aspects and facilitate several methods of Urban Data Observatory like the discovery process

Last Update

This attribute encoded the time that an update to the assed has been performed This attribute is set by Organicity platform

TimeInstant: {
    type: "urn:oc:attributeType:ISO8601",
    value: "2016-08-24T11:56:42+01:00"
}

Comments and general asset description

{
  "description": {
    "value": "This is a general description of the asset",
    "type": "urn:oc:attributeType:description"
  }
}

Ranking

{
  "ranking": {
    "value": 0.7 ,
    "type": "urn:oc:attributeType:reputation"
  }
}

Origin

This attribute encodes the origin of information described in the asset.

origin: {
    type: "urn:oc:attributeType:origin",
    value: "Train station performance indicators from the TransportAPI",
    metadata: {
        unit: {
            type: "NOT_APPLIED",
            value: "NOT_APPLIED"
        },
        url1: {
            type: "url",
            value: "http://fcc.transportapi.com/"
        }
    }
}
"origin": {
    "type": "urn:oc:attributeType:origin"
    "value": "http://www.londonair.org.uk/LondonAir/API/"
}

Organicity datasource endpoint

This attribute should describe if an Organicity client could retrieve historic data through the OC platform of by consuming an external API service or accessing an online file

"datasource": {
    "type": "urn:oc:attributeType:datasource"
    "value": "http://london.site.organicity.eu:8081/api/v1/entities/"
    "metadata": {
        "datasourceInternal": {
            "type": "urn:oc:datatype:boolean"
            "value": "true"
        }
    }
}

Organicity Java Entities A project for creating and parsing Organicity Asset with Java.