ModelSpec howto - describing Jena 2.2 models in RDF

introduction

This document describes the ModelSpec features for Jena 2.2. They build on the experimental features available in Jena 2.0 and 2.1, but have been extended to increase flexibility and uniformity.

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: the ModelSpec design document. 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 and which will be referred to using the prefix jms. Jena defines this vocabulary namespace as

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

differences from the original ModelSpecs

The revised ModelSpec differs from the original in several minor ways and a few major ones, those being:

the additional of specifications for rulesets and schemas.
the separation out of database connection specifications.
the special type Shared to allow values to be shared by specifications. [Shared is not implemented.]

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 unique resource with type jms:ModelSpec.
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 RDF.typestatements. This abbreviated inference avoids some reasoner overheads.

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.

PlainModelSpec, 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 specificiation, where a model maker is identified 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 THAT DOCUMENT.

PlainModelSpec, 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.

PlainModelSpec 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. [Discussed later, when we've sorted out the unresolved issue of model specs that identify particular models.]

_: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 my 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.

shared specifications

[Not implemented in this release.]

By default, each time a model is constructed using a ModelSpec, new instances of all the subcomponents of that description are created. This is not always a wise choice, especially if those subcomponents consume lots of space or take a long time to prepare - eg, a large schema for a reasoner.

Any sub-specification can be made shared by giving it the Shared type:

_:conn rdf:type jms:Shared .

When a component of type Shared is requested, if there is already a Shared component created from equivalent RDF, then that component is returned rather than a new component being created.

The method ModelFactory.share( Resource r, Object o ) declares that the resource r, which must have RDF type Shared, has shared value o. Any modelspec component whose description matches r will resolve to the value o.

By "equivalent RDF" we mean that the submodels reachable from r are isomorphic.

So, for the database connection example, the resource _:conn can be declared shared in the user's application, without the user's database name and password appearing in the ModelSpec.