Difference between revisions of "IoT Semantics"

From AMTech WikiDocs
Jump to: navigation, search
(Policies for updating and deleting published semantic)
(Things and Observations semantic)
 
(9 intermediate revisions by the same user not shown)
Line 45: Line 45:
  
 
== Things and Observations semantic ==
 
== Things and Observations semantic ==
Semantic for things and the observations they produce can be defined using the Thing Types and Observation Types.
+
* Semantic for things and observations can be defined using the Thing Types and Observation Types
This configurable semantic is composed by :
+
* A type is associated to every resource in the platform
* Type general info (name, description, geometric representation)
+
* These types include:
* Type specific properties known as supported properties
+
** General info (name, description, geometric representation)
* In the case of the thing types, the set of observation types that the given thing type can produce
+
** 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:
 
Each specific property contains its own semantic to define. The main common information are:
Line 107: Line 108:
 
*Support instances enrichment, allowing to insert new properties and values after semantic been extended.
 
*Support instances enrichment, allowing to insert new properties and values after semantic been extended.
  
== Publishing semantic ==
+
== Sharing semantic ==
The semantics for thing and observation types can be defined without letting others see the changes. The action of publishing a type is what makes it visible to other creators, thus available for use by others in their activities. Once published, a type can only be extended by its creator.
+
* 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
When a type is published:
+
* Properties can be added to a type that is already shared as long as the new properties are not required
*it becomes visible to other creators that will be able to use it in their activities
+
* 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
*its supported properties become visible to other creators
+
* Properties can only be added to a type by its creator or any creator belonging to the same tenant
*supported properties can only be added as long as they are not required
+
* Existing properties that are required cannot be deleted from a type that is already shared if instances exist for the type in any tenant
*existing supported properties that are required cannot be deleted if instances exist. If they are not required or no instances of the type exist, they can be deleted anytime
+
* 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)
*the type can be deleted only if it is not used by any other resource
+
* 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 :
*values for the validation of the supported properties that are published cannot be changed : min value, max value, min date, max date and validation regex
+
[[File:Typepublished.png|thumbnail|center|public]] *public types show this icon in the [[Tree editor|Tree editor]]
+
 
+
== Policies for updating and deleting published semantic ==
+
Once a type is published, the following policies apply to the update and delete of its supported properties
+
* Required properties cannot be deleted or added if instances of the type exist
+
* Properties related to the validation of a supported property cannot be changed if the supported property is published and instances of the type exist. These properties are :
+
 
** validationRegEx
 
** validationRegEx
 
** validationSchema
 
** validationSchema
 
** minValue and maxValue for numeric supportedProperties
 
** minValue and maxValue for numeric supportedProperties
 
** minDate and maxDate for datetime supportedProperties
 
** minDate and maxDate for datetime supportedProperties
A published type for which no instances exist has no restrictions for updating/removing/adding supported properties
+
* Icon for types that are shared with at least one tenant [[File:Typepublished.png|thumbnail|center|public]]
  
 
== Resource status ==
 
== Resource status ==
Line 137: Line 131:
 
== Properties data type in custom semantics ==
 
== Properties data type in custom semantics ==
 
* Support for using same property ID, with different data types in different Thing/Observation types
 
* 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.
+
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
 
* 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)
 
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)

Latest revision as of 11:23, 19 July 2018

Linked data

http://linkeddata.org/

Linked Data STRUCTURED DATA ON THE WEB

Resource Description Framework (RDF)

https://www.w3.org/RDF/

Json-ld

Json for linked data http://json-ld.org/

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
    public

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)