ModelSpec howto - describing Jena 2.3 models in RDF

WARNING. The current ModelSpec API (including ModelMakers) and code suffers from some problems which we hope to resolve in post-2.3 Jenas. Users of ModelSpec should be prepared to cope with changes in the CVS version of Jena, especially in the areas of default models, creating vs opening models, and re-opening models.

introduction

This document describes the ModelSpec features for Jena 2.3. It builds on the features from earlier ModelSpecs but adds new description properties for rulesets and reasoners.

The intention is to be able to specify how a model is constructed using a configuration file, input stream, URL, or other way of getting RDF into a Jena process, and for this configuration to be capable of specifying anything that the ModelFactory class can construct.

A more formal document will be available in future releases. (The previous document has been withdrawn, as it no longer reflects the actual or intended state of the code. The philosophy, that of allowing extensible specifications for descibing models, has been retained.) Here we concentrate on how to use ModelSpecs in general.

The ModelSpec descriptions use the Jena Model Specification vocabulary, which is available in the vocabulary class JenaModelSpec [previous known as JMS] and which will be referred to using the prefix jms. Jena defines this vocabulary namespace as

http://jena.hpl.hp.com/2003/08/jms#

creating a ModelSpec

ModelSpecs are created by calling one of the ModelFactory methods named createSpec, which create a ModelSpec from an RDF description. There are three variants of createSpec:

createSpec( Resource r , Model m ). This is the core method. The ModelSpec is created from the sub-graph of m rooted at r. The resource r identifies the model specification.
createSpec( Model m ). The ModelSpec is created from the sub-graph of m rooted at the single resource with type jms:ModelSpec in m.
createSpec( Resource r ). This abbreviates createSpec( r, r.getModel() ).

All ModelSpecs are interpreted using partial RDFS inference with respect to the JMS schema found at vocabularies/jena-mode-spec.n3 and also in the vocabulary class com.hp.hpl.jena.vocabulary.JenaModelSpec.

By "partial" inference, we mean that the vocabulary is RDFS-complete, and that the specification has types inferred from RDFS.domain and RDFS.subClassOf statements. This abbreviated inference avoids some reasoner overheads but allows useful abbreviation in ModelSpecs.

using a ModelSpec

A ModelSpec doesn't describe only a single model, but a way of making many models of the same kind. Often these models are named, or built on named models. The important creation method is:

createModel(): create a new model according to the specification. This method is used by ModelFactory.createModel(ModelSpec). You may need to cast this model to the appropriate type - in particular, if you're expecting an OntModel.

Once a ModelSpec has been constructed, the RDF on which it is based may become inacessible; indeed, it is possible to construct some ModelSpecs without using RDF at all. To regenerate RDF "equivalent" to that description, use:

getDescription(): returns an RDF description which describes this ModelSpec. If the original RDF description had no superfluous statements, this model is likely "the same" as that original, ie isomorphic. This is a useful way to save an RDF description to be used in a later createSpec.

some simple ModelSpec descriptions

We will write our descriptions in N3, rather than RDF/XML, for clarity. We will assume the usual Jena prefixes (rdfs, jms, rdf), call the root resource of the description "_:this", and make heavy use of bnodes. Your own descriptions can use whatever mixtures of bnodes and URIs you like.

plain ModelSpec, no frills

A ModelSpec for plain [non-reasoning], default models can be as simple as

_:this rdf:type jms:DefaultModelSpec .

This will construct a default model (ie the same kind of Model that ModelFactory.createDefaultModel() will construct). If anything more complicated that this is required, then a model maker must be specified.

_:this jms:maker _:maker .

It happens that this specification, where a model maker is mentioned but not further described, also produces a ModelSpec that makes default models. Pick whichever you find most pleasing.

If you wish to create models with different reification styles, then the maker can specify the style explicitly.

_:this jms:maker _:maker .
_:maker jms:reificationStyle jms:rsMinimal .

This will produce models which have the minimal reification style. (For an explanation of the different styles, see the reification howto.

plain ModelSpec, file-based

You can specify a model that is loaded from, and written back to, some file using a FileModelMaker. The model is loaded from the file when it is created, and written back when it is closed. The fileBase, the directory in which the file is found, has to be specified.

_:this jms:maker _:maker .
_:maker jms:fileBase "/tmp" .

Filing-system names are of course implementation-specific, so if you expect to move fileBase-using ModelSpecs between systems, take care.

A file-based ModelSpec can use createModelOver(String s) to create models loaded from the file whose name is s within the fileBase. If the file does not exist, the model will initially be empty, but will be written back when closed.

Of course, a refication style can be specified as well as a filebase. There is no need for a file-based model to be opened with the same style each time it is used - the reification style is not preserved.

plain ModelSpec from a database

A Plain (ie non-inferring, non-ontologogical) model can be a persistent database model. Jena supports JDBC-connected database models; these are specified using an RDB model-maker. Each such model created will use it's own database connection.

_:this jms:maker _:maker .
_:maker jms:reificationMode jms:rsStandard .
_:maker jms:hasConnection _:conn .

_:conn jms:dbURL jdbc:mysql://some.database.machine.eg/jenaDB .
_:conn jms:dbUser "william.blake" .
_:conn jms:dbPassword "tyger, tyger" .
_:conn jms:dbType "MySQL" .

The model-maker is specified as being a Jena RDB model-maker by the hasConnection. Several models may share the same (or similar) connections.

The connection URL specifies the database to connect to; the same database can support many different Jena models. (Note that this is a URI, not a literal.) The user and password are required to (weakly) authenticate the connection. The type is required so that the correct database drivers can be loaded. Note the (in-)security implications of the database password being stored in plain text in the ModelSpec description document - these are partly bypassed by using the shared property discussed later.

an inference model

An inference model is characterised by having a reasoner specification as well as a (base) model-maker specification. The reasoner engine is specified by its URI (as known to the Jena ReasonerRegistry), and additional properties, such as schemas and rules.

_:this jms:maker _:maker .
_:this jms:reasonsWith _:reasoner .
_:reasoner jms:reasoner <http://jena.hpl.hp.com/2003/RDFSExptRuleReasoner> .

[check that the URI remains correct]

This is the simplest reasoner specification - just giving the URL of the reasoner. Any other properties of the reasoner take on its usual defaults.

Reasoners may be supplied with a schema or schemas as the "initial base" for their reasoning - for example, an RDFS reasoner may be given an RDFS schema and do sub-type reasoning in advance of being applied to a particular model. Schemas can be specified by giving their URLs.

_:reasoner jms:schemaURL <http://some.domain.xyz/RDFS/cunning> .

If several schemas are supplied, they are merged into a single schema to feed to the reasoner.

Similarly, a schema can be specified using a ModelSpec.

_:reasoner jms:schema _:modelSpec .

If the reasoner is a rule-based reasoner, it may be loaded with additional rules. Those rules may be specified in the ModelSpec description, or be identified by URL.

_:reasoner jms:ruleSetURL <http://some.domain.xyz/RULES/straight> .

The URL identifies a resource containing the rules, written in an appropriate notation. Several ruleSetURLs may be given; all the rules are loaded into the reasoner in no particular order.

Similarly,

_:reasoner jms:ruleSet _:set .

specifies a set of rules located elsewhere in this specification, as properties of _:set. Multiple such ruleSets can be given, and they may be freely mixed with ruleSetURLs.

ruleSet specifications

The ruleset specifications allow different reasoner specifications to share rule specifications (and possibly the rules themselves). The simplest such specification is the empty one:

_:set rdf:type jms:RuleSet .

which may be useful as a placeholder (or a leftover from pruning away rulesets). Additional rules may be specified inline or by URL:

_:set jms:hasRule "some proper rule text here" .
_:set jms:ruleSetURL <http://some.domain/RULES/example> .

Both hasRule and ruleSetURL may be present as often as required. Since both predicates have domain RuleSet, the type declaration may be omitted.

ontology models

An OntModel specification has additional properties for specifying the ontology language and document-manager details. For example, using the same database connection description as our earlier example,

_:this jms:importMaker _:conn .
_:this jms:ontLanguage "http://www.w3.org/TR/owl-features/#term_OWLLite" .
_:this jms:docManager _:DM .
_:this jms:reasonsWith _:R .

_:R jms:reasoner http://jena.hpl.hp.com/2003/RDFSExptRuleReasoner .

specifies OntModels for the OWL Lite language, using the RDFS rule-based reasoner. The OntModels will take their base models from the database. The document manager has been given no specific properties, so the default document manager will be used.