update ci/cd

image: openjdk:8-jdk

check:

variables:

    SAREF_DEV_KEY: <my_private_key>

    SAREF_PORTAL_KEY: <my_private_key>

before_script:

  - eval $(ssh-agent -s)

  - ssh-add <(echo "$SAREF_DEV_KEY")

  - mkdir -p ~/.ssh

  - '[[ -f /.dockerenv ]] && echo -e "Host *\n\tStrictHostKeyChecking no\n\n" > ~/.ssh/config'

stages:

  - test

  - build

  - deploy

test-develop:

  stage: test

  script:

    - curl -L -o saref-pipeline.jar "https://gitlab.emse.fr/saref/saref-pipeline/-/jobs/artifacts/master/raw/target/saref-pipeline.jar?job=build"

    - java -jar saref-pipeline.jar develop -s && touch target/success

  allow_failure: true

  except:

    - /^prerelease-v/

    - /^release-v/

  artifacts:

    when: always

    paths:

      - target/site

      - target/success

    reports:

      junit: target/report_output.xml

test-prerelease:

  stage: test

  script:

    - curl -L -o saref-pipeline.jar "https://gitlab.emse.fr/saref/saref-pipeline/-/jobs/artifacts/master/raw/target/saref-pipeline.jar?job=build"

    - java -jar saref-pipeline.jar -g -s

    - java -jar saref-pipeline.jar release -t && touch target/success

  allow_failure: true

  only:

    - /^prerelease-v/

  artifacts:

    when: always

    paths:

      - target/report_output.xml # allows to visualize the report as HTML on the SAREF portal

      - target/site

      - target/success

    reports:

      junit: target/report_output.xml # allows to visualize the errors when discussing a pull request

      junit: target/report_output.xml

deploy-report:

  stage: deploy

  script:

    - scp -pr '-P 29419' target/site saref-dev@saref.etsi.org:~/snapshot/$CI_PIPELINE_ID

    - echo "SAREF pipeline report  https://saref.etsi.org/snapshot/$CI_PIPELINE_ID/report.html" 

    - exit $(test -f target/success) $?

  except:

    - /^release-v/

test-release:

  stage: test

  script:

    - curl -L -o saref-pipeline.jar "https://gitlab.emse.fr/saref/saref-pipeline/-/jobs/artifacts/master/raw/target/saref-pipeline.jar?job=build"

    - java -jar saref-pipeline.jar release -t

  only:

    - /^release-v/

trigger-release:

  stage: deploy

  only:

    - /^release-v/

  variables:

    SAREF_DEV_KEY: $SAREF_DEV_KEY

    SAREF_PORTAL_KEY: $SAREF_PORTAL_KEY

  trigger:

    project: saref/saref-portal

    branch: master

SAREF v3.1.1 is a reference ontology for the IoT developed by ETSI SmartM2M in close interaction with the industry. SAREF contains core concepts that are common to several IoT domains and, to be able to handle specific data elements for a certain domain, dedicated extensions of SAREF have been created, for example SAREF4ENER [[i.4]](#[i.4]), SAREF4ENVI [[i.5]](#[i.5]), SAREF4BLDG [[i.6]](#[i.6]), and SAREF4CITY [[i.7]](#[i.7]), SAREF4INMA [[i.8]](#[i.8]), SAREF4AGRI [[i.9]](#[i.9]). Each domain can have one or more extensions, depending on the complexity of the domain. As a reference ontology, SAREF serves as the means to connect the extensions in different domains. The earlier document ETSI TR 103 411 [[i.10]](#[i.10]) specifies the rationale and methodology used to create, publish and maintain the SAREF extensions.

The present document is the technical specification of SAREF4SYST, a generic extension of ETSI TS 103 264 SAREF [[1]](#[1]) that defines an ontology pattern which can be instantiated for different domains. SAREF4SYST defines Systems, Connections between systems, and Connection Points at which systems may be connected. These core concepts can be used generically to define the topology of features of interest, and can be specialized for multiple domains. The topology of features of interest is highly important in many use cases. If a room holds a lighting device, and if it is adjacent with an open window to a room whose luminosity is low, then by turning on the lighting device in the former room one may expect that the luminosity in the latter room will rise.

The SAREF4SYST ontology pattern can be instantiated for different domains. For example to describe zones inside a building (systems), that share a frontier (connections). Properties of systems are typically state variables (e.g. agent population, temperature), whereas properties of connections are typically flows (e.g. heat flow).

SAREF4SYST has two main aims: on the one hand, to extend SAREF with the capability or representing general topology of systems and how they are connected or interact and, on the other hand, to exemplify how ontology patterns may help to ensure an homogeneous structure of the overall SAREF ontology and speed up the development of extensions.

SAREF4SYST consists both of a core ontology, and guidelines to create ontologies following the SAREF4SYST ontology pattern. The core ontology is a lightweight OWL-DL ontology that defines 3 classes and 9 object properties.

Use cases for ontology patterns are described extensively in ETSI TR 103 549 [[i.3]](#[i.3]). Clauses 4.2 and 4.3 extract use cases for the SAREF4SYST ontology pattern.

### Use case 1: Smart Energy

The present clause illustrates how SAREF4SYST can be used to homogeneously represent knowledge that is relevant for use cases in the Smart Energy domain:

- Electric power systems can exchange electricity with other electric power systems. The electric energy can flow both ways in some cases (from the Public Grid to a Prosumer), or in only one way (from the Public Grid to a Load). Electric power systems can be made up of different sub-systems. Generic sub-types of electric power systems include producers, consumers, storage systems, transmission systems. 

- Electric power systems may be connected one to another through electrical connection points. An Electric power system may have multiple connection points (Multiple Winding Transformer generally have one single primary winding with two or more secondary windings). Generic sub-types of electrical connection points include plugs, sockets, direct-current, single-phase, three-phase, connection points. 

- An Electrical connection may exist between two Electric power systems at two of their respective connection points. Generic sub-types of electrical connections include Single-phase Buses, Three-phase Buses. A single-phase electric power system can be connected using different configurations at a three-phase bus (RN, SN, TN types).

## Use case 2: Smart Building

The present clause illustrates how SAREF4SYST can be used to homogeneously represent knowledge that is relevant for use cases in the Smart Building domain:

- Buildings, Storeys, Spaces, are different sub-types of Zones. Zones can contain sub-zones. Zones can be adjacent or intersect with other zones. 

- Two zones may share one or more connections. For example some fresh air may be created inside a storey if it has two controllable openings to the exterior at different cardinal points. 

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.

- [Maxime Lefrançois](http://maxime-lefrancois.info/me#) ([MINES Saint-Étienne](https://www.mines-stetienne.fr/))

<h3>General Overview</h3>

<p>A graphical overview of the SAREF4SYST ontology is provided in <a href="#Figure_1">Figure 1</a>. In such figure:</p>

<ul>

• Rectangles are used to denote Classes. The label of the rectangle is the identifier of the Class.

• Plain arrows are used to represent Object Properties between Classes. The label of the arrow is the identifier of the Object Property. The origin of the arrow is the domain Class of the property, and the target of the arrow is the range Class of the property.

• Dashed arrows with identifiers between stereotype signs (i.e. "<< >>") refer to OWL axioms that are applied to some property. Four pairs of properties are inverse one of the other; the property <a href="#s4syst:connectedTo">s4syst:connectedTo</a> is symmetric, and properties <a href="#s4syst:hasSubSystem">s4syst:hasSubSystem</a> and <a href="#s4syst:hasSubSystem">s4syst:hasSubSystem</a> are transitive.

• A symbol =1 near the target of an arrow denotes that the associated property is functional. A symbol ∃ denotes a local existential restriction.

</ul>

<figure>

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

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

</figure>

<h3>Systems and sub-systems</h3>

<p>A <a href="#s4syst:System">s4syst:System</a>, is defined as a part of the universe that is virtually isolated from the environment. </p>

<p>NOTE: The system properties are typically state variables (e.g. consumed or stored energy, agent population, temperature, volume, humidity). </p>

<a href="#Figure_2">Figure 2</a> illustrates classes and properties that can be used to define connected systems and their sub-systems.

<figure>

  <a href="diagrams/Systems.png"><img src="diagrams/Systems.png" alt="SAREF4SYST: Systems, sub-systems"/></a>

  <figcaption id="Figure_2">Figure 2: SAREF4SYST: Systems, sub-systems</figcaption>

</figure>

<p>A system may be connected to other systems that are part of its environment. This is modelled by a property named <a href="#s4syst:connectedTo">s4syst:connectedTo</a>, which is symmetric. </p>

<h3>Connections between systems</h3>

<p>A connection between two <a href="#s4syst:Systems">s4syst:Systems</a>, modelled by <a href="#s4syst:connectedTo">s4syst:connectedTo</a>, describes the potential interactions between connected <a href="#s4syst:Systems">s4syst:Systems</a>. A connection can be qualified using class <a href="#s4syst:Connection">s4syst:Connection</a>. </p>

<a href="#Figure_3">Figure 3</a> illustrates classes and properties that can be used to qualify connections between <a href="#s4syst:Systems">s4syst:Systems</a>.

<figure>

  <a href="diagrams/Connections.png"><img src="diagrams/Connections.png" alt="Connections between systems"/></a>

  <figcaption id="Figure_3">Figure 3: Connections between systems</figcaption>

</figure>

<h3>Connection Points of systems</h3>

<p>A <a href="#s4syst:System">s4syst:System</a> connects to other <a href="#s4syst:Systems">s4syst:Systems</a> at connection points. A connection point belongs to one and only one <a href="#s4syst:System">s4syst:System</a>, and can be described using the class <a href="#s4syst:ConnectionPoint">s4syst:ConnectionPoint</a>.</p>

<a href="#Figure_4">Figure 4</a> illustrates the classes and the properties that can be used to describe connection points of a <a href="#s4syst:System">s4syst:System</a>.

<p>One can then associate a <a href="#s4syst:ConnectionPoint">s4syst:ConnectionPoint</a> with properties (<a href="https://saref.etsi.org/core/Property">saref:Property</a>) that describe it (e.g. position and speed, voltage and intensity, thermic transmission coefficient).</p>

<figure>

  <a href="diagrams/ConnectionPoints.png"><img src="diagrams/ConnectionPoints.png" alt="SAREF4SYST: Connection points of systems, where other systems connect"/></a>

  <figcaption id="Figure_4">Figure 4: SAREF4SYST: Connection points of systems, where other systems connect</figcaption>

</figure>