Revision for “Content Model” created on May 20, 2015 @ 09:08:53
| Title | Content Model |
|---|---|
| Content | <h2>Overview</h2>
The IoTEntity XML content model is a representation of an <a title="Glossary & References" href="http://www.iotworldservices.com/wiki/iotworldserviceswiki/glossary-references/" data-cke-saved-href="default.asp?W88">IoTEntity </a>and its properties, a serialization that can be used as payload in an <a title="Events – Content Model" href="http://www.iotworldservices.com/wiki/iotworldserviceswiki/events-content-model/" data-cke-saved-href="default.asp?W89">Event </a>and as result and body of the <a title="The RESTful API" href="http://www.iotworldservices.com/wiki/iotworldserviceswiki/getting-and-setting-data-for-iotentities-using-events-and-rest/the-restful-api/" data-cke-saved-href="default.asp?W86">RESTful API</a>'s GET and POST operations. The content model is formally defined as an <a title="LinkSmart XML Schema" href="http://www.iotworldservices.com/wiki/iotworldserviceswiki/linksmart-xml-schema/" data-cke-saved-href="default.asp?W90">XML Schema that is available for download</a>.
When used as part of the RESTful API, the IoTEntity model can be accessed on five different levels:
<ol>
<li><strong>IoTEntity </strong>- Represents an entity as a whole. This level is also used in Event messages.</li>
<li><strong>IoTProperty </strong>- An individual property of an entity identified by the URI in the request.</li>
<li><strong>ArrayOfIoTEntity </strong>- A list, or collection, of IoTEntity elements.</li>
<li><strong>ArrayOfIoTProperty </strong>- A list, or collection, of IoTProperty elements of an entity identified by the URI in the request.</li>
<li><strong>ArrayOfStateObservations</strong> - A list, or collection, of IoTStateObservation elements of a property of an entity, identified by the URI in the request</li>
</ol>
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.
<h2>Element: IoTEntity</h2>
Entity objects are represented by IoTEntity elements with the following content model:
<img class="alignnone" src="https://fogbugz.cnet.se/default.asp?pg=pgDownload&pgType=pgWikiAttachment&ixAttachment=314&sFileName=IoTEntityContentModel.png" alt="" width="425" height="526" />
<i><span lang="EN-GB">Figure</span></i><i><span lang="EN-GB">: The IoTEntity content model</span></i>
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 <strong>MUST </strong>be used for providing a globally unique identifier of the entity. See the <a href="https://fogbugz.cnet.se/default.asp?W92" data-cke-saved-href="default.asp?W92">RDFa in LinkSmart section</a> 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 <strong>MUST</strong> 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.
<h2>Element: IoTProperty</h2>
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.
<img title="" src="https://fogbugz.cnet.se/default.asp?pg=pgDownload&pgType=pgWikiAttachment&ixAttachment=315&sFileName=IoTPropertyContentModel.png" alt="" border="0" />
<em>Figure: The IoTProperty content model</em>
Similar to the IoTEntity, also IoTProperty is using the same set of RDFa attributes @about, @prefix, @xml:base and @typeof.
The @about attribute <strong>MUST </strong>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 <strong>MUST </strong>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 <strong>SHOULD </strong>be used to record the datatype of the data value of the property recorded within the child IoTStateObservation/Value element. It is <strong>RECOMMENDED </strong>to use XML Schema datatypes such as 'xs:datetime' where the prefix 'xs' must be defined using the @prefix attribute.
See the <a href="https://fogbugz.cnet.se/default.asp?W92" data-cke-saved-href="default.asp?W92">RDFa in LinkSmart section</a> 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 <strong>MUST </strong>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 <strong>MUST </strong>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 <a href="https://fogbugz.cnet.se/default.asp?W88" data-cke-saved-href="default.asp?W88">Glossary </a>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.
<img title="" src="https://fogbugz.cnet.se/default.asp?pg=pgDownload&pgType=pgWikiAttachment&ixAttachment=311&sFileName=IoTStateObservationContentModel.png" alt="" border="0" />
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.
<h2>Example: A Farm Field entity</h2>
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
<a href="http://www.iotworldservices.com/wp-content/uploads/2014/11/iotentityXMLexample.png"><img class="alignnone size-medium wp-image-887" src="http://www.iotworldservices.com/wp-content/uploads/2014/11/iotentityXMLexample-300x154.png" alt="iotentityXMLexample" width="300" height="154" /></a>
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.
<h2>Collections of objects - The arrays</h2>
Lists, or collections, of objects are provided within a wrapper element at the root level.
<img title="" src="https://fogbugz.cnet.se/default.asp?pg=pgDownload&pgType=pgWikiAttachment&ixAttachment=317&sFileName=ArrayOfxContentModel.png" alt="" border="0" />
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.
|
| Excerpt |