WSML2Reasoner - API and User Guide

1  Introduction

1.1  Purpose

This document is intended to give a short introduction to using the the WSML2Reasoner framework and its application programming interface (API).

1.2  Audience

This guide is not only for software developers who are integrating WSML2Reasoner into their application, but also for higher level business users and professionals that wish to reason over WSML ontologies.

1.3  Scope

This document is intended to be a 'non-technical' guide for the basic usage of the WSML2Reasoner API. For a more technical description of the internal implementations, we refer the user to A Reasoning Framework for Rule-Based WSML.

2  Description

2.1  Function

The WSML2Reasoner framework performs a variety of functions that ultimately - and optimally - translate a WSML ontology into the appropriate syntax of a specified underlying reasoning engine. Depending on the variant of the WSML ontology, and concurrently the desired reasoning tasks to be performed, the user must specify which reasoning engine he or she wishes to use.

2.2  Facades

Each reasoning engine implemented within the WSML2Reasoner framework requires a specific facade. The facade is essential in order to mediate between the generic Datalog representation and the internal representation specific to the single reasoning engines, or between the resulting OWL representation and an OWL reasoning engine (e.g. Pellet). However, aside from simply specifying the reasoning engine of choice (via the API, explained later), the end user mustn't worry about implementing the facades directly.

2.3  Extensions

In addition to the facades which provide an interface for, and implementation of, the underlying reasoning engines, the WSML2Reasoner query extensions (such as the SQL interface for the WSML-Flight-A query language) provide an alternative interface whereby reasoning tasks can be achieved with an alternative query syntax. For more infomation, please refer to section 4.

3  Getting Started

3.1  Releases

The are four basic release variants in accord to included reasoning engine library license agreements. The actual core WSML2Reasoner code base is LGPL.

4  WSML2Reasoner Query Extensions

Purpose of the SQL Interface Extension/WSML-Flight-A Query Language

The purpose of the SQL Interface extension required to accomodate the WSML-Flight-A query language is to provide an easy to use syntactic extension for querying ontologies and to facilitate the following main features:

This is mainly a use case driven extension of SQL originally required to accomodate the WSML-Flight-A query language. Additional motivations and details are given in [1]. Furthermore since this query language is layered on top of WSML-Flight, there are no compatability issues. There is no need to adjust existing ontologies, reasoning components, or other existing dependent software due to the architecture chosen.

Syntax and Usage

The allowed syntax for WSML-Flight-A queries closely corresponds to standard SQL syntax. For an exhaustive, in-depth description we again refer to [1], while [2] and [3] provide a concise overview of the SQL syntax. This section is only meant to serve as a short introduction.

A WSML-Flight-A query in general is of the following form:

	SELECT X1, ...,Xn

Whereby Q is an ordinary WSML-Flight query, X1, ..., Xn are a subset of the variables appearing in Q, and o is the IRI of the ontology over which the query is placed. The WSML-Flight-A extension allows for SQL-like projection via the select expression in the usual SQL-like syntax and semantics. It explicitly supports the following constructs:

With the exception of COUNT(*), all aggregate functions exclude NULL values, as in SQL. The type of the returned value for SUM is subject to deterministic widening to ensure lossless results. Numeric aggregates obviously only return values if and only if all bindings of a variable are also numeric. The return value type for COUNT is integer, for MIN, MAX and AVG it is the same type as the column, for SOME and EVERY it is boolean. For VAR_POP, VAR_SAMP, STDDEV_POP and STDDEV_SAMP statistical functions, the type is always double. Additionally the usual further SQL constructs are possible:

Where orderExpression denotes the usual:

{ column number | column alias | select Expression } [ASC | DESC]

And LIMIT n m creates the result set for the SELECT statement first and then discards the first n rows (OFFSET) and returns the first m rows of the remaining result set (LIMIT).


Following are some short examples for the query expressions. The basic usage of the query extension is very simple. Queries are passed as ordinary String objects, and the WSMLQuery class is the only entry point. Results are returned in the expected WSML2Reasoner wrappers.

	String query = "<query>"
	WSMLQuery wqe = new WSMLQuery();
	Set<Map<Variable, Term>> r = wqe.executeQuery(query);

Complete usage examples are contained in the WSML2Reasoner org.wsml.reasoner.ext.sql test package. Following are short examples to illustrate the syntax of queries and same basic combinations. The first query illustrates one of the simplest use cases of the query extension, in which basically no features are used.

	FROM _http://someontology
	WHERE ?x memberOf ?y"

The second example illustrates the possibility to order query results according to certain variable bindings.

	SELECT ?place, ?employee
	FROM _http://someontology
	WHERE ?employee[hasWorkingPlace hasValue ?place]
	ORDER BY 1, 2

Furthermore it is possible to use aggregates, group results and impose further restrictions on the projection, as in standard SQL.

	SELECT ?place, COUNT(?place)
	FROM _http://someontology
	WHERE ?employee[hasWorkingPlace hasValue ?place]
	GROUP BY ?place
	HAVING COUNT(?place) > 4

Also the order of sorting can be specified, as usual, and the number of results can then be limited to a certain desired amount.

	SELECT ?place, COUNT(?place)
	FROM _http://someontology
WHERE ?employee[hasWorkingPlace hasValue ?place] GROUP BY ?place HAVING COUNT(?place) > 4 ORDER BY ?place DESC LIMIT 2


[1] D1.4: Process Ontology Query Language, Technical report, SUPER IST Project 026850. Stijn Heymans, Cristina Feier, Jos de Bruijn, Stefan Züller, Emilia Cimpian
[2] MySQL 3.23, 4.0, 4.1 Reference Manual -
[3] HSQLDB User Guide, Chapter 9. SQL Syntax -