Merge branch 'documentation-html' into 'develop-v2.1.1'

The present document is a technical specification of SAREF4CITY, an extension of SAREF [[1]](#[1]) for the Smart Cities domain. This extension has been created by investigating resources from potential stakeholders of the ontology, such as standardization bodies (e.g. Open Geospatial Consortium), associations (e.g. Spanish Federation of Municipalities and Provinces), IoT platforms (e.g. FIWARE) and European projects and initiatives (e.g. ISA2 programme) as reported in ETSI TR 103 506 [[i.1]](#[i.1]). In addition, the use cases defined in [[i.1]](#[i.1]) were also taken into account, namely:

The present document is a technical specification of SAREF4CITY, an extension of SAREF [[1]](#[1]) for the Smart Cities domain. 

SAREF4CITY V2.1.1 is a major revision of SAREF4CITY, using updated reference ontology patterns specified in ETSI TS 103 548 [2] to solve the harmonization needs identified in ETSI TR 103 781 [i.2], with updated development framework and tools defined in ETSI TS 103 673 [3].

This extension has been created by investigating resources from potential stakeholders of the ontology, such as standardization bodies (e.g. Open Geospatial Consortium), associations (e.g. Spanish Federation of Municipalities and Provinces), IoT platforms (e.g. FIWARE) and European projects and initiatives (e.g. ISA2 programme) as reported in ETSI TR 103 506 [[i.1]](#[i.1]). In addition, the use cases defined in [[i.1]](#[i.1]) were also taken into account, namely:

- Use case 1: eHealth and Smart Parking.

- Use case 2: Air Quality Monitoring and Mobility.

After the first complete implementation of the ontology, a second validation workshop, the "Towards interoperability and harmonization of Smart City models with SAREF4CITY" one, took place on the 22nd of November 2018 at the European Commission premises in Brussels. During the workshop the ontology was presented to a variety of stakeholders from industry to academia and public administration. Apart from observations and comments on the reuse and alignment with other ontologies, the discussion addressed more general questions like how to promote the adoption of SAREF or which is the technological and methodological support needed to create a SAREF ecosystem of collaborative ontologies.

SAREF4CITY is an OWL-DL ontology that extends SAREF and reuses six other ontologies. SAREF4CITY includes 31 classes (13 defined in SAREF4CITY and 18 reused from the SAREF, time, geosp, geo, foaf, dcterms, org, cpsv, and time ontologies), 36 object properties (20 defined in SAREF4CITY and 16 reused from the SAREF, geosp, geo, and cpsv ontologies) and 7 data type properties (3 defined in SAREF4CITY and 4 reused from the SAREF ontology).

The current version of the ontology, V2.1.1, represents the adaptation of the previous SAREF4CITY conceptualization according to the new SAREF core and the homogenization process across extensions.

SAREF4CITY is an OWL-DL ontology that extends SAREF and reuses seven other ontologies. SAREF4CITY includes 124 classes (13 defined in SAREF4CITY and 111 reused from the SAREF, time, sf, geo, foaf, dc, org, cpsv, skos and time ontologies), 103 object properties (18 defined in SAREF4CITY and 85 reused from the SAREF, geo, skos and cpsv ontologies) and 13 data type properties (6 defined in SAREF4CITY and 4 reused from the SAREF ontology).

SAREF4CITY focuses on extending SAREF in order to create a common core of general concepts for smart city data oriented to the IoT field. The main idea is to identify the core components, as mentioned, that could be extended for particular smart city subdomains, for example, for public transport.

<h3>Topology</h3>

<p>In the SAREF4CITY ontology existing models have been reused when needed in order to increase interoperability and reduce effort in modelling general domains. As an example, for modelling the requirements related to the topology domain, standard ontologies already developed have been reused and connected to the SARE4CITY elements. As shown in <a href="#Figure_2">Figure 2</a>, for representing spatial objects the geosp:SpatialObject class from GeoSPARQL has been reused along with its subclasses geosp:Feature, geosp:Geometry and the properties geosp:sfContains, geosp:sfWithin and geosp:hasGeometry. In addition, the class geo:Point and the property geo:location have been reused from the W3C de-facto standard for geographical information "WGS84 Geo Positioning vocabulary" in order to be able to indicate that something is located at certain coordinates.</p>

<p>In the SAREF4CITY ontology existing models have been reused when needed in order to increase interoperability and reduce effort in modelling general domains. As an example, for modelling the requirements related to the topology domain, standard ontologies already developed have been reused and connected to the SARE4CITY elements. As shown in <a href="#Figure_2">Figure 2</a>, for representing spatial objects the geo:SpatialObject class from GeoSPARQL has been reused along with its subclasses geo:Feature, geo:Geometry and the classes from the simple features ontology sf:Geometry and sf:Point and the properties geo:sfContains, geo:sfWithin and geo:hasGeometry.</p>

<figure>

<h3>Administrative Area</h3>

<p>The model defined to describe administrative areas is depicted in <a href="#Figure_3">Figure 3</a>. As it can be observed, this model heavily relies on the topology pattern described in clause 4.2.2. In this sense, the ability to connect administrative areas (e.g. a city) with their inner areas, (e.g. its neighbourhoods) is given by inheritance of the geosp:SpatialObject class and through the geosp:Feature class. That is, as <a href="#s4city:AdministrativeArea">s4city:AdministrativeArea</a> is subclass of geosp:SpatialObject, the geosp:sfContains and geosp:sfWithin properties could also be applied to all the administrative areas defined, namely <a href="#s4city:City">s4city:City</a>, <a href="#s4city:Country">s4city:Country</a>, <a href="#s4city:District">s4city:District</a> and <a href="#s4city:Neighbourhood">s4city:Neighbourhood</a>.</p>

<p>The model defined to describe administrative areas is depicted in <a href="#Figure_3">Figure 3</a>. As it can be observed, this model heavily relies on the topology pattern described in clause 4.2.2. In this sense, the ability to connect administrative areas (e.g. a city) with their inner areas, (e.g. its neighbourhoods) is given by inheritance of the geo:SpatialObject class and through the geo:Feature class. That is, as <a href="#s4city:AdministrativeArea">s4city:AdministrativeArea</a> is subclass of geo:SpatialObject, the geo:sfContains and geo:sfWithin properties could also be applied to all the administrative areas defined, namely <a href="#s4city:City">s4city:City</a>, <a href="#s4city:Country">s4city:Country</a>, <a href="#s4city:District">s4city:District</a> and <a href="#s4city:Neighbourhood">s4city:Neighbourhood</a>.</p>

<figure>

  <a href="diagrams/AdministrativeArea.png"><img src="diagrams/AdministrativeArea.png" alt="Administrative Area model"/></a>

<h3>City Object</h3>

<p>The model developed to represent city objects is shown in <a href="#Figure_4">Figure 4</a>. This model also relies on the topology pattern described in clause 4.2.2, as for the administrative area case. The ability to connect city objects with the city or with the parts in which they are located is enabled by means of the properties geosp:sfContains and geosp:sfWithin inherited from the geosp:SpatialObject class.</p>

<p>The model developed to represent city objects is shown in <a href="#Figure_4">Figure 4</a>. This model also relies on the topology pattern described in clause 4.2.2, as for the administrative area case. The ability to connect city objects with the city or with the parts in which they are located is enabled by means of the properties geo:sfContains and geo:sfWithin inherited from the geo:SpatialObject class.</p>

<figure>

  <a href="diagrams/CityObject.png"><img src="diagrams/CityObject.png" alt="City Object model"/></a>

</figure>

<h3>Measurement</h3>

<p>As it can be observed in <a href="#Figure_6">Figure 6</a>, the modelling of measurements in the SAREF4CITY ontology totally relies on the measurement model proposed in SAREF. This modelling includes the <a href="https://saref.etsi.org/core/FeatureOfInterest">saref:FeatureOfInterest</a> class that provides the means to refer to the real world phenomena that is being observed in the given measurement. In order to reduce duplication with SAREF documentation, the reader is referred to the SAREF specification for details about SAREF modelling including here details only for the new concepts.</p>

<figure>

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

  <figcaption id="Figure_6">Figure 6: Measurement model</figcaption>

</figure>

<h3>Observation</h3>

<p>The modelling of observation in the SAREF4CITY ontology totally relies on the observation model proposed in SAREF. This modelling includes the <a href="https://saref.etsi.org/core/FeatureOfInterest">saref:FeatureOfInterest</a> class that provides the means to refer to the real world phenomena that is being observed in the given measurement. In order to reduce duplication with SAREF documentation, the reader is referred to the SAREF specification for details about SAREF modelling including here details only for the new concepts.</p>

<h3>Key Performance Indicator</h3>

<a href="#Figure_7">Figure 7</a> provides an overview of the modelling of Key Performance Indicators (KPI). The KPI modelling involves two main concepts, namely <a href="#s4city:KeyPerformanceIndicator">s4city:KeyPerformanceIndicator</a> and <a href="#s4city:KeyPerformanceIndicatorAssessment">s4city:KeyPerformanceIndicatorAssessment</a>. This distinction is needed to decouple the definition of a KPI in general terms, for example the mean air pollution per week, and a particular value of such KPI, for example the mean value of air pollution last week in Madrid.

<a href="#Figure_6">Figure 6</a> provides an overview of the modelling of Key Performance Indicators (KPI). The KPI modelling involves two main concepts, namely <a href="#s4city:KeyPerformanceIndicator">s4city:KeyPerformanceIndicator</a> and <a href="#s4city:KeyPerformanceIndicatorAssessment">s4city:KeyPerformanceIndicatorAssessment</a>. This distinction is needed to decouple the definition of a KPI in general terms, for example the mean air pollution per week, and a particular value of such KPI, for example the mean value of air pollution last week in Madrid.

<p>A <a href="#s4city:KeyPerformanceIndicator">s4city:KeyPerformanceIndicator</a> is related to a <a href="https://saref.etsi.org/core/FeatureOfInterest">saref:FeatureOfInterest</a> by means of the property <a href="#s4city:isKPIOf">s4city:isKPIOf</a>. It should be noted that the inverse relation of <a href="#s4city:isKPIOf">s4city:isKPIOf</a> is also defined, more precisely, the relation <a href="#s4city:hasKPI">s4city:hasKPI</a> links a given <a href="https://saref.etsi.org/core/FeatureOfInterest">saref:FeatureOfInterest</a> to its KPIs represented as instances of <a href="#s4city:KeyPerformanceIndicator">s4city:KeyPerformanceIndicator</a>. The calculation period of a <a href="#s4city:KeyPerformanceIndicator">s4city:KeyPerformanceIndicator</a> is indicated by the property <a href="#s4city:hasCalculationPeriod">s4city:hasCalculationPeriod</a>. The name and a natural language description of the <a href="#s4city:KeyPerformanceIndicator">s4city:KeyPerformanceIndicator</a> are indicated by the attributes <a href="#s4city:hasName">s4city:hasName</a> and <a href="#s4city:hasDescription">s4city:hasDescription</a>, respectively.</p>

<p>The relation between a specific assessment of a KPI (<a href="#s4city:KeyPerformanceIndicatorAssessment">s4city:KeyPerformanceIndicatorAssessment</a>) and the general KPI definition (<a href="#s4city:KeyPerformanceIndicator">s4city:KeyPerformanceIndicator</a>) can be established by means of the property <a href="#s4city:quantifiesKPI">s4city:quantifiesKPI</a>. A <a href="#s4city:KeyPerformanceIndicatorAssessment">s4city:KeyPerformanceIndicatorAssessment</a> is related to the <a href="https://saref.etsi.org/core/FeatureOfInterest">saref:FeatureOfInterest</a> by means of the property <a href="#s4city:assesses">s4city:assesses</a>. The temporal entity to which the assessment of the KPI refers to is represented by the property <a href="#s4city:refersToTime">s4city:refersToTime</a>. The agent assessing the KPI is linked by means of the property <a href="#s4city:isAssessedBy">s4city:isAssessedBy</a>. In order to express the administrative area or geographical location assessed by the KPI, the property <a href="#s4city:refersToSpace">s4city:refersToSpace</a> is included in the model. In case the KPI represents a value extracted from an aggregation of measurements, the property <a href="#s4city:isDerivedFrom">s4city:isDerivedFrom</a> can be used to link to such measurements (<a href="https://saref.etsi.org/core/Measurement">saref:Measurement</a>). The unit of measure in which a KPI value is expressed is indicated by means of the reused property <a href="https://saref.etsi.org/core/isMeasuredIn">saref:isMeasuredIn</a> while the value itself is indicated by the attribute <a href="https://saref.etsi.org/core/hasValue">saref:hasValue</a>. The name and a natural language description of the <a href="#s4city:KeyPerformanceIndicatorAssessment">s4city:KeyPerformanceIndicatorAssessment</a> are indicated by the attributes <a href="#s4city:hasName">s4city:hasName</a> and <a href="#s4city:hasDescription">s4city:hasDescription</a>, respectively. The creation, expiration and last update dates of the value are represented by the attributes <a href="#s4city:hasCreationDate">s4city:hasCreationDate</a>, <a href="#s4city:hasExpirationDate">s4city:hasExpirationDate</a> and <a href="#s4city:hasLastUpdateDate">s4city:hasLastUpdateDate</a>, respectively.</p>

<p>The relation between a specific assessment of a KPI (<a href="#s4city:KeyPerformanceIndicatorAssessment">s4city:KeyPerformanceIndicatorAssessment</a>) and the general KPI definition (<a href="#s4city:KeyPerformanceIndicator">s4city:KeyPerformanceIndicator</a>) can be established by means of the property <a href="#s4city:quantifiesKPI">s4city:quantifiesKPI</a>. A <a href="#s4city:KeyPerformanceIndicatorAssessment">s4city:KeyPerformanceIndicatorAssessment</a> is related to the <a href="https://saref.etsi.org/core/FeatureOfInterest">saref:FeatureOfInterest</a> by means of the property <a href="#s4city:assesses">s4city:assesses</a>. The temporal entity to which the assessment of the KPI refers to is represented by the property <a href="#s4city:refersToTime">s4city:refersToTime</a>. The agent assessing the KPI is linked by means of the property <a href="#s4city:isAssessedBy">s4city:isAssessedBy</a>. In order to express the administrative area or geographical location assessed by the KPI, the property <a href="#s4city:refersToFeature">s4city:refersToFeature</a> is included in the model. In case the KPI represents a value extracted from an aggregation of observations, the property <a href="#s4city:isDerivedFrom">s4city:isDerivedFrom</a> can be used to link to such observations (<a href="https://saref.etsi.org/core/Observation">saref:Observation</a>). The unit of measure in which a KPI value is expressed is indicated by means of the reused property <a href="https://saref.etsi.org/core/isMeasuredIn">saref:isMeasuredIn</a> while the value itself is indicated by the attribute <a href="https://saref.etsi.org/core/hasValue">saref:hasValue</a>. The name and a natural language description of the <a href="#s4city:KeyPerformanceIndicatorAssessment">s4city:KeyPerformanceIndicatorAssessment</a> are indicated by the attributes <a href="#s4city:hasName">s4city:hasName</a> and <a href="#s4city:hasDescription">s4city:hasDescription</a>, respectively. The creation, expiration and last update dates of the value are represented by the attributes <a href="#s4city:hasCreationDate">s4city:hasCreationDate</a>, <a href="#s4city:hasExpirationDate">s4city:hasExpirationDate</a> and <a href="#s4city:hasLastUpdateDate">s4city:hasLastUpdateDate</a>, respectively.</p>

<figure>

  <a href="diagrams/KPI.png"><img src="diagrams/KPI.png" alt="Key Performance Indicator model"/></a>

  <figcaption id="Figure_7">Figure 7: Key Performance Indicator model</figcaption>

  <figcaption id="Figure_6">Figure 6: Key Performance Indicator model</figcaption>

</figure>

<h3>Public Service</h3>

<p>The model developed to describe public services within the SAREF4CITY ontology is depicted in <a href="#Figure_8">Figure 8</a>. The main entity included is the <a href="#s4city:PublicService">s4city:PublicService</a> class which is a specialization of the reused concept cpsv:PublicService class defined in the Public Service vocabulary provided by the ISA vocabularies European initiative. The facility in which the service is provided is indicated by the <a href="#s4city:involvesFacility">s4city:involvesFacility</a> property. It can be also possible to indicate in which administrative area it is provided, for example a neighbourhood, by means of the property cpsv:physicallyAvailableAt. The public services that an agent (<a href="#s4city:Agent">s4city:Agent</a>) provides or uses are indicated by means of the properties cpsv:provides and cpsv:uses, respectively. The languages in which a service is provided are indicated by the property <a href="#s4city:isAvailableInLanguage">s4city:isAvailableInLanguage</a>. The name and a natural language description of the <a href="#s4city:PublicService">s4city:PublicService</a> are indicated by the attributes <a href="#s4city:hasName">s4city:hasName</a> and <a href="#s4city:hasDescription">s4city:hasDescription</a>, respectively.</p>

<p>The model developed to describe public services within the SAREF4CITY ontology is depicted in <a href="#Figure_7">Figure 7</a>. The main entity included is the <a href="#s4city:PublicService">s4city:PublicService</a> class which is a specialization of the reused concept cpsv:PublicService class defined in the Public Service vocabulary provided by the ISA vocabularies European initiative. The facility in which the service is provided is indicated by the <a href="#s4city:involvesFacility">s4city:involvesFacility</a> property. It can be also possible to indicate in which administrative area it is provided, for example a neighbourhood, by means of the property cpsv:physicallyAvailableAt. The public services that an agent (<a href="#s4city:Agent">s4city:Agent</a>) provides or uses are indicated by means of the properties cpsv:provides and cpsv:uses, respectively. The languages in which a service is provided are indicated by the property <a href="#s4city:isAvailableInLanguage">s4city:isAvailableInLanguage</a>. The name and a natural language description of the <a href="#s4city:PublicService">s4city:PublicService</a> are indicated by the attributes <a href="#s4city:hasName">s4city:hasName</a> and <a href="#s4city:hasDescription">s4city:hasDescription</a>, respectively.</p>

<figure>

  <a href="diagrams/PublicService.png"><img src="diagrams/PublicService.png" alt="Public Service model"/></a>

  <figcaption id="Figure_8">Figure 8: Public Service model</figcaption>

  <figcaption id="Figure_7">Figure 7: Public Service model</figcaption>

</figure>

<!-- this is the previous version of the description.html that contained the example, now moved to a new file 

<h3>Instantiating SAREF4CITY</h3>

<a href="#Figure_9">Figure 9</a> shows an example of how to instantiate the SAREF4CITY extension of SAREF. This example shows the use of different patterns included in the SAREF4CITY ontology. First of all, a camera (<a>ex:Camera1</a>) measures the speed of a car (<a>ex:Car35</a>) in the information attached to the individual <a>ex:Camera1Measurement200</a>, which provides a value of 35 Km/hour. The position of the car at that moment is captured by the instance <a>ex:CarLocation2018-11-20T13-30-00</a> with points to the geographical coordinates in which the car is located and also to the road segment in which it is included. It can be observed that such road segment might contain (see property geosp:sf:Contains) other city objects such as a lamppost or a building.

<p>The KPI pattern is also instantiated in the example. The instance <a>ex:RoadSegment50Congestion2018-11-20T13-30-00</a> refer to the value (70 %) of the road congestion on the 2018-11-20 at 13:20. Such value is assessed by the public administration <a>ex:City4</a>. In the calculation of such value the speed of the cars (<a>ex:CarsSpeed2018-11-20</a>), the pollution (<a>ex:Polution2018-11-20</a>) and the GMaps API (<a>ex:GMapsAPI2018-11-20</a>) values have been taken into account as it can be observed from the s4ctiy:isDerivedFrom property between the KPI value and the different <a href="https://saref.etsi.org/core/Measurement">saref:Measurement</a> instances.</p>

<p><a href="#Figure_8">Figure 8</a> shows an example of how to instantiate the SAREF4CITY extension of SAREF. This example shows the use of different patterns included in the SAREF4CITY ontology. First of all, a camera (<a>ex:Camera1</a>) measures the speed of a car (<a>ex:Car35</a>) in the information attached to the individual <a>ex:Camera1Measurement200</a>, which provides a value of 35 Km/hour. The position of the car at that moment is captured by the instance <a>ex:CarLocation2018-11-20T13-30-00</a> with points to the geographical coordinates in which the car is located and also to the road segment in which it is included. It can be observed that such road segment might contain (see property geo:sf:Contains) other city objects such as a lamppost or a building.</p>

<p>The KPI pattern is also instantiated in the example. The instance <a>ex:RoadSegment50Congestion2018-11-20T13-30-00</a> refer to the value (70 %) of the road congestion on the 2018-11-20 at 13:20. Such value is assessed by the public administration <a>ex:City4</a>. In the calculation of such value the speed of the cars (<a>ex:CarsSpeed2018-11-20</a>), the pollution (<a>ex:Polution2018-11-20</a>) and the GMaps API (<a>ex:GMapsAPI2018-11-20</a>) values have been taken into account as it can be observed from the s4ctiy:isDerivedFrom property between the KPI value and the different <a href="https://saref.etsi.org/core/Observation">saref:Observation</a> instances.</p>

<p>In the example the event <a>ex:BasketMatch23</a>, as sub event of the <a>ex:BasketWeek2018</a>, is described. It can be seen that the match is accessible by metro, is organized by <a>ex:City4</a> and takes place at the facility <a>ex:BasketArena7</a>.</p>

<p>Finally, some examples of public services are shown. One service example is the <a>ex:HealthService123</a> that involves the facility <a>ex:BasketArena7</a> and is available in Spanish. Such service is available in area <a>ex:Neighbourhood34</a> that is contained in <a>ex:City4</a>, which is the service provider organization. In addition, another service, <a>ex:Bus33Service</a>, is provided by another organization, in this case <a>ex:TransportCo</a>.</p>

<figure>

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

  <figcaption id="Figure_9">Figure 9: Example</figcaption>

  <a href="diagrams/S4CITY Example 1.png"><img src="diagrams/S4CITY Example 1.png" alt="Example"/></a>

  <figcaption id="Figure_8">Figure 8: Example</figcaption>

</figure>

-->

<ul>

  <li id="[1]">[1] ETSI TS 103 264 (V3.1.1) (02-2020): "SmartM2M; Smart Applications; Reference Ontology and oneM2M Mapping".</li>

  <li id="[2]">[2] ETSI TS 103 548: "SmartM2M; SAREF reference ontology patterns".</li>

  <li id="[3]">[3] ETSI TS 103 673: "SmartM2M; SAREF Development Framework and Workflow, Streamlining the Development of SAREF and its Extensions".</li>

</ul>

<h3>Informative references</h3>

<ul>

  <li id="[i.1]">[i.1] ETSI TR 103 506 (V1.1.1) (09-2018): "SmartM2M; SAREF extension investigation; Requirements for Smart Cities".</li>

  <li id="[i.2]">[i.2] ETSI TR 103 781: "SmartM2M; Study for SAREF ontology patterns and usage guidelines".</li>

</ul>