1 Introduction

The Internet of Things (IoT) promises techniques which will enable integration of connected physical devices with less effort, and as a consequence this will enable new added-value services at a large scale [1, 2]. The integration of two or more physical devices should not only happen at the level of data exchange but the devices should also understand the meaning of exchanged data. That is, instead of mere interoperability IoT devices are required to achieve semantic interoperability [3, 4]. Only then, it would be possible for machines to discover devices relevant for an added-value service, and further to understand their capabilities, to integrate and process their data, and to ultimately create a new value.

The promise of IoT has not been delivered yet. The current focus in the IoT is merely to connect heterogeneous devices to a common IoT platform.Footnote 1\(^{,}\)Footnote 2 Once connected, devices are capable to exchange data. But semantics of data and capabilities of devices, which generate this data, are not described in a machine-interpretable form. What is generated by each IoT platform is essentially a data silo that yet needs to be integrated. This situation hinders the potential of IoT to enable added-value services at large scale.

In order to improve this, W3C Web of Things (WoT) Working GroupFootnote 3 is developing a new standard which addresses the challenge of heterogeneous IoT platforms, communication protocols, and data formats. Among others, WoT Group proposes the so-called protocol binding to bring disparate IoT platforms and devices to the Web as a common application layer. Once connected to the Web, devices can be accessed and programmed with a standardized Application Programming Interface (API). However the most important aspect of the upcoming standard is provision of Thing DescriptionFootnote 4 (TD). TD is a machine-readable description of an IoT thing (e.g., a physical device or virtual thing residing in a cloud). It abstracts an IoT thing in terms of its interactions and data it consumes or produces. Interactions, data and the thing itself may be marked-up with semantic terms from an ontology or a schema [5, 6]. iot.schema.org is a community effortFootnote 5 which is developing exactly one such IoT schema to be used with TD. iot.schema.org abstracts the functionality of IoT devices via so-called Capabilities. Capability is a semantic model to formally describe traits of a class of physical devices (e.g., thermostat provides temperature data and it can be set to a target temperature). iot.schema.org exposes capabilities of an IoT device in order to simplify the development of an application. The schema is developed as an IoT extension to the widely-used schema.org.

WoT TD and Capabilities from iot.schema.org offer a solid basis to achieve IoT semantic interoperability. Semantics specified by an iot.schema.org Capability can be used to mark-up a TD. The TD is then used to generate a code-skeleton of the thing. This can be done, for example, with the WoT reference implementation. Once the code-skeleton has been implemented for device, it can be exposed as an IoT thing, i.e., accessible over a Web API and discoverable thanks to its TD. Such an IoT thing can also be easily integrated with other things since its capability, interactions, and data are all semantically described and machine interpretable. With WoT TD and iot.schema.org Capabilities in place we are capable of creating semantically described IoT things and realize them in an efficient manner. This is unfortunately not so easy in practice as an iot.schema.org Capability is always overspecified. It provides one Capability per class of devices. However in real-world there exists multiple device variants from different manufacturers in a class of devices.

1.1 Motivating Example

Consider a widely used industrial device such as a pump, whose functionality should be semantically described and exposed over an IoT API. For this purpose one can use pump CapabilityFootnote 6 specified in iot.schema.org. It includes semantic description of pump interactions and their data such as TurnOn, TurnOff, PumpStatus, PumpRunMode (such as fixed speed mode, variable speed mode etc.), FlowRate, Pressure, Temperature and PumpSpeed. The Pump Capability can be used to semantically describe a pump and expose it as an IoT Thing. However not all pumps in the world implement all the interactions described in pump Capability. In the real world, pumps from different manufactures differ in certain feature or data they offer. Consider the following use case where there are two pump manufacturers. Manufacturer 1 produces pumps which can be operated in fixed speed operating mode. In this mode, the speed of a pump cannot be changed by a user. On the other hand manufacturer 2, produces pumps which can run in variable speed operating mode. In this mode, a user can set the speed of a pump by changing the pressure and flow rate of the pump. In such a case, the pump Capability of iot.schema.org should be tailored to fit the requirements of pumps from each manufacturer. This means, we should be able to shape iot.schema.org Capabilities to represent several device variants in a class of devices.

1.2 Contributions

In this work, we address the problem of creating tailored Thing Description templates for specific device variants from overspecified iot.schema.org Capabilities. The goal of this work is to extend semantics of iot.schema.org Capabilities in such a way that it enables specification of variants of Capabilities, and automate the generation of TD for so-extended device Capabilities. In particular, we propose to use RDF Shape languages [7,8,9] to specify constraints on Capabilities. Shape constraints help to adapt an iot.schema.org Capability to represent several device variants. We model the constraints in both Shape Constraint Languages (W3C SHACL) and Shape Expressions (ShEx). However, in this paper we will present the shapes created for pump use case in ShEx only. Shapes created in SHACL can be found online. After modeling the constraints as RDF shapes, TD templates can be generated from a Capability and its shapes. This is a very important extension to iot.schema.org and WoT TD as it is ensures rich semantic descriptions for IoT device variants, while keeping the overall process easy, e.g., with respect to automatically-generated TD, TD validation, and automatically-generated user interfaces for IoT things.

The main contributions of this paper are the following: (1) we describe a procedure to specify shape constraints on iot.schema.org Capabilities using ShEx [7,8,9] in Sect. 3; (2) in Sect. 4 we provide a mapping from SHACL to JSON Schema and, from ShEx to JSON Schema as TD uses JSON Schema [10] to model constraints on data consumed or produced by interactions; (3) we provide implementation of the tool to generate semantically enriched TD templates from an iot.schema.org Capability shapes in Sect. 5. In Sect. 6 we will discuss about pros and cons of our approach and also present our lessons learned by using SHACL and ShEx for creating device variants. We conclude in Sect. 7 and present ideas for future work.

2 Background and Related Work

W3C Web of Things Working Group is developing a standard to create interoperability between physical things on the Web. For this, WoT Group is developing a protocol binding to enable interoperability between various protocols such as OCF, OPC-UA [11], BacNet [12] and so on. Apart from the protocol binding, WoT Group also proposes Thing Description, which is a platform independent description of a physical device. Thing Description describes a device in terms of its interactions such as Properties, Events and Actions. A Thing Description is serialized in JSON-LD [13] format. Further on, Thing Description uses JSON Schema [10] to model syntactical constraints on data. JSON Schema provides simple data types such as integer, number, string, boolean and complex data types such as object, array and enumeration.

In order to provide semantic discovery and interoperability between devices, Thing Description is supposed to be extended with external ontologies and schemas [5, 6]. Many ontologies are developed for IoT. Domain-independent ontologies such as W3C Semantic Sensor Networks (SSN) [14], M3 [15] to model sensors, their observations and their domain. QUDT [16] to model physical quantities and Units of measurement. WGS84 [17] describes concepts to define spatial features of IoT things. IoT Ontology [18] which models IoT entity features required for their automated deployment. There also exists several domain ontologies such as SAREFFootnote 7 for Smart appliances, Brick [19] for Building Management Systems (BMS) domain. There exists eCl@ssOWL ontology [20] for industry domain and so on. A TD can be semantically enriched by marking up with the terms defined in these ontologies. More recently, community work on iot.schema.org (currently referred to as iotschema.orgFootnote 8) has started which provides lightweight RDFS semantics to expose capabilities of a device in order to simply IoT application development. iot.schema.org Capability model is aligned with WoT TD model [5]. In order to model domain features of a physical device, iot.schema.org normalizes semantics from existing standards such as OneM2MFootnote 9, OpenT2TFootnote 10, OCFFootnote 11, IPSO ObjectsFootnote 12. Moreover, the semantics of Capability model can be further extended with existing IoT semantics. For example, Capability model can be extended with Feature of Interest model defined in W3C SSN/SOSA ontology.

RDF Shape Languages are used to define constraints on RDF graphs. These constraints can be used for purposes such as generating and validating RDF data, or generating user interfaces [9]. They bring closed-world assumption to RDF data and captures data in a predictable way [21]. This allows to safely process data being exchanged between programs, humans or IoT things. There are two RDF Data shape languages: SHACL and ShEx. Both SHACL and ShEx can be used to express constraints on RDF graphs. We model the constraints on iot.schema.org Capabilities in both languages and the implementation can be found in the following GitHub repository.Footnote 13

3 RDF Constraints Modeling on iot.schema.org Capabilities

In this section, we will consider the pump use case presented in Sect. 1 and present the following: (1) an iot.schema.org Capability for a pump, (2) a procedure to model ShEx constraints on an iot.schema.org Capability to specify device variants of different manufacturers (e.g., pump specification for manufacturer 1 and manufacturer 2 in our use case). Shape constraints modeled in SHACL can be found in git repository mentioned above.

3.1 iot.schema.org Capability

An iot.schema.org Capability models a semantic description of a physical device in terms of its interaction patterns and their input and output data. Here we present an iot.schema.org Capability defined for a pump. This Capability is created referring to eCl@ss description of a centrifugal pump.Footnote 14 Due to space constraints, we present a part of the Capability in Listing 1.1. The complete specification of the pump Capability, its interaction patterns and data can be found in the GitHub repository mentioned above. Among others, the pump Capability provides the following interaction patterns (1) TurnOn, an action to turn on a pump; (2) TurnOff, an action to turn off a pump; (3) PumpStatus, a property to check the current status of a pump; (4) PumpRunMode, an action to set the operating mode of a pump to FixedSpeed or VariableSpeed. These interaction patterns are further described in terms of its input and/or output data as shown in Listing 1.2.

figure a
figure b

Data Description. The Data of an interaction pattern is well-defined in terms of the value type, allowed values for the data, units of measurement, minimum and maximum range of the data. Listing 1.2 shows the definition of data for each interaction pattern of the pump Capability. Let us consider FlowRate interaction pattern. It has input and output data called FlowRateData which is well-defined in the capability. FlowRateData provides a value of type float. Minimum and maximum range for FlowRate of a pump can be specified in float. And also the unit of measurement for FlowRate such as GallonsPerMinute, CubicMeterPerSecond, CubicYardPerMinute etc.Footnote 15 can be specified for a pump using pump Capability model. Similarly, PumpRunModeData defines a set of pre-defined operating modes of a pump such as FixedSpeedMode, VariableSpeedMode. Data description for all interaction patterns of the pump Capability can be found in the GitHub repository.

In this manner an iot.schema.org Capability provides a well-defined semantic description for a class of physical devices. In the next section, we will describe a procedure to model constraints on an iot.schema.org Capability to model device variants.

3.2 Modeling of ShEx Constraints

Shape constraints on an iot.schema.org Capability are specified at two levels: (1) at the level of a Capability in order to constrain the interaction patterns supported a device variant, (2) at the level of data of an interaction pattern to specify constraints on complex data of an interaction pattern. Listing 1.3 shows a part of ShEx constraints modeled on the pump Capability. ShEx has several serialization formats such as ShExC, which is compact representation of ShEx Shapes. ShExJ is a JSON syntax, which serves as abstract syntax.Footnote 16 And ShExR is a RDF syntax generated from ShExJ. In Listing 1.3 shapes are defined in ShExC format. This shape represents the specification of pump features for manufacturer 2 in our use case. That is the pumps which can be operated in variable speed mode.

Constraints on Interaction Patterns. The pump Capability shown in Listing 1.1 defines that a physical device of type pump should implement all eight interactions as specified in the Capability. However, in the real world all the pumps may not provide all these eight interactions. Therefore, using shape constraints we can specify several variants of pumps by modeling constraints on interaction patterns. Listing 1.3 shows ShEx constraints modeled for this pump variant specified by manufacturer 2. Lines 4–11 in the listing present the constraints on interaction patterns. These lines show that a physical device, which implements this shape should implement only a subset of interaction patterns of a pump Capability such as TurnOn, TurnOff, PumpStatus, PumpRunMode, FlowRate and Pressure. Therefore, it represents a variation of pump. In the similar manner, another shape with a different set of interaction patterns can be defined on the pump Capability representing one more variation. Further on, data of the interaction patterns can also be constrained to represent a device variant.

figure c

Constraints on Interaction Pattern’s Data. Lines 14–15 and 19–22 in Listing 1.3 shows ShEx constraints on pump interaction patterns data. Constraints for PumpRunModeData are modeled in lines 14–15. It specifies that a pump from manufacturer 2 can be operated only in VariableSpeedMode. Further on, constraints on FlowRateData are also defined to represent pump specification from manufacturer 2. Lines 19–22 present this constraints. It specifies that a pump should be operated within the flow rate range 7.5 and 295.0. It further specifies that flow rate of the pump is measured in CubicMeterPerHour unit.

Fig. 1.
figure 1

Mapping between SHACL, ShEx and JSON Schema

Full size image

4 Mappings Between SHACL, ShEx and JSON Schema

Having a device variant model in place, our goal is to automate the generation of semantically enriched TD template for a device variant. In a TD constraints on interaction patterns data are modeled using JSON Schema [10]. Therefore in order to generate JSON Schema constraints from SHACL or ShEx constraints, we created a mapping from Shape constraint languages (SHACL and ShEx) to JSON Schema.

ShEx defines RDF shapes as Node constraints, Triple constraints and Shape expressions. On the other hand, SHACL defines two types of shapes such as node shapes and property shapes. Here, we will present different elements of ShEx, SHACL and a possible conversion to JSON Schema. The table in Fig. 1 shows this mapping. In the table all the examples use default prefix “:” for URIs. This default prefix can be replaced by other prefixes depending on the use case. ShEx and SHACL uses XML schema datatypes. In this examples we use xsd prefix for XML datatypes. Firstly, the table presents elements such as xsFacet (StringFacet, NumericFacet) and ValueSet and their conversion to JSON Schema. Inside each facet we also present the constraints that are applicable to it. For example, constraints such as MinInclusive, MaxInclusive, MinExclusive, MaxExclusive, TotalDigits, FractionDigits are presented in NumericFacet as they are applicable only to numeric RDF literals. In some cases, there is no JSON Schema equivalent for ShEx and SHACL. TotalDigits, FractionDigits in NumericFacet and flags in StringFacet are such examples. The ShEx and SHACL logical operator And can be converted to a JSON Schema allOf if the shape is combining more than one shapes as shown in row 6(a) of Fig. 1. Alternatively, AND can be converted to a JSON Schema object, if it combines more than one Triple constraints as shown in row 6(b) of Fig. 1. This mapping from SHACL to JSON Schema and ShEx to JSON Schema are implemented in the TD template generator.

5 Thing Description Template Generation

We developed two implementations of TD template generator in JavaScript. One implementation takes ShEx shapes on an iot.schema.org Capability as input and generates a semantically enriched TD template from it. The second implementation takes SHACL shapes on an iot.schema.org Capability as input and generates a semantically enriched TD template. The code for TD template generator is available online.Footnote 17

The mappings from an iot.schema.org Capability shape to TD model are done at two levels. (1) mapping from iot.schema.org Capability model to WoT TD model [5]. This is a direct mapping as iot.schema.org Capability model is aligned with WoT TD model. This mapping generates semantically enriched interaction templates of a TD, (2) mapping from ShEx to JSON Schema and mapping from SHACL to JSON Schema. This mappings generates input and output data of an interaction pattern.

For ShEx implementation, the tool is built on top of shex.js, which is a JavaScript implementation of ShEx.Footnote 18 A Capability shape in ShEx compact format (ShExC) format is given as input to shex.js which verifies the shape and converts it into ShEx JSON format (ShExJ).Footnote 19 ShExJ file is given as input to the TD template generator tool. The tool recursively converts shape constraints on a Capability to TD format and gives as output a TD template with semantic mark-ups from iot.schema.org Capability model. In case of SHACL implementation also the TD generator tool recursively converts SHACL shapes to semantically enriched TD template.

We implemented and tested mappings from all types of ShEx and SHACL shapes to JSON Schema (as presented in the mapping table in previous section). The result is that the tool generates valid TD templates with semantic mark-ups. The resulting semantically enriched TD templates can be found in the GitHub repository. The TD template generated for our pump use case is shown in Listing 1.4.

figure d

A generated TD template should be instantiated with the attributes of a physical device. For example, base field should be filled by the uri where the thing can be accessed. link section of the interaction patterns should be filled with the href of the interaction, that is the link where an interaction can be accessed and the mediaType which indicates the format of data consumed or produced by an interaction. After filling this information, the template becomes a TD which can be validated using thingweb-playground tool.Footnote 20 Such a semantically marked-up TDs enhance discovery of devices and semantic interoperability between devices.

6 Discussion

The proposed approach presents a solution to a real-life engineering problem by automatically generating semantically-enriched device descriptions for specific IoT device variants. This approach is tested in W3C WoT Plugfest during the WoT meeting in March, 2018.Footnote 21 The results were very encouraging, Thing Descriptions from various manufacturers were easily discoverable based on terms from iot.schema.org. The discovery process is important as it precedes the development of a new application. An efficient discovery significantly reduces the time required for application development. The work in this paper further simplifies the application development by automating the generation of semantically-enriched TDs. Moreover, it enables specification of variants of TDs to capture differences in physical devices of the same class. Shape Constraints are created based on well-defined semantic terms from iot.schema.org, rather than on strings (as it is the case in JSON).

iot.schema.org tend to overspecify capabilities of physical devices, as capabilities need to capture all possible features of one class of devices. On the other hand, it is desirable to be able to constrain such specification for devices that do not support all features. Before RDF Shape languages it was a challenge to constrain RDF graphs under the Open World Assumption of OWL. On the other hand, in IoT it is critical to restrict the interface of a device to exact requirements of the device (e.g., input/output data provided in certain range). Only then, interoperability with that device is possible. This is the reason why we propose RDF Shape languages to be used for constraining overspecified iot.schema.org Capabilities. Therefore, RDF Shape languages bring a closed-world assumption flavor to the interpretation of semantics of iot.schema.org Capabilities, which is important for building clients that interact with IoT devices.

The process of semantic mark-up of TDs is error-prone. By automating this process, we avoid these errors. Our approach is domain-independent. Device variants to iot.schema.org Capabilities from any domain can be created using our approach. The shape constraints act as constructors for TDs. We believe that this work is a good contribution to both iot.schema.org and W3C WoT communities, as it provides an engineering solution for a real-world problem, and it helps for the adoption of the technologies developed by these communities.

On the other hand, the limitation of this approach is that in some cases, there is no mapping from SHACL and ShEx to JSON Schema, which may lead to loss of information in generated TDs.

Our lessons learned from using RDF shape languages SHACL and ShEx are the following. We first implemented the approach in ShEx as it has very compact syntax and it is easy to parse. However ShEx validates a data graph in Turtle format only. On the other hand, a TD is serialized in JSON-LD format, therefore a semantically enriched TD cannot be validated against ShEx shapes on an iot.schema.org Capability. Moreover, default values for a property cannot be expressed in ShEx. Therefore, we extended our implementation to support SHACL. We modeled shapes on an iot.schema.org Capability in SHACL and implemented TD template generation using SHACL shapes. The advantages of using SHACL are: SHACL can validate a data graph serialized in Turtle or JSON-LD. Default values for a property can be expressed in SHACL. However, SHACL syntax is not very compact. On the whole, the implementation of both SHACL and ShEx should be improved for better usability.

7 Conclusions and Future Work

In summary we addressed the problem of modeling device variants in a class of physical devices and generating semantically enriched TDs for the device variants. For this purpose, we employed SHACL and ShEx RDF shape languages to model device variants. In order to generate TDs from SHACL and ShEx shapes we created a mapping from SHACL and ShEx to JSON Schema. We developed an algorithm to automatically generate semantically enriched TD templates from device variants. We discussed the pros and cons of our approach and also presented our lessons learned on using SHACL and ShEx for modeling constraints on RDF graphs. The future directions of the work are the following: (1) offer TD template generator as an online tool to simplify the usage of the tool and to evaluate the approach by getting user’s feedback; (2) in the current work, we developed a top-down approach to generate semantically-enriched TDs from iot.schema.org Capabilities. In the future we will work on bottom-up approach to generate TDs marked-up with iot.schema.org semantics, from existing device descriptions from oneM2M, OCF, IPSO and so on.