IoT Semantics

From AMTech WikiDocs
Jump to: navigation, search

Linked data


Resource Description Framework (RDF)


Json for linked data

Example of an observation @type eddystoneBrodcast, @id eddystoneBroadcast

    "proximityarea": "",
    "eddystoneTlmAdvCnt": 0,
    "guestusers": [],
    "targetthings": "[]",
    "location": "",
    "eddystoneTlmVbatt": 0,
    "eddystoneTlmSecCnt": 0,
    "lastSeenByBLEHub": "2016-02-21T18:39:21.000Z",
    "eddystoneType": "uid",
    "eddystoneNamespace": "0123456789",
    "eddystoneInstance": "123456",
    "eddystoneTlmVersion": "0",
    "smoothingResult": "new",
    "description": "",
    "topic": "m2mBridgeTest/bleScanner/eddystone/new",
    "beaconRssi": 1,
    "@type": "/amtech/linkeddata/types/composite/observation/eddystoneBrodcast",
    "beaconTxPower": 1,
    "beaconDistance": 0,
    "creationDate": "2016-03-24T20:53:47.369Z",
    "guesttenants": [],
    "eddystoneUrl": "",
    "eddystoneTlmTemperature": 0,
    "producer": "eddystone",
    "detectiontime": "2016-03-04T18:37:31.000Z",
    "occurrencetime": "2016-03-04T18:37:31.000Z",
    "@id": "/amtech/things/observations/eddystoneBroadcast"

Things and Observations semantic

  • Semantic for things and observations can be defined using the Thing Types and Observation Types
  • A type is associated to every resource in the platform
  • These types include:
    • General info (name, description, geometric representation)
    • Specific properties known as supported properties
    • In the case of the thing types, the set of observation types that the given thing type can produce

Each specific property contains its own semantic to define. The main common information are:

  • Value type or range: type of the values this property can hold
  • property informations: name, caption, description, default values,etc
  • Validation parameters and message (see below).
  • Translation of the caption, description, validation message to the supported languages

Also, the thing types allow

  • Maximum number and recording frequency of historic values (snapshots) to keep for the property, this is the information that will be shown in the timeline view
  • an option to check if the thing type is allowed to have floor plan that can be helpful when working with proximity areas.

The validation parameters include

  • minimum and maximum values for numerical data
  • minimum and maximum date for datetime data
  • regular expression for strings
  • isRequired to say that the field can not be empty.
  • JSON schema see Thing type SNMPDevice property setOIDs JSON schema validation
       "type": "array",
       "items": {
           "type": "object",
           "properties": {
               "oid": {
                   "type": "string",
                   "pattern": ""
               "type": {
                   "type": "string",
                   "enum": ["Integer", "OctetString", "Null", "ObjectIdentifier", "Sequence", "IpAddress", "Counter", "Gauge", "TimeTicks", "Opaque", "NsapAddress", "Counter64", "NoSuchObject", "NoSuchInstance", "EndOfMibView", "PDUBase"]
               "value": {
                   "type": "string"
           "required": ["oid", "type", "value"]

To create a new supported property click on Create.png under the supportedProperties collection of the chosen semantics. The opened dialog allows to define the name of the property and the value type:

Select property type

As shown, there are 4 options

  • SemanticPrimitiveType.png the value type must be one of the proposed primitive types
Select primitive type
  • SemanticAnyThing.png the value must be an instance of any of the already defined thing types
  • SemanticThingType.png the property will hold thing types
  • SemanticThingOfType.png the property will hold instances of the thing type selected in the dialog

The choice will then appear on the right of the button

The three last options allow also to define the property as a collection: check to create collections

Clicking on the button AcceptBtn.png will create the new property and will open it on the editor so you can edit the other information of its semantics.

Thing and Observation instances

Instances are resources of a specific semantic type, that have values for each property defined in the semantics.

  • Support instances enrichment, allowing to insert new properties and values after semantic been extended.

Sharing semantic

  • Thing and observation types can be shared with other tenants using the property guestTenants
  • Sharing a type with a tenant will automatically share all of its properties with the tenant
  • Properties can be added to a type that is already shared as long as the new properties are not required
  • Properties added to a type that is already shared will not be visible to the type guest tenants until the property is shared, or the type is shared again
  • Properties can only be added to a type by its creator or any creator belonging to the same tenant
  • Existing properties that are required cannot be deleted from a type that is already shared if instances exist for the type in any tenant
  • A type can be deleted, even if it is shared, but only if it is not used by any other resource (Ex. it cannot be used in any activity, instances cannot exist, etc)
  • Properties related to the validation of a supported property cannot be changed if the supported property is shared and instances of the type exist. These properties are :
    • validationRegEx
    • validationSchema
    • minValue and maxValue for numeric supportedProperties
    • minDate and maxDate for datetime supportedProperties
  • Icon for types that are shared with at least one tenant

Resource status

Resources have a status "draft" or "valid" according to validations of it properties against the metadata. If at least one property does not meet the conditions such as min value or validation regex, the resource status is set to draft. The status is a system-maintained property. It is updated every time a property value changes, or when the resource is explicitly validated. Validations can be performed by users that have only guest access to a resource, and even in that case, the system will use the result of the validation to update the status.

The execution of an observer does not return resources with invalid status, and therefore these resources are not taken into account in a reasoner execution.

Properties data type in custom semantics

  • Support for using same property ID, with different data types in different Thing/Observation types

The supported properties of the user-defined semantic have the scope of the type. This allows to define a supported property with the same ID in different types, with different meaning (data type). For instance: a thing type Truck with a property Weight of type double, and a thing type Container with a property Weight of type integer, that keeps not relation to the Truck weight other than having the same ID.

  • Restriction of not reusing a property name with a different data type inside a Thing/Observation after property deletion

Once a supported property is defined inside a Thing or Observation type, using a data type, it cannot be redefined with another data type for the same Thing/Observation (even if the property is deleted from the type and then re-created). This is due to a restriction imposed by the graph data layer (Titan) (to be fixed in future releases)