Overview
The IoTEntity XML content model is a representation of an IoTEntity and its properties, a serialization that can be used as payload in an Event and as result and body of the RESTful API‘s GET and POST operations. The content model is formally defined as an XML Schema that is available for download.
When used as part of the RESTful API, the IoTEntity model can be accessed on five different levels:
- IoTEntity – Represents an entity as a whole. This level is also used in Event messages.
- IoTProperty – An individual property of an entity identified by the URI in the request.
- ArrayOfIoTEntity – A list, or collection, of IoTEntity elements.
- ArrayOfIoTProperty – A list, or collection, of IoTProperty elements of an entity identified by the URI in the request.
- ArrayOfStateObservations – A list, or collection, of IoTStateObservation elements of a property of an entity, identified by the URI in the request
Each level is represented as a root element in the corresponding XML document and is described in detail below. Note that IoTProperty will also be present as a child element to IoTEntity.
Element: IoTEntity
Entity objects are represented by IoTEntity elements with the following content model:
Figure: The IoTEntity content model
The IoTEntity is using a set of RDFa attributes @about, @prefix, @xml:base and @typeof where all attributes except @xml:base are required. The @about attribute MUST be used for providing a globally unique identifier of the entity. See the RDFa in LinkSmart section for general usage guidelines for RDFa attributes.
The optional Name and Description elements can be used to provide human readable descriptions of the entity. They are not intended to hold any machine interpretable data.
The optional and repeatable Meta element can be used to record any additional metadata about an entity. The type of metadata MUST be recorded using the RDFa attribute @property.
The repeatable IoTProperty element represents all properties of the entity, its content model is described below.
Finally, the content of an IoTEntity is open for extension by any other element provided that it is defined within an namespace that differs from the target namespace of the IoTEntity schema.
Element: IoTProperty
The IoTProperty element describes a particular property of an entity in an IoT system, including both metadata and often actual observations of state conditions, data values or measurements.
Figure: The IoTProperty content model
Similar to the IoTEntity, also IoTProperty is using the same set of RDFa attributes @about, @prefix, @xml:base and @typeof.
The @about attribute MUST be used for providing a unique identifier of the property within the scope of its parent entity, i.e. the id space for properties is locally scoped in contrast to the IoTEntity id space that should provide globally unique identifiers. The concatenation of IoTEntity and IoTProperty identifiers will then together form a globally unique identifier of the property.
The @prefix attribute is optional but MUST be used to define any CURIE prefix used by any child element of IoTProperty and not defined by any other @prefix attribute of the parent IoTEntity element.
The IoTProperty element does also include an optional @datatype attribute that SHOULD be used to record the datatype of the data value of the property recorded within the child IoTStateObservation/Value element. It is RECOMMENDED to use XML Schema datatypes such as ‘xs:datetime’ where the prefix ‘xs’ must be defined using the @prefix attribute.
See the RDFa in LinkSmart section for general usage guidelines for RDFa attributes.
The optional Name and Description elements can be used to provide human readable descriptions of the property. They are not intended to hold any machine interpretable data.
The optional UnitOfMeasure element can be used to record the unit of measurement for the data value provided in the child IoTStateObservation/Value element, such as “kW” or “ppm”. The type of data MUST be recorded using the RDFa attribute @typeof.
The optional and repeatable Meta element can be used to record any additional metadata about an entity. The type of metadata MUST be recorded using the RDFa attribute @property.
The values of the property, a time-series based data set is represented by the optional and repeatable IoTStateObservation element, that includes the Value element recording the data as a string, and time stamps for both PhenomenonTime and ResultTime (see Glossary for definition of these terms). Also IoTStateObservation includes an optional extension point that can hold additional complex data structures representing property values using elements from another namespace than used as target namsespace by the IoTEntity schema.
Finally, the content of an IoTProperty is open for extension by any other element provided that it is defined within an namespace that differs from the target namespace of the IoTEntity schema.
Example: A Farm Field entity
An example of a Farm Field entity is provided below. The entity has two properties temperature and humidity which are measured regularly and reported to the Storage Manager
The IoTEntity default namespace is declared on the root element to ‘http://linksmart.org/IoTEntity/1.0’. The globally unique identifier for the entity is provided in the @about attribute as “D77EC6B0F0394734925E0A90CE7D1B5B018671A3”.
The entity is typed as a ‘Farm Field’ referencing an ontology via the prefix ‘cnet’ using the CURIE notation. The prefix ‘clafis’ is defined using the @prefix attribute to the URI ‘http://ns.cnet.se/ontologies’.
The two properties have locally scoped identifiers recorded in the @about attributes, ‘Temperature’ and “Humidity”. Both properties are also typed, referencing the previously defined ‘clafis’ prefix, using the @typeof attribute. The datatypes of the property values are recorded in the @datatype attributes referencing XML Schema datatypes via the ‘xs’ prefix.
The ‘Temperature’ property use the UnitOfMeasurement element to record the unit of the value, “C”. The @typeof attribute is used to reference a type system, again using a “clafis:UoM”.
Finally, the data values and associated phenomenom and result times for the two properties are provided within IoTStateObservation elements.
Collections of objects – The arrays
Lists, or collections, of objects are provided within a wrapper element at the root level.
Each collection wrapper can have an arbitrary number of child elements of the specific type. The wrappers do not have any additional elements or attributes.