Better documentation

The present document is the technical specification of SAREF4ENVI, an extension of SAREF [[1]](#[1]) for the environment domain. The extension was created in collaboration with domain experts in the field of light pollution currently working in the STARS4ALL European H2020 project ([http://www.stars4all.eu/index.php/lpi/](http://www.stars4all.eu/index.php/lpi/)). The STARS4ALL project is composed by partners such as Universidad Politécnica de Madrid, Universidad Complutense de Madrid, ESCP Europe, Leibniz Institute of Freshwater Ecology and Inland Fisheries, Instituto de Astrofísica de Canarias, University of Southampton, Europan Crowdfunding Network, and CEFRIEL (Società Consortile a Responsabilita Limitata).

SAREF4ENVI has two main aims: on the one hand, to be the basis for enabling the use of SAREF in the environment domain and, on the other hand, to exemplify how to enable interoperability between environmental devices in cooperation.

SAREF4ENVI is an OWL-DL ontology that extends SAREF with 32 classes (24 defined in SAREF4ENVI and 7 reused from the time, SAREF and geo ontologies), 24 object properties (22 defined in SAREF4ENVI and 2 reused from the SAREF and geo ontologies), 13 data type properties (9 defined in SAREF4ENVI and 4 reused from the SAREF ontology), and 24 individuals (9 defined in SAREF4ENVI and 12 reused from the OM ontology). SAREF4ENVI focuses on extending SAREF for photometers to solve the lack of interoperability between sensors that can measure and share information about light pollution. Such extension involves the following use cases (more details can be found in ETSI TR 103 411 [[i.1]](#[i.1])):

- Use case 1: Monitor light pollution in a city, through the data collected by photometers about the magnitude of the light emitted in a given area.

- Use case 2: Adjust lampposts light intensity due to high pollution, after identifying the most contaminating lampposts and therefore the areas where more energy is being thrown away.

- Use case 3: Register a photometer, in which a new collection of photometers is incorporated into an existing sensor network.

The editors would like to thank the ETSI SmartM2M technical committee for providing guidance and expertise.

Also, many thanks to the ETSI staff and all other current and former active Participants of the ETSI SmartM2M group for their support, technical input and suggestions that led to improvements to this ontology.

Also, special thanks goes to the ETSI SmartM2M Technical Officer Guillemin Patrick for his help.

- [Maria Poveda-Villalon](https://w3id.org/people/mpoveda/) ([Universidad Politécnica de Madrid](http://www.oeg-upm.net/))

- [Raúl Garcia-Castro](http://www.garcia-castro.com/foaf.rdf#me) ([Universidad Politécnica de Madrid](http://www.oeg-upm.net/))

 No newline at end of file

<h3>General Overview</h3>

<p>A graphical overview of the SAREF4ENVI ontology is provided in <a href="#Figure_1">Figure 1</a>.</p>

<p>In such figure, grey rectangles are used to denote classes created in the ontology while white rectangles denote reused classes. For all the entities, it is indicated whether they are defined in the extension or in other ontologies by the prefix included before their identifier, that is, if the element is defined in SAREF4ENVI there is no prefix added and if the element is reused from another ontology it is indicated by a prefix according to the <a href="#namespacedeclarations">Namespace Declarations</a> section.</p>

<p>Arrows are used represent properties between classes and to represent some RDF, RDF-S and OWL constructs, more precisely:</p>

<ul>

  <li>Plain arrows with white triangles represent the <a href="https://www.w3.org/TR/rdf-schema/#ch_subclassof">rdfs:subClassOf</a> relation between two classes. The origin of the arrow is the class to be declared as subclass of the class at the destination of the arrow.</li>

  <li>Dashed arrows between two classes indicate a local restriction in the origin class, i.e. that the object property can be instantiated between the classes in the origin and the destination of the arrow. The identifier of the object property is indicated within the arrow.</li>

  <li>Dashed arrows with identifiers between stereotype signs (i.e. "<< >>") refer to OWL constructs that are applied to some ontology elements, that is, they can be applied to classes or properties depending on the OWL construct being used.</li>

  <li>Dashed arrows with no identifier are used to represent the <a href="https://www.w3.org/TR/rdf-schema/#ch_type">rdf:type</a> relation, indicating that the element in the origin of the arrow is an instance of the class in the destination of the arrow.</li>

</ul>

<p>Datatype properties are denoted by rectangles attached to the classes, in an UML-oriented way. Dashed boxes represent local restrictions in the class, i.e. datatype properties that can be applied to the class it is attached to.</p>

<p>Individuals are denoted by grey rectangles (or white ones in the case of being reused from other ontologies) in which the identifier is underlined.</p>

<p>The representation of additional property axioms (functional, inverse functional, transitive, and symmetric) that are being used in the diagram is shown in the legend of <a href="#Figure_1">Figure 1</a>.</p>

<p>Clause 4.2.2 to clause 4.2.7 describe the different parts of the SAREF4ENVI extension describing the different conceptual modules of the ontology.</p>

<figure>

  <a href="diagrams/Overview.png"><img src="diagrams/Overview.png" alt="SAREF4ENVI overview"/></a>

  <figcaption id="Figure_1">Figure 1: SAREF4ENVI overview</figcaption>

</figure>

<h3>Physical Object Hierarchy</h3>

<p>In SAREF4ENVI, the SAREF ontology has been extended with various elements to describe different physical objects, devices, and their characteristics.</p>

<p>Apart from extending the <a href="https://saref.etsi.org/core/Device">saref:Device</a> class with the <a href="#s4envi:Device">s4envi:Device</a> class, a hierarchy has been defined also including the classes <a href="#s4envi:PhysicalObject">s4envi:PhysicalObject</a>, <a href="#s4envi:System">s4envi:System</a> and <a href="#s4envi:Actuator">s4envi:Actuator</a> in the upper levels. In order to represent sensors from the light pollution domain, the classes <a href="#s4envi:Photometer">s4envi:Photometer</a> and <a href="#s4envi:TESS">s4envi:TESS</a> (a specific type of photometer) have been included extending the hierarchy. Such classes are organized in the hierarchy shown in <a href="#Figure_2">Figure 2</a>.</p>

<figure>

  <a href="diagrams/Hierarchy.png"><img src="diagrams/Hierarchy.png" alt="Physical Object hierarchy"/></a>

  <figcaption id="Figure_2">Figure 2: Physical Object hierarchy</figcaption>

</figure>

<h3>Devices and Measurements</h3>

<p>Devices and measurements are depicted in <a href="#Figure_3">Figure 3</a>. This model represents an n-ary pattern that allows users to relate different measurements from a given sensor for different properties measured in different units. That is, the <a href="https://saref.etsi.org/core/Measurement">saref:Measurement</a> class aims at describing a measurement of a physical quantity (using the <a href="https://saref.etsi.org/core/hasValue">saref:hasValue</a> property) for a given <a href="https://saref.etsi.org/core/Property">saref:Property</a> and according to a given <a href="https://saref.etsi.org/core/UnitOfMeasure">saref:UnitOfMeasure</a>.</p>

<p>This pattern enables to differentiate between properties and the measurements made for such properties and to store measurements for a concrete property in different units of measurement.</p>

<p>Furthermore, it allows adding a timestamp (using the <a href="https://saref.etsi.org/core/hasTimeStamp">saref:hasTimeStamp</a> property) to identify when the measurement applies to the property, which can be used either for single measurements or for series of measurements (e.g. measurement streams).</p>

<p>It is worth noting that this modelling was included in SAREF 2.0 after the SAREF4ENVI extension was developed. This pattern was first included in the SAREF4ENVI and SAREF4BLDG extensions and then proposed to be extrapolated to SAREF 2.0; this explains why the prefix used for this part of the model refers to SAREF instead of to SAREF4ENVI. However, as its origin is in the SAREF4ENVI and SAREF4BLDG extensions requirements and models, the explanations are kept in the present document.</p>

<figure>

  <a href="diagrams/Sensor.png"><img src="diagrams/Sensor.png" alt="Sensor and measurement model"/></a>

  <figcaption id="Figure_3">Figure 3: Sensor and measurement model</figcaption>

</figure>

<h3>Devices</h3>

<p><a href="#Figure_4">Figure 4</a> represents the <a href="#s4envi:Device">s4envi:Device</a> class which is extended from <a href="https://saref.etsi.org/core/Device">saref:Device</a>; therefore, the new class inherits the properties defined in the SAREF ontology for <a href="https://saref.etsi.org/core/Device">saref:Device</a>, such as <a href="https://saref.etsi.org/core/hasManufacturer">saref:hasManufacturer</a>. In addition, the class has been complemented with the properties <a href="#s4envi:hasFrequencyMeasurement">s4envi:hasFrequencyMeasurement</a> and <a href="#s4envi:hasTransmissionPeriod">s4envi:hasTransmissionPeriod</a> in order to model the frequency with which a device makes measurements and its period for transmitting such measurements. Both relationships are represented by n-ary relationships modelled by the classes <a href="#s4envi:FrequencyMeasurement">s4envi:FrequencyMeasurement</a> and <a href="#s4envi:PeriodMeasurement">s4envi:PeriodMeasurement</a>, which are subclasses of <a href="https://saref.etsi.org/core/Measurement">saref:Measurement</a>. The specific value for the frequency and the period is indicated by the datatype property <a href="https://saref.etsi.org/core/hasValue">saref:hasValue</a> , which is inherited from the class <a href="https://saref.etsi.org/core/Measurement">saref:Measurement</a>.</p>

<p>As the temporal units of measurement are already defined in SAREF by means of the class time:TemporalUnit, there has been no need for defining new units for <a href="#s4envi:PeriodMeasurement">s4envi:PeriodMeasurement</a>. However, new units of measurement are needed to represent frequencies; therefore, <a href="https://saref.etsi.org/core/UnitOfMeasure">saref:UnitOfMeasure</a> class has been extended with the class <a href="#s4envi:FrequencyUnit">s4envi:FrequencyUnit</a>, including the main instances from the OM units of measurement ontology to measure frequency, such as om:hertz, om:reciprocal_second-time, om:reciprocal_hour, om:reciprocal_day, and om:reciprocal_year. It is worth noting that the user is free to use other units of measurement if required.</p>

<p>Finally, <a href="#s4envi:Actuator">s4envi:Actuator</a> has been added according to the domain expert requirements in order to represent devices that can act (<a href="#s4envi:affectsProperty">s4envi:affectsProperty</a>) over properties as shown in <a href="#Figure_4">Figure 4</a>.</p>

<figure>

  <a href="diagrams/Device.png"><img src="diagrams/Device.png" alt="Device model"/></a>

  <figcaption id="Figure_4">Figure 4: Device model</figcaption>

</figure>

<h3>Systems and Physical Objects</h3>

<p>As already observed in <a href="#Figure_2">Figure 2</a>, according to the requirements extracted from uses cases and domain experts, it was necessary to include more general information about systems and physical objects, which are superclasses of devices, in order to provide a general framework for representing communications, componency, and digital representations. This section focuses on these additional classes included in SAREF4ENVI that model how to access physical objects and their components.</p>

<p><a href="#Figure_5">Figure 5</a> represents the class <a href="#s4envi:System">s4envi:System</a> and its properties. It can observed that a system can be composed of other systems and this is represented by the property <a href="#s4envi:hasComponent">s4envi:hasComponent</a> and its inverse <a href="#s4envi:isComponentOf">s4envi:isComponentOf</a>. A system can also be connected to other systems, represented by the <a href="#s4envi:isConnectedTo">s4envi:isConnectedTo</a> property.</p>

<p>The communication protocol and interface that a system might use are represented by the classes <a href="#s4envi:CommunicationProtocol">s4envi:CommunicationProtocol</a> and <a href="#s4envi:CommunicationInterface">s4envi:CommunicationInterface</a>, respectively.</p>

<figure>

  <a href="diagrams/System.png"><img src="diagrams/System.png" alt="System model"/></a>

  <figcaption id="Figure_5">Figure 5: System model</figcaption>

</figure>

<p>The model represented in <a href="#Figure_6">Figure 6</a> supports the representation of services that allow the access to digital representations of a given physical object (e.g. devices, sensors, etc.). The main entity in this model is <a href="#s4envi:PhysicalObject">s4envi:PhysicalObject</a> that represents a general class for devices and systems and any other entity with a physical representation in order to make the model extensible to other domains. Such object can have digital representations (<a href="#s4envi:DigitalRepresention">s4envi:DigitalRepresention</a>) that can be accessed through services (<a href="https://saref.etsi.org/core/Service">saref:Service</a>).</p>

<p>In addition, the digital representation can be linked back to the physical object that it encapsulates by means of the property <a href="#s4envi:encapsulates">s4envi:encapsulates</a>, defined as inverse of <a href="#s4envi:hasDigitalRepresentation">s4envi:hasDigitalRepresentation</a>. It is worth noting that <a href="#s4envi:hasDigitalRepresentation">s4envi:hasDigitalRepresentation</a> is defined as inverse functional since a digital representation can encapsulate only one object.</p>

<p>Finally, the relation between a physical object and its location is represented by the reused property geo:location. In addition, <a href="#s4envi:PhysicalObject">s4envi:PhysicalObject</a> is declared to be subclass of geo:SpatialThing.</p>

<figure>

  <a href="diagrams/PhysicalObject.png"><img src="diagrams/PhysicalObject.png" alt="Physical object and digital representation model"/></a>

  <figcaption id="Figure_6">Figure 6: Physical object and digital representation model</figcaption>

</figure>

<h3>Photometers</h3>

<p>A photometer, in general, is an instrument that measures light intensity or optical properties of solutions or surfaces. In general a <a href="#s4envi:Photometer">s4envi:Photometer</a> is an entity that observes some <a href="#s4envi:LightProperty">s4envi:LightProperty</a>, in a way of paraphrasing the axiom shown in <a href="#Figure_7">Figure 7</a>. In such figure, it can also be observed that a particular case of photometer is a <a href="#s4envi:TESS">s4envi:TESS</a> (Telescope Encoder and Sky Sensor). It is worth noting that other particular photometers could be added by extending the <a href="#s4envi:Photometer">s4envi:Photometer</a> class when reusing this extension.</p>

<p>Furthermore, <a href="#Figure_7">Figure 7</a> also shows the main light properties that can be observed by a photometer. These properties are represented as instances, for example <a href="#s4envi:Luminiscence">s4envi:Luminiscence</a>, of the class <a href="#s4envi:LightProperty">s4envi:LightProperty</a>.</p>

<figure>

  <a href="diagrams/Photometers.png"><img src="diagrams/Photometers.png" alt="Photometer and light property model"/></a>

  <figcaption id="Figure_7">Figure 7: Photometer and light property model</figcaption>

</figure>

<h3>Lampposts, Light Points and Light</h3>

<p><a href="#Figure_8">Figure 8</a> represents the model to represent lampposts and their possible light points using the classes <a href="#s4envi:Lamppost">s4envi:Lamppost</a> and <a href="#s4envi:LightPoint">s4envi:LightPoint</a>. It can also be indicated that a lamppost can have one or more light points by using the <a href="#s4envi:hasLightPoint">s4envi:hasLightPoint</a> object property. </p>

<p>In this model both lampost and light points are allowed to be agents that project light (represented by the property <a href="#s4envi:projectsLight">s4envi:projectsLight</a>). In this sense, one lamppost could directly project light or in a more complex scenario a lamppost could have different light points being these light points in charge of projecting the light.</p>

<p>Finally, <a href="#s4envi:LightPoint">s4envi:LightPoint</a> has been defined as subclass of geo:Point as it is a point located in a given space and it can inherit the mechanism to express its latitude, altitude and longitude from geo:Point.</p>

<figure>

  <a href="diagrams/Lamppost.png"><img src="diagrams/Lamppost.png" alt="Lamppost and light point model"/></a>

  <figcaption id="Figure_8">Figure 8: Lamppost and light point model</figcaption>

</figure>

<p>The model depicted in <a href="#Figure_9">Figure 9</a> represents the light characteristics. It can be observed that a light is projected in a certain angle, in a given direction and from a given height, represented by the properties <a href="#s4envi:hasProjectionAngle">s4envi:hasProjectionAngle</a> (datatype property), <a href="#s4envi:isProjectedInDirection">s4envi:isProjectedInDirection</a> (object property) and <a href="#s4envi:isProjectedFromHeight">s4envi:isProjectedFromHeight</a> (object property), respectively.</p>

<p>The angle is represented by a float indicating the degrees of the cone of light that the light emits. Besides, the direction can be represented by instances of the class <a href="#s4envi:CompassDirection">s4envi:CompassDirection</a> that could represent values such as North, South, Northwest, etc.</p>

<p>The height from which a light is projected is modelled as a subclass of <a href="https://saref.etsi.org/core/Measurement">saref:Measurement</a>, namely <a href="#s4envi:HeightMeasurement">s4envi:HeightMeasurement</a>, as in this case it is necessary to indicate the value of such measure, inherited from <a href="https://saref.etsi.org/core/Measurement">saref:Measurement</a>, and the unit of measurement used. That is, an n-ary pattern is used here.</p>

<p>The colour of the light emitted is represented by the objet property <a href="#s4envi:hasColor">s4envi:hasColor</a> and its values should be instantiated as individuals of the class <a href="#s4envi:Color">s4envi:Color</a>. Similarly, the geometry of a light can be indicated by means of the <a href="#s4envi:hasGeometry">s4envi:hasGeometry</a> object property and its values would belong to the class <a href="#s4envi:Geometry">s4envi:Geometry</a>.</p>

<p>Finally, it could be indicated whether a light has a flash by using the <a href="#s4envi:hasFlash">s4envi:hasFlash</a> datatype property.</p>

<figure>

  <a href="diagrams/Light.png"><img src="diagrams/Light.png" alt="Light model"/></a>

  <figcaption id="Figure_9">Figure 9: Light model</figcaption>

</figure>

<h3>Observations about S4ENVI</h3>

<p>In the following, several observations about potential uses of the SAREF4ENVI ontology are listed.</p>

<p>First of all, it is worth reminding here that a TESS is an example of a particular photometer, other photometers could be included by extending the class <a href="#s4envi:Photometer">s4envi:Photometer</a>.</p>

<p>In addition, in order to include other physical objects or devices related to environmental measurements in other use cases, the different classes included in the ontology could be extended. For example, <a href="#s4envi:Photometer">s4envi:Photometer</a> should be extended to represent CO2 sensors; in that case, the <a href="https://saref.etsi.org/core/Property">saref:Property</a> hierarchy should be extended with the properties that CO2 sensors might measure following the guidelines presented in this extension.</p>