Title: Ontology Network Manager (OntoNet) ## Terminology Stanbol OntoNet implements the API section for managing OWL and OWL2 ontologies, in order to prepare them for consumption by reasoning services, refactorers, rule engines and the like. Ontology management in OntoNet is sparse and not connected: once loaded internally from their remote locations, ontologies live and are known within the realm they were loaded in. This allows loose-coupling and (de-)activation of ontologies in order to scale the data sets for reasoners to process and optimize them for efficiency.
OntoNet ontology network structure
Figure 1: an example of OntoNet setup for multiple ontology networks, showing the orthogonal layering of sessions, scopes and spaces.
The following concepts have been introduced with OntoNet: * __Ontology scope__: a "logical realm" for all the ontologies that encompass a certain CMS-related set of concepts (such as "User", "ACL", "Event", "Content", "Domain", "Reengineering", "Community", "Travelling" etc.). Scopes never inherit from each other, though they can load the same ontologies if need be. * __Ontology space__: an access-restricted container for synchronized access to ontologies within a scope. The ontologies in a scope are loaded within its set of spaces. An ontology scope contains: (a) one core space, which contains the immutable set of essential ontologies that describe the scope; (b) one (possibly empty) custom space, which extends the core space according to specific CMS needs (e.g. the core space for the User scope may contains alignments to FOAF). * Session: a container of (supposedly volatile) semantic data which need to be intercrossed with one or more Scopes, for stateful management of ontology networks. It can be used to load instances and reason on them using different models (one per scope). An OntoNet Session is not equivalent to an HTTP session (since it can live persistently across multiple HTTP sessions), although its behaviour can reflect the one of the HTTP session that created it, if required by the implementation. -------------------- ## Usage Given the entire knowledge base managed by your CMS, OntoNet allows the construction and management of ontology networks, programmatically via its Java API or RESTful Web Services _(see next section for details on the latter)_. A criterion for choosing the appropriate API can be as follows: * Stanbol plugins or server software that incorporates Stanbol (e.g. larger OSGi platforms) should use the Java API. * Client applications, non-Java CMSs or services decoupled from Stanbol should use the RESTful API. * Java-based CMSs can use either API. ### Java API First and foremost, the concept of __ontology network__ is implicit in the OntoNet API. There is no such thing as an `OntologyNetwork` type. What you do is create `OntologyScope` and `Session` objects and link them together at creation time or when launching a process. #### Accessing the managers. First and foremost let us obtain references to the main OntoNet manager classes. In an OSGi environment they can be obtained by reference: @Reference ONManager onMgr; @Reference SessionManager sesMgr; In a non-OSGi environment they must be instantiated as POJOs (Plain Old Java Objects): TODO #### Managing an ontology scope. Let us now show an example of how to setup an ontology scope, which you should use for storing the models for a certain domain of your knowledge base. In this example we will refer to social networks and communities. ScopeRegistry registry = onMgr.getScopeRegistry(); OntologyScopeFactory factory = onMgr.getOntologyScopeFactory(); /* * Here we create a scope called "social" where we intend * to place all the knowledge needed for modeling social * networks and communities. * * Suppose the FOAF and SIOC ontologies are the only ones * we are concerned with at scope creation time. We tell * the scope factory method to fetch them from their * original locations on the Web. */ try { /* * You can include as many ontology input source as * you want, even none at all. */ OntologyScope scope = factory.createOntologyScope( "social", new RootOntologyIRISource( IRI.create("http://xmlns.com/foaf/spec/index.rdf")), new RootOntologyIRISource( IRI.create("http://rdfs.org/sioc/ns"))); /* * Setup the scope, so its ontologies will be available * via the RESTful API */ // Lock the ontology scope scope.setUp(); // Register the scope and activate it registry.registerScope(scope, true); } catch (OWLOntologyCreationException e1) { /* * Thrown if there was an error creating one of the * ontology sources (e.g. if some URL could not be * resolved or it is not an ontology. */ e1.printStackTrace(); } catch (DuplicateIDException e1) { /* * Thrown if there is already a scope called "social". * In this case we may decide to use the existing one, * so we get it. Note that wen reusing a scope, you * lose the provilege of writing in its core space. * Only the custom space will be open for modification. */ scope = registry.getScope("social"); } If you have not changed any parameters in the OntoNet configuration and have the Ontology Manager Web Service endpoint up and running, you should be able to fetch an RDF file at `http://localhost:8080/ontonet/ontology/social`. Let us check it (in Turtle Syntax): % curl -H "Accept: application/turtle" http://localhost:8080/ontonet/ontology/social @prefix xsd: . @prefix owl: . @prefix : . @prefix xml: . @prefix rdf: . @prefix rdfs: . @base . rdf:type owl:Ontology ; owl:imports . Let us take a look at the imported ontology that represents the core space of the "social" scope. % curl -H "Accept: application/turtle" http://localhost:8080/ontonet/ontology/social/core @base . rdf:type owl:Ontology ; owl:imports , . Here are the `owl:imports` statements for the FOAF and SIOC ontologies, which are hijacked to "internal" versions managed by Stanbol. Of course if a domain namespace other than "http://localhost:8080/" was configured, you will see that one in each import statement. Also note that the import statement for FOAF ends with `http://xmlns.com/foaf/0.1/`, which is different from the IRI we passed to Stanbol `http://xmlns.com/foaf/spec/index.rdf`. This happens because in the case of FOAF the _physical_ IRI (which must be known a priori) differs from its _logical_ IRI (which identifies the ontology and is discovered only when the ontology is read), and OntoNet tends to privilege the logical IRI when one is found, i.e. when the ontology is not anonymous. The FOAF and SIOC ontologies are imported by the core space because they were indicated at _creation_ time. Of course it is possible to onbtain a Java object for the ontology using the Java API. Here is how to export an entire scope to an OWL API object of type `OWLOntology`: /* * To obtain the OWLOntology, we must specify its class as * a return parameter. * We also set the second argument to true, to specifiy * that we want it merged with its imports, so that the * resulting object contains all axioms. */ OWLOntology scopeAsOWL = scope.export(OWLOntology.class, true); An scope can be exported either as an OWL API object or as a Clerezza object. /* * In Clerezza, a Graph is a subclass of TripleCollection, * so it is supported by OntoNet. We could also export a * scope to a MGraph (modifiable Graph). */ Graph scopeAsClerezza = scope.export(Graph, false); #### Ontology input sources. Note that when you add an ontology to a space or session, you pass it an `OntologyInputSource` object, or more precisely, an `OntologyInputSource`. This is because there can be several ways to obtain an ontology, and those most common are supported in Stanbol. For example, it can be obtained by defererencing a IRI and parsing its source code (in RDF/XML, Turtle, etc.), or by reading an input stream, or taking an already stored RDF graph in the Stanbol store; or it could be an ontology Java object created from scratch. An __Ontology input source__ is an object that incorporates (1) the "method" by which an ontology should be accessed; (2) the type of Java object it should create to represent an ontology; (3) where it should store the ontology. * __`OWLOntology` input sources__ comply with the OWL API specification [1] and creates objects of type `OWLOntology` stored in an _in-memory_ `OWLOntologyManager`. It will be stored persistently once added to an ontology network. * `RootOntologySource`. Wraps an already existing `OWLOntology`, therefore it does not provide a physical IRI. * `RootOntologyIRISource`. Tries to locate and load an ontology, and its imports, from a given IRI. It can use a custom `OWLOntologyManager` as a store, and can even override any mappers, in order to force-dereference the IRI. * `ParentPathInputSource`. Tries to load an ontology from a root `File`, and will seek its imports among the files in the same directory as the root `File`. It also allows a custom `OWLOntologyManager` as a store. Loads the ontology source codeWraps an already existing `OWLOntology`, therefore it does not provide a physical IRI. * `BlankOntologySource`. Creates an `OWLOntology` with no ID and no axioms. It can be useful for supplying dummy ontologies to methods that will not admit a null ontology. Note that the blank ontology is not shared: each `BlankOntologySource` has a distinct blank ontology object, and they are _not_ equal! * __`TripleCollection` input sources__ comply with the Apache Clerezza API specification, which is also the default native implementation of OntoNet. The resulting ontology is a subtype of `TripleCollection` (`Graph` or `MGraph`) and uses a `TcProvider` as a store. Depending on the chosen Stanbol storage, it can be pesistent or in-memory. Generally, these input sources take less memory that OWL API counterparts, but do not allow RDF graphs to be managed using the OWL language constructs. Note that any `TripleCollection` can be exported as an `OWLOntology` afterwards, once stored. * `GraphContentInputSource`. Creates a `TripleCollection` by reading an input stream, which can be obtained from a file, URL etc. It can use any `TcProvider` as a store, otherwise it will create an in-memory triple collection, which will be copied to the Stanbol store when adding the ontology to a network. If this `TcProvider` is the `TcManager` used by Stanbol, its triples are not copied across. * `GraphSource`. Wraps an existing `TripleCollection` object. In general, it does not 'know' where the ontology was stored. ### Service Endpoints The OntoNet RESTful API is structured as follows: _(Please note, that the following links to the actual service endpoints link to a running instance of Apache Stanbol. If you use domains or ports other than "localhost:8080", then please change accordingly)_ #### Scopes ("/ontonet/ontology") * The endpoint @ [/ontonet/ontology](http://localhost:8080/ontonet/ontology) shows an overview (as an RDF graph or HTML document) of all registered ontology scopes. * An Ontology Scope @ /ontonet/ontology/{scopeId} provides the de-referenceable OWL form of the ontology scope _scopeId_, inclusive of OWL import statements for the spaces and ontologies therein. #### Sessions ("/ontonet/session") * The endpoint @ [/ontonet/session](http://localhost:8080/ontonet/session) shows an overview (as an RDF graph or HTML document) of all open OntoNet sessions. * A Session @ /ontonet/session/{sessionId} provides the de-referenceable OWL form of the OntoNet Session _sessionId_, inclusive of OWL import statements for the ontologies therein. #### Managed Ontologies ("ontonet/{ontologyId}") * A Managed Ontology @ /ontonet/{ontologyId}, where _ontologyId_ is the full logical IRI that identifies the ontology, provides the RDF form of the ontology with that ID, if that ontology has been stored and is managed by OntoNet (i.e. is in some scope or session). ## References: * [1] OWL API ____ _[Back to Ontology Manager](../)_