This repository contains an open source reference implementation of STAplus.
NOTE: This implementation is still work in progress. The source code is already available in this repository to give you the opportunity to follow along or actually contribute.
INPORTANT: Do not yet use in production!
STAplus is an OGC Candidate Standard 22-022 that extends the suite of OGC SensorThings API v1.0 and v1.1 Standards.
"STAplus - SensorThings API extension PLUS - defines a SensorThings data model extension to improve FAIR principles when exchanging sensor data including licensing and ownership information. The STAplus extension is fully backwards compatible to the existing OGC SensorThings API Part 1: Sensing Version 1.0 and 1.1 and thereby offers existing deployments to easily upgrade to STAplus."1
The following simplified2 UML diagrams illustrate the data model extension towards SensorThings API Datastream and MultiDatastream.
NOTE: The yellow colored classes belong to the SensorThings API data model.
This repository contains an open source reference implementation of STAplus as a FROST-Server plugin.
This implementation supports the conformance classes Core, Authentication and Business Logic as defined in the STAplus Candidate Standard. The API conformance class is already supported by the FROST-Server implementation.
This implementation enforces the concept of ownership as explained in detail below. Please see Business Logic for more details.
The deployment of the STAplus plugin requires a working deployment of the FROST-Server. You can follow the FROST-Server documentation to run your instance.
This repository builds with the FROST-Server 2.2.0 SNAPSHOT.
Follow the FROST-Server documentation applicable to your deployment strategy.
Make sure you copy the FROST-Server.Plugin.STAplus-2.2.0-SNAPSHOT.jar file to the appropriate FROST-Server directory and apply the STAplus specific settings below.
Different features of the STAplus plugin can be activated / deactivated using FROST-Server alike configuration variables:
- plugins.staplus.enable:
Set totrueto activate the STAplus plugin. Default:false. - plugins.staplus.idType.observation_group:
The type of the primary key column of the ObservationGroups table. Defaults to the value of plugins.coreModel.idType. - plugins.staplus.idType.license:
The type of the primary key column of the Licenses table. Defaults to the value of plugins.coreModel.idType. - plugins.staplus.idType.campaign:
The type of the primary key column of the Campaigns table. Defaults to the value of plugins.coreModel.idType. - plugins.staplus.idType.relation:
The type of the primary key column of the Relations table. Defaults to the value of plugins.coreModel.idType.
NOTE: The type of the primary key column of the Party table (plugins.staplus.idType.party) is set to UUID by the implementation. This setting cannot be changed!
The activation of the Enforcement of Ownership allows to operate the STAplus endpoint in multi-user-CRUD mode. However, it requires to enable Authentication.
Each acting user is identified via a unique UUID, provided by the authentication plugin. The REMOTE_USER value is used to identify the user. The value of REMOTE_USER represents the user as a Party object via the authId property. When creating a Party object, the value for the authId property must either be empty or match the value for the REMOTE_USER. All other values are rejected by the implementation and will result in a response with HTTP status code 400.
The classes Thing, MultiDatastream, Datastream and ObservationGroup are directly associated to a Party. Objects of class Observation are linked to the owning Party object via the (Multi)Datastream. Objects of class Relation are linked to the Party object via the Subject property.
When activating the Concept of Ownership, the implementation enforces the multiplicity [1] on the association of these classes to Party. Therefore, creating objects of class Thing, MultiDatastream, Datastream or ObservationGroup require the association with the Party object that represents the acting user.
A user can update or delete any object owned. However, the user cannot delete the own Party. This requires admin access.
plugins.staplus.enable.enforceOwnership:
Set to true to enable the enforcement of ownership. Default: false.
This STAplus implementation creates a Party entity for the acting user if the Authentication conformance class is enabled. To prevent that the implementation creates a new Party entity for each request, it is IMPORTANT to allow client-side id generation. The id generation is controlled via this general setting:
<Parameter override="false" name="persistence.idGenerationMode" value="ServerGeneratedOnly" />P L E A S E make sure that you include the following configuration to ensure that a Party entity exists only once per user:
<Parameter override="false" name="persistence.idGenerationMode.Party" value="ClientGeneratedOnly" />This configuration overwrites the id generation for the Party entity only.
According to the STAplus Data Model, a Datastream, ObservationGroup and Campaign may have a License association. In order to ensure the use of compatible licenses, this implementations generates a given set of configured licenses.
The file resources/tables.xml contains as the last constructor for table generation the entry
<include relativeToChangelogFile="true" file="insertCCLicenes.xml" />The file insertCCLicenses.xml contains the set of licenses that are generated by the implementation.
You can change this configuration accordingly to load a different set of licenses.
plugins.staplus.enable.enforceLicensing:
Set to true to enable the enforcement of licensing. Default: false.
When adding (an) Observation(s) to an ObservationGroup, the Enforcement of Licensing ensures that the License, associated to (an) Observation(s) is compatible to the License associated to an ObservationGroup.
When activating the Enforcement of Licensing, the plugin enforces licenses compatibility based on the Creative Commons v3 licensing model an the license compatibility according to the official cart.
See https://wiki.creativecommons.org/wiki/Wiki/cc_license_compatibility for more information.
The plugin creates the different Creative Commons Licenses in read-only mode as "system-wide" globals. An application cannot create new License objects nor can it update or delete the existing ones. An application can obtain a list of the "system-wide" licenses via the /Licenses path.
plugins.staplus.enable.enforceObservationGroupLicensing:
Set to true to enable the enforcement of licensing on ObservationGroup entity. Default: false.
Work on this implementation has being funded by the European Commission.
Footnotes
-
The SensorThings API classes are empty. Please see Sensor Things API standard - Sensing Entities diagram and Sensor Things API standard - MultiDatastream Extension Entities diagram for details. ↩