better documentation

The present document is a technical specification of SAREF4BLDG, an extension of the SAREF ontology [[1]](#[1]) that was created based on the Industry Foundation Classes (IFC) standard for building information. It should be noted that not the whole standard has been transformed since it exceeds the scope of this extension, which is limited to devices and appliances within the building domain. 

The IFC specification is developed and maintained by buildingSMART International as its "Data standard" and, since its version IFC4, it is published as the ISO 16739 [[i.2]](#[i.2]) standard. SAREF4BLDG is meant to enable the (currently missing) interoperability among various actors (architects, engineers, consultants, contractors, and product component manufacturers, among others) and applications managing building information involved in the different phases of the building life cycle (Planning and Design, Construction, Commissioning, Operation, Retrofitting/Refurbishment/Reconfiguration, and Demolition/Recycling). By using SAREF4BLDG, smart appliances from manufacturers that support the IFC data model will easily communicate with each other. Towards this aim, SAREF4BLDG should be used to annotate (or generate) neutral device descriptions to be shared among various stakeholders. 

SAREF4BLDG is an OWL-DL ontology that extends SAREF with 72 classes (67 defined in SAREF4BLDG and 5 reused from the SAREF and geo ontologies), 179 object properties (177 defined in SAREF4BLDG and 2 reused from the SAREF and geo ontologies), and 83 data type properties (82 defined in SAREF4BLDG and 1 reused from the SAREF ontology). 

SAREF4BLDG focuses on extending the SAREF ontology to include those devices defined by the IFC version 4 - Addendum 1 [[i.3]](#[i.3]) and to enable the representation of such devices and other physical objects in building spaces.

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/))

<h3>General Overview</h3>

<p><a href="Figure_1">Figure 1</a> presents an overview of the classes (only the top levels of the hierarchy) and the properties included in the SAREF4BLDG extension. As it can be observed the classes <a href="#s4bldg:Building">s4bldg:Building</a>, <a href="#s4bldg:BuildingSpace">s4bldg:BuildingSpace</a> and <a href="#s4bldg:PhysicalObject">s4bldg:PhysicalObject</a> have been declared as subclasses of the class geo:SpatialThing in order to reuse the conceptualization for locations already proposed by the geo ontology. The modelling of building objects and building spaces has been adapted from the SAREF ontology; in this sense, the new classes deprecate the <a href="https://saref.etsi.org/core/BuildingObject">saref:BuildingObject</a> and <a href="https://saref.etsi.org/core/BuildingSpace">saref:BuildingSpace</a> classes. In addition, a new class has been created, the <a href="#s4bldg:Building">s4bldg:Building</a> class, to represent buildings.</p>

<p>The concepts <a href="#s4bldg:Building">s4bldg:Building</a> and <a href="#s4bldg:BuildingSpace">s4bldg:BuildingSpace</a> are related to each other by means of the properties <a href="#s4bldg:hasSpace">s4bldg:hasSpace</a> and <a href="#s4bldg:isSpaceOf">s4bldg:isSpaceOf</a>; such properties are defined as inverse properties among them. These properties might also be used to declare that a <a href="#s4bldg:BuildingSpace">s4bldg:BuildingSpace</a> has other spaces belonging to the class <a href="#s4bldg:BuildingSpace">s4bldg:BuildingSpace</a>.</p>

<p>The relationship between building spaces and devices and building objects has also been transferred and generalized from the SAREF ontology. In this regard, a <a href="#s4bldg:BuildingSpace">s4bldg:BuildingSpace</a> can contain (represented by the property <a href="#s4bldg:contains">s4bldg:contains</a>) individuals belonging to the class <a href="#s4bldg:PhysicalObject">s4bldg:PhysicalObject</a>. This generalization has been implemented in order to support building spaces to contain both building objects and devices. Accordingly, the classes <a href="#s4bldg:BuildingObject">s4bldg:BuildingObject</a> and <a href="https://saref.etsi.org/core/Device">saref:Device</a> are declared as subclasses of <a href="#s4bldg:PhysicalObject">s4bldg:PhysicalObject</a>.</p>

<p>Finally, the class representing building devices, namely <a href="#s4bldg:BuildingDevice">s4bldg:BuildingDevice</a>, is defined as a subclass of both <a href="https://saref.etsi.org/core/Device">saref:Device</a> and <a href="#s4bldg:BuildingObject">s4bldg:BuildingObject</a>. This class is a candidate for replacing the <a href="https://saref.etsi.org/core/BuildingRelated">saref:BuildingRelated</a> class.</p>

<figure>

  <a href="diagrams/Overview.png"><img src="diagrams/Overview.png" alt="General overview of the top levels of the SAREF4BLDG extension"/></a>

  <figcaption id="Figure_1">Figure 1: General overview of the top levels of the SAREF4BLDG extension</figcaption>

</figure>

<h3>Device Taxonomy</h3>

<p>The main contribution of this extension is the representation of the devices defined in the IFC standard and their connections to SAREF. In this sense, a hierarchy consisting in 62 classes has been created taking into account the subset of the IFC hierarchy related to devices, as defined in the buildingSMART documentation (https://standards.buildingsmart.org/IFC/RELEASE/IFC4/ADD1/HTML/annex/annex-c/common-use-definitions/index.htm), and adding several classes to clarify its categorization. The device classes are organized into 6 hierarchical levels that, for the sake of clarity, will be displayed in <a href="Figure_2">Figure 2</a> and <a href="Figure_3">Figure 3</a>. </p>

<p><a href="Figure_2">Figure 2</a> shows the first five levels of the hierarchy. Since transport elements (<a href="#s4bldg:TransportElement">s4bldg:TransportElement</a>) and vibration isolations (<a href="#s4bldg:VibrationIsolation">s4bldg:VibrationIsolation</a>) are not classified under IFC elements, they belong directly to the class <a href="#s4bldg:Device">s4bldg:Device</a>. The building elements are divided into <a href="#s4bldg:ShadingDevice">s4bldg:ShadingDevice</a> and <a href="#s4bldg:DistributionDevice">s4bldg:DistributionDevice</a>. In fact, most of the device types included in IFC belong to the distribution device category which contains the classes <a href="#s4bldg:DistributionControlDevice">s4bldg:DistributionControlDevice</a> and <a href="#s4bldg:DistributionFlowDevice">s4bldg:DistributionFlowDevice</a>. The hierarchy under the <a href="#s4bldg:DistributionFlowDevice">s4bldg:DistributionFlowDevice</a> is depicted in <a href="Figure_3">Figure 3</a>.</p>

<p>As can be observed in <a href="Figure_2">Figure 2</a>, some classes defined in SAREF4BLDG are also defined in the SAREF ontology. More precisely, this occurs in the classes <a href="#s4bldg:Actuator">s4bldg:Actuator</a> and <a href="#s4bldg:Sensor">s4bldg:Sensor</a> that extend the classes <a href="https://saref.etsi.org/core/Actuator">saref:Actuator</a> and <a href="https://saref.etsi.org/core/Sensor">saref:Sensor</a>, respectively. This decision has been taken because in the SAREF4BLDG extension these concepts refer to specific sensors and actuators that are placed in or related to buildings. </p>

<figure>

  <a href="diagrams/Hierarchy1.png"><img src="diagrams/Hierarchy1.png" alt="Device hierarchy in SAREF4BLDG (Part 1)"/></a>

  <figcaption id="Figure_2">Figure 2: Device hierarchy in SAREF4BLDG (Part 1)</figcaption>

</figure>

<figure>

  <a href="diagrams/Hierarchy2.png"><img src="diagrams/Hierarchy2.png" alt="Device hierarchy in SAREF4BLDG (Part 2)"/></a>

  <figcaption id="Figure_3">Figure 3: Device hierarchy in SAREF4BLDG (Part 2)</figcaption>

</figure>

<p>For each class extracted from the IFC specification, <a href="https://www.w3.org/TR/rdf-schema/#ch_label">rdfs:label</a> and <a href="https://www.w3.org/TR/rdf-schema/#ch_comment">rdfs:comment</a> annotations have been generated including the identifier and an excerpt of the definition provided in the IFC online documentation. In addition, provenance information has been included using the PROV-O ontology (https://www.w3.org/TR/prov-o/), which has been published by the W3C as recommendation. In our case, the property prov:hadPrimarySource is used to link each class with:</p>

(a) the online document in IFC describing the concept; and 

(b) the online document in IFC describing the properties defined for such concept. 

<p>It should be noted that properties are not specified in IFC for all the concepts but just for those representing particular devices. That is, there is no description of properties for the following general classes: </p>

- <a href="#s4bldg:EnergyConversionDevice">s4bldg:EnergyConversionDevice</a>, <a href="#s4bldg:FlowController">s4bldg:FlowController</a>, <a href="#s4bldg:FlowMovingDevice">s4bldg:FlowMovingDevice</a>, <a href="#s4bldg:FlowStorageDevice">s4bldg:FlowStorageDevice</a>, <a href="#s4bldg:FlowTerminal">s4bldg:FlowTerminal</a>, and <a href="#s4bldg:FlowTreatmentDevice">s4bldg:FlowTreatmentDevice</a>.

<p>In addition, the classes created in this extension have been related to the ifcOWL ontology (https://w3id.org/ifc/IFC4_ADD1) when possible. This relation has been declared by means of the annotation property <a href="https://www.w3.org/TR/rdf-schema/#ch_seealso">rdfs:seeAlso</a> from the SAREF4BLDG classes to the ifcOWL ones.</p>

<h3>Measurements</h3>

<p>Measurements are depicted in <a href="Figure_4">Figure 4</a>. This model represents an n-ary pattern that allows users to relate measurements for different properties that are 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 SAREF2.0 after the SAREF4BLDG 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 SAREF4BLDG. However, as its origin is the SAREF4ENVI and SAREF4BLDG extensions requirements and modellings, the explanations are kept in the present document.</p>

<figure>

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

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

</figure>

<h3>Device Properties</h3>

<p>In the SAREF4BLDG extension 179 object properties (177 defined in SAREF4BLDG and 2 reused from the SAREF and geo ontologies) and 83 datatype properties (82 defined in SAREF4BLDG and 1 reused from the SAREF ontology) have been included. 172 out the 179 object properties and 81 out of the 83 datatype properties have been created according to the IFC specification of properties for devices.</p>

<p>For each of the created object and datatype properties, their documentation from IFC has been attached as documentation, including information about their use, such as the expected units of measurement.</p>

<p>The naming of the created object and datatype properties is consistent with the naming used in IFC. More precisely, the names of the properties in the ontology are the names assigned in IFC transformed into Camel Case starting with lowercase. For example, the property "IdealShaftPower" (extracted from https://standards.buildingsmart.org/IFC/RELEASE/IFC4/ADD1/HTML/schema/ifchvacdomain/pset/pset_compressortypecommon.htm) has been transformed into the object property <a href="#s4bldg:idealShaftPower">s4bldg:idealShaftPower</a>.</p>

<h3>Observations about S4BLDG</h3>

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

<p>It should be mentioned that the range of the <a href="#s4bldg:shortCircuitVoltage">s4bldg:shortCircuitVoltage</a> object property is open to different representations of complex numbers. In this sense, when reusing the ontology users should define the class to be used to represent complex numbers or reuse an existing one.</p>

<p>In addition, the list of building devices should not be considered exhaustive, the current classification represents those devices described in IFC. It might be needed to extend the hierarchy in the case of new devices related to buildings are described in new versions of IFC or are needed for a particular use case.</p>

<p>Furthermore, it is expected that concrete use cases will either reuse the existing classes to represent their devices or specialize some of these classes to cover specific device types (e.g. by creating a hierarchy of boiler devices under the <a href="#s4bldg:Boiler">s4bldg:Boiler</a> class).</p>