OWLlink:
Structural Specification

1 Introduction

OWLlink provides a declarative interface to OWL reasoners. It is intended to be a lightweight mechanism giving client applications access to reasoning functionality provided by a server. The OWLlink core defines primitives for handling and manipulation of OWL Knowledge Bases (KBs), such as asserting axioms, as well as primitives for asking questions about KB entities. Each KB given to the reasoner is a self-contained collection of facts and axioms.

2 Preliminaries

The OWLlink interface makes a number of assumptions:

• The protocol is agnostic to multiple client connections. Multi-threaded OWLlink server implementations may be provided, but no guarantees are made as to the semantics when clients attempt to simultaneously update and query.
• The connection to the server is effectively stateless. Clients are not identified to the reasoner, thus the server will not distinguish between clients and maintain any kind of consistency checking or record of which client is adding information or making requests. Conversely, a client has no way of ensuring that the server has not been given additional information (such as additional axioms) since its last communication.
• There is no explicit classification request. The server will decide when it is appropriate to, for example, compute the classification hierarchy of concepts. This may happen after each Knowledge Base modification, alternatively the server may choose to defer the classification until absolutely necessary.
• An OWLlink Knowledge Base (KB) is a self-contained collection of facts and class as well as property axioms. OWLlink does not explicitly provide any support for modularity or import of KBs. Client applications will thus have to resolve any issues related to the handling of imports before passing a KB to an OWLlink client.

3 Basic Protocol

3.1 Sessions and Messages

Before sending a request to an OWLlink server, a client must establish an OWLlink session to the server that abstracts the actual bidirectional communication channel between the client and the server. The actual implementation of a session provides primitives to transport requests and responses and is defined by the transport mechanism used to access an OWLlink server.

OWLlink servers are allowed to service several clients concurrently. However, interaction within one OWLlink session is not concurrent. An OWLlink session is assumed to transport requests and responses sequentially. Each request should be processed by the OWLlink server such that the results are the same as if the requests were processed sequentially in the order they were dispatched. Furthermore, the server must send the responses to the client in exactly the same order in which the requests arrived. OWLlink does not prescribe how concurrent requests issued through different OWLlink sessions are to be handled. Servers are free to provide their own mechanisms for isolating interaction between different OWLlink sessions.

An OWLlink session can be terminated by the client or the server. Furthermore, due to environmental circumstances (e.g., network problems or timeouts), an OWLlink session can be broken asynchronously. Regardless of the cause, all requests issued on an OWLlink session that were not completed when the OWLlink session was terminated must be made invalid. The exact meaning of this is not precisely specified. An OWLlink server can, but is not required to, implement a transaction mechanism for rolling back not completed requests. If a client establishes a different OWLlink session, an OWLlink server should not send any responses for the invalid requests: each response can be transmitted only through the OWLlink session through which the request was initiated.

The basic interaction pattern of OWLlink is that of request-response. The fundamental objects used in the protocol are presented in Figure 1.

• Each request is defined by its type, a subclass of the Request class, and the (possibly empty) set of parameters. To call a service of an OWLlink server, a client constructs a request of the appropriate type and sends it to the server.
• After receiving a request and processing it, an OWLlink server constructs an appropriate response object and sends it to the client. Depending on the type of the request, the server should select the appropriate subclass of the Response class.

Each request is paired with exactly one response. Depending on the transport mechanism, it might be inefficient to send individual requests to an OWLlink server at a time. Therefore, OWLlink allows to bundle requests into messages. As shown in Figure 1, a RequestMessage object encapsulates a list of Request objects, whereas a ResponseMessage object encapsulates a list of Response objects.

Each request message must correspond to exactly one response message. The response message must contain the responses to all the requests from the request message, and all responses must be listed in the response in the order matching with the order of the corresponding requests. The responses must be the same as if the requests were executed sequentially in the order specified in the request message. Note that an OWLlink server is free to execute the requests in any way it wishes, as long as the requests are seemingly executed sequentially. For example, if a request to update the Knowledge Base is followed by a query request, the responses to the query must take the updates into account.

3.2 Confirmation and Error Handling

Each request in OWLlink must be accompanied by a corresponding response (cf. Figure 1). Request primitives that address a specific Knowledge Base are subclasses of the abstract KBRequest class and the corresponding confirmations are subclasses of the abstract KBResponse class. If a request has been processed successful, the type of the response returned depends on the request and may contain additional data. If a request does not produce any specific data, the OWLlink server should still return a Confirmation response to the client. For example, if a request to write axioms into a Knowledge Base succeeds, only a confirmation response is returned indicating that all axioms were added successfully.

A Confirmation (or any sub-type thereof) may contain a warning. For example, an OWLlink server may accept sets containing repetitions of objects without raising a warning. However, it may be useful to warn the user if this has happened, as this may indicate a spelling or typographical mistake.

If a request cannot be executed, the OWLlink server should return an Error response to the OWLlink client containing a message specifying the cause for failure. Specific error classes are defined to report syntactic violations (SyntaxError), semantic problems (SemanticError) and problems regarding the management of a Knowledge Base (KBError).

If a server cannot process a request, it should attempt to recover gracefully, and process other pending requests as if the error did not happen. If, however, this recovery is not possible the server should close the OWLlink session after sending the Error response. The state of the server after such an action is not prescribed by this specification.

This specification does not require requests that modify a Knowledge Base to execute atomically. For example, a request for adding axioms to a Knowledge Base might fail after several axioms have been already added. In this case, the OWLlink server is not required to roll back the already processed axioms — the behavior of the server is implementation-specific. Nevertheless, OWLlink implementors are encouraged to ensure that requests which modify a Knowledge Base are executed atomically.

3.3 Identification and Status

3.4 Knowledge Base Management

OWLlink servers can manage more than one KB simultaneously. Each OWLlink KB is identified with a unique URI on creation. These URIs provide a handle that identifies the particular incarnation of the KB in the particular server. Most OWLlink requests are derived from the KBRequest class, which requires a kb parameter identifying the KB to which the request applies. If a KB with the given URI cannot be found, the server should return a KBError object.

A new KB is allocated within the OWLlink server by sending a CreateKB request (cf. Figure 3). If the optional argument kb of type URI is given, the new KB is allocated with this URI, otherwise a new (server-generated) URI is used. On successful creation of the new KB, a KB object containing the URI that identifies the allocated KB is returned. However, if the given URI is already in use by another KB allocated before or the KB could not be allocated for some other reasons (e.g., a low memory condition), the response to the CreateKB request is a KBError. Freshly allocated KBs are initially empty, not containing any fact or axiom. Note that the only way to produce an empty KB (without using advanced features like retraction of course) is through a CreateKB request. The optional name argument of a CreateKB request allows to associate a name with a KB on creation. Such KB names do not have to be unique and thus cannot be used to identify a certain KB. However, named KBs are published together with their identifying KB URI in the servers Description object and thus can be accessed from multiple clients.

The use of unique URIs allows to sidestep some of the issues relating to multiple clients. If a client chooses not to share a KB URI with another client (either directly or by making it public through passing a name on creation), then the client can be sure that it is the only one interacting with that KB. This is not entirely the case, as a malicious client could choose to try sending messages with random URIs to a running OWLlink server. There is a (very small) chance that such a client could get lucky and hit on a URI which is in use, but this potential situation is unlikely enough not to be concerned with it.

Different clients of the same server, like KB browsers or explanation tools, however, may want to share KBs by sharing URIs or making KBs public through naming — it is then the clients' responsibility to manage and coordinate this sharing.
The possibility to pass an identifying URI along with a CreateKB request, allows OWLlink KBs to stand alone — a situation that is useful, say for test suites and benchmarking.

The actual settings of a KBs options can be retrieved by sending a GetSettings request (see Figure 4). The Settings response does not need to be equal to the corresponding section within the Description object, as the value of an option may at any time be modified using a Set request (see Figure 5). The response to a successful Set request is an OK object indicating that the value of the corresponding option has been set to the given value within the server. At any time, the value reported by a Settings object for an option has to correspond to the value of the previous successful Set request for that option, or, in case no such request was ever issued, the default value for that option as reported in the Description object. Note that a server might at any time decide to refuse a Set request. For example, a server might support the change of certain options only if the corresponding KB is still empty. In that case, or if the addressed option is not supported or the value does conflict with the options type annotation, it has to return a corresponding Error object without modifying the value of the option.

It is good practice for clients to release a KB once it is not in use any more, as this allows the OWLlink server to free the resources allocated for the KB. This can be done using the ReleaseKB request (see Figure 5), to which the server should respond on success with the OK response and otherwise with a KBError. Once a KB has been released, any further requests using its URI result in a KBError.

3.5 Extensions

Different reasoners support different languages as well as different reasoning facilities. To support these differences, OWLlink is extensible. Current candidates for extensions are:

4 Tells

Figure 6 shows the primitive for adding content to a KB via OWLlink. Since OWLlink 2 relies on the concept language of OWL 2 for expressing content, it basically refers to the OWL 2 axioms. More precisely, the Tell request adds a set of OWL 2 axioms to the specified KB. Analogous to the definition of an ontology in OWL 2 an OWLlink KB is defined by a set of unordered axioms without repetitions in the sense of structural equivalence. An OWLlink server must not return an error in case a structurally equivalent axiom is submitted a second time but is free to provide a warning. It should, however, keep only one copy of the structurally equivalent axiom. If a server states to ignore annotations it also has to take this into account when checking for structural equivalence, i.e. has to filter annotations at all levels of the tell language beforehand.
If all axioms are successfully added to the KB, the server should respond with a Ok response.

A request may contain a mixture of arbitrary management, tell, and ask requests. This allows, for example, to create self-containing test cases for OWLlink servers. For instance, one single request may include the creation of a KB (with a user given URI) followed by a tell, an ask, more tells, and further asks.

5 Asks

5.1 Retrieving KB Entities

Each particular request depicted in Figure 7 returns a set of all corresponding named OWL 2 entities of the referenced KB. That is a possibly empty SetOfXXX consisting of ox.XXX where XXX is one of OWLClass, ObjectProperty, DataProperty, Datatype, Individual, or AnnotationProperty. Note that semantically equivalent entities are not grouped or marked as such.
Note that GetAllIndividuals return the set of all named individuals (ground facts). The SetOfDatatypes response has to consist of all built-in and user defined datatypes which are actually referenced within the axioms of the KB.

In case an OWLlink server ignores all annotation axioms it must not return annotation properties as well as classes, properties, etc. which only occur in annotation axioms. Furthermore, if a server ignores declarations, all declared entities will not be part of the responses unless they are referenced elsewhere. On the other hand, when considering declarations the responses have to account for declared entities in all responses.

5.2 Checking KB Status

5.3 Queries about Classes and Properties

5.3.1 Querying Classes

The basic asks of Figure 9 about one or more classes all return a boolean value and cover requests such as class subsumption, class satisfiability, class equivalence, and class disjointness.

Both queries return a set of class synonym sets. The synonym sets embrace those classes which are equivalent to each other.

The equivalent classes of a OWL class description can be retrieved with help of the GetEquivalentClasses query of Figure 11. This query returns a (potentially empty) set of other class names A_n (SetOfClasses response) which are equivalent to the given description C (see left hand side of Fig. 11), that is A_k^Ic = C^Ic for 1 ≤ k ≤ n.

5.3.2 Retrieving the Class Hierarchy

The complete class hierarchy can be retrieved utilizing a single request, namely GetSubClassHierarchy. This request has an optional argument which is a class name (see Figure 11). Without giving a class name this query returns all super-/sub-class pairs of the KB, whereas the first element consists of a synset of classes and the second of a set of sub-class synsets (ClassHierarchy response). The latter set may be an empty set in case the super class has no sub classes other than the unsatisfiable class. There is no order of class-subclass pairs within the response. The two predefined OWL class entities owl:Nothing and owl:Thing are not considered in the class sub-class pairs of this response (unless there is a class which is equivalent to them) . This is because of two reasons: (1) to have analogous responses in comparison to the property hierarchy requests (where comparable predefined entities do not exist) (2) to minimize the number of pairs to be transfered (by ruling out redundant pairs). Therefore, when retrieving the initial hierarchy of a just created KB the response will contain no class sub-class pair.
See the following examples use square brackets "[]" for ClassSubClassPairs, curly brackets "{}" for SetOfSubClassSynsets and round brackets "()" for ClassSynsets. The respective responses to the GetSubClassHierarchy query, namely ClassHierarchy are enclosed with angle brackets "⟨⟩":

When providing a class name as argument to GetSubClassHierarchy a fraction of the hierarchy will be returned starting with the supplied class as root.

5.3.3 Querying Object Properties

Likewise to the class asks above there are analog asks about object properties as shown in Figure 12.

Furthermore, the IsObjectPropertyXXX checks for the various characteristics an object property can have. Here XXX can be one of Functional, InverseFunctional, Reflexive, Irreflexive, Symmetric, Asymmetric, or Transitive.

Queries about sub- as well as super-object properties are given in Figure 13. The answers to these queries are sets of object property synsets. Likewise to the corresponding class queries these queries also have a direct flag in order to retrieve all or only the direct sub- resp. super-object properties.

The request for retrieving equivalent (GetEquivalentObjectProperties) and unsatisfiable object properties (GetUnsatisfiableObjectProperties) and the object property hierarchy are shown in Figure 14. Their respective response is a set of object properties (SetOfObjectProperties response).
The result set of the GetDisjointObjectProperties query in Figure 15 is a set of object property synsets (SetOfObjectPropertySynsets).

The object property hierarchy can be retrieved with GetSubObjectPropertyHierarchy (Figure 15). It is analogical to the corresponding class query and returns pairs consisting of object property synsets and their corresponding set of sub-object property synsets. Note that since there is no predefined unsatisfiable (as well as universal) property in OWL 2 this reveals no information about unsatisfiable object properties.

5.3.4 Querying Data Properties

Essentially the same queries as for object properties are provided for data properties. There is one exception with respect to the characteristics of data properties which are limited to IsDataPropertyFunctional as can be seen in Figure 16.

The queries for retrieving all as well as only direct sub- and super-data properties are depicted in Figure 17.

Requests for querying important data property relationships are given in Figure 18. The result set to GetEquivalentDataProperties return a set of equivalent other data properties. With help of GetUnsatisfiableDataProperties one can retrieve the set of non-satisfiable data properties. GetDisjointDataProperties returns a set of data property synsets which are disjoint to the given one.

Likewise to the object property hierarchy, GetSubDataPropertyHierachy (Figure 19) responds with pairs of super- and sub-data properties.

5.4. Queries about Facts

The following queries refer to ground facts. This means that they are only sensitive to named individuals of the underlying KB. For instance, retrieving the fillers of an object property r with respect to an individual i (see GetObjectPropertyFillers in Figure 27) given a KB containing solely the axiom ClassAssertion(i MinCardinality(1 r)) will return the empty set since there is no named individual in the KB which satisfies the query condition.

5.4.1 Queries about Individuals

AreIndividualsEquivalent respectively AreIndividualsDisjoint returns true in case a set of provided individuals are all the same or all different from each other. More precisely, for n individuals a_n AreIndividualsEquivalent returns true if a_j^Ii = a_k^Ii with 1 ≤ j, k ≤ n for every model I of the KB. The contrary case (AreIndividualsDisjoint) returns true if a_j^Ii ≠ a_k^Ii with 1 ≤ j, k ≤ n and j ≠ k. In case an OWLlink server has the UNA enabled AreIndividualsEquivalent always returns false and AreIndividualsDisjoint always true when asked with different identifiers.

Whether an individual is an instance of a class description can be checked with help of IsInstanceOf. For an individual a and a description C this query returns true in case a^Ii ∈ C^Ic holds in every model I of the KB.

In order to retrieve the classes an individual is an instance of GetTypes can be used as depicted in Figure 21. For an individual a it returns all synonym sets of named classes A where a^Ii ∈ A^Ic in all models I of the KB. When setting the direct flag to true the query returns only the most specific class synonym sets of the previous answer, namely those where there is no B with a^Ii ∈ B^Ic where B^Ic ⊂ A^Ic.

The flattened variant GetFlattenTypes rules out any information about class equivalence from the response by simply returning a set of classes.

Figure 22 show the the GetDisjointIndividuals query which answers with a set of synsets containing all those individuals b_n for a given a with a^Ii ≠ b_j^Ii where 1 ≤ j ≤n.

The equivalent individuals to an individual are returned as result to the query GetEquivalentIndividuals (Figure 23) which answers with a potentially empty set of equivalent individuals to a, namely all b_n with a^Ii = b_j^Ii where 1 ≤ j ≤n. This query as well as the flattened variant for retrieving disjoint individuals (GetFlattenDisjointIndividuals) also returns a set of individuals.

5.4.2 Queries about Properties related to Individuals

To retrieve the object properties originating from a source individual or pointing to a target individual GetObjectPropertiesOfSource and GetObjectPropertiesOfFiller are provided (see Figure 24). They return a set of object property synsets. The object properties of a source individual a are those object properties R where there exists an individual b such that (a^Ii, b^Ii) ∈ R^Ipo in all models of the KB (and vice versa for the corresponding filler query). The query GetObjectPropertiesBetween returns all object properties which relate two given individuals.

The negative flag of those queries indicates whether this queries refer to the positive (default) or negative object property assertions. When set to true this flag refers to NegativeObjectPropertyAssertions which state that two entities are not related by a property. For instance, the result set of the GetObjectPropertiesOfSource query will then contain all object properties R where there exists an individual b such that (a^Ii, b^Ii) ∉ R^Ipo in all models of the KB.

Figure 25 shows the asks for checking whether two individuals or an individual and a constant are related via a given property (AreIndividualsRelated resp. IsIndividualRelatedWithConstant).

In Figure 26 there are the corresponding data property queries from above (Figure 24) in order to retrieve data properties which relate individuals with constants.

5.4.3 Queries about related Individuals

The queries GetObjectPropertyFillers and GetObjectPropertySources take an object property and an originating/target individual and return all fillers resp. sources with respect to the property (see Fig. 27). The result consists of a set of individual synsets. Formally, given an individual a and an object property R the GetObjectPropertyFillers response consists of all individuals b_n where (a^Ii, b_k^Ii) ∈ R^Ipo for 1 ≤ k ≤ n in all models of the KB (and vice versa for the corresponding source query). The negative flags refer to the kind of property assertion (either positive or negative).

GetInstances returns those individuals which are instances of a provided description, i.e. all a wrt. C for which a^Ii ∈ C^Ic. When setting its direct flag to true the result set excludes those individuals which are also instances of sub-classes of the given description.

The queries about related individuals also come in a so called flattened variant as shown in Figure 28. Here, the result set contains exactly the same individuals as before but is made flat in terms of not grouping equivalent individuals anymore. This is especially useful when applying the unique name assumption (UNA) where different identifier always refer to different individuals.

5.4.4 Queries about Individuals Related to Constants

Likewise to the queries about related individuals there are queries with respect to individuals related to constants via data properties. Those queries allow to retrieve the source individuals for a given data property and constant as well as the constant for a given individual and data property (Figure 29). Note that the negative flag, in contrast to the object property queries, is only allowed within GetDataPropertySources (it is simply unclear how to deal with an infinite result set; e.g. GetDataPropertyFillers[negative=true](i, r) with functional(r), domain(r, xsd;integer) and r(i, 1)).

The former also comes with a flattened variant (see Figure 30) in order to trade semantic information (about equivalent individuals) for a smaller result message in case communication performance is of high importance to the client.

6. References