You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jena.apache.org by ch...@apache.org on 2012/10/16 17:20:36 UTC
svn commit: r1398843 [1/2] - in /jena/Scratch/Eyeball/trunk/doc: ./
eyeball-1-doc/
Author: chrisdollin
Date: Tue Oct 16 15:20:36 2012
New Revision: 1398843
URL: http://svn.apache.org/viewvc?rev=1398843&view=rev
Log:
added version info to document names, started docs for E2.4.
Added:
jena/Scratch/Eyeball/trunk/doc/eyeball-2.3-brief.html
- copied unchanged from r1398314, jena/Scratch/Eyeball/trunk/doc/brief.html
jena/Scratch/Eyeball/trunk/doc/eyeball-2.3-full-template.html
- copied unchanged from r1398314, jena/Scratch/Eyeball/trunk/doc/full-template.html
jena/Scratch/Eyeball/trunk/doc/eyeball-2.3-full.html
- copied unchanged from r1398314, jena/Scratch/Eyeball/trunk/doc/full.html
jena/Scratch/Eyeball/trunk/doc/eyeball-2.3-index.html
- copied unchanged from r1398314, jena/Scratch/Eyeball/trunk/doc/index.html
jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-brief.html
jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-full-template.html
jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-full.html
jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-index.html
Removed:
jena/Scratch/Eyeball/trunk/doc/brief.html
jena/Scratch/Eyeball/trunk/doc/classpath.text
jena/Scratch/Eyeball/trunk/doc/eyeball-1-doc/
jena/Scratch/Eyeball/trunk/doc/full-template.html
jena/Scratch/Eyeball/trunk/doc/full.html
jena/Scratch/Eyeball/trunk/doc/index.html
jena/Scratch/Eyeball/trunk/doc/old-full.html
Added: jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-brief.html
URL: http://svn.apache.org/viewvc/jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-brief.html?rev=1398843&view=auto
==============================================================================
--- jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-brief.html (added)
+++ jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-brief.html Tue Oct 16 15:20:36 2012
@@ -0,0 +1,406 @@
+<html>
+<head>
+<title>Eyeball 2.4</title>
+<link type="text/css" rel="stylesheet" href="styles/doc.css">
+</head>
+<body>
+
+<h1>caveat</h1>
+
+This document is a work-in-progress; refer to the
+<a href="full.html">manual</a> for details when this page
+doesn't help.
+
+<h1>brief guide</h1>
+
+<p>
+So you've got Eyeball installed and you've run it on one of your
+files, and Eyeball doesn't like it. You're not sure why, or what
+to do about it. Here's what's going on.
+
+<p>
+Eyeball inspects your model against a set of <i>schemas</i>.
+The default set of schemas includes RDF, RDFS, the XSD datatypes,
+and any models your model imports: you can add additional schemas
+from the command line or configuration file.
+Eyeball uses those schemas to work out what URIs count as "declared"
+in advance. It also checks URIs and literals for syntactic
+correctness and name space prefixes for being "sensible".
+Let's look at some of the messages you can get.
+
+<h2>unknown predicate reports</h2>
+
+<p>
+You'll probably find several messages like this:
+
+<pre>
+predicate not declared in any schema: <i>somePredicateURI</i>
+</pre>
+
+Eyeball treats the imported models, and (independently) the
+specified schemas, as single OntModels, and extracts those
+OntModels' properties. It includes the RDF and RDFS schemas.
+Anything used as a predicate that isn't one of those properties
+is reported.
+
+<p>If you're using OWL, you can silence the "undeclared property"
+messages about OWL properties by adding to your Eyeball command line
+the option:
+
+<blockquote>
+-assume owl
+</blockquote>
+
+<p>
+Eyeball will read the OWL schema (it has a copy stashed away in the
+<i>mirror</i> directory) and add the declared properties to
+its known list. This works for any filename or URL you like, so long as
+there's RDF there and it has a suitable file suffix - <i>.n3</i> for
+N3 or <i>.rdf</i> or <i>.owl</i> for RDF/XML - and for the built-in
+names <i>dc</i> (basic Dublin Core), <i>dcterms</i> (Dublin Core terms)
+and <i>dc-all</i> (both). So you
+can construct your own schemas, which declare your own domain-specific
+property declarations, and invoke Eyeball with
+
+<blockquote>
+-assume owl <i>mySchemaFile.n3</i> <i>otherSchemaFile.rdf</i>
+</blockquote>
+
+<p>
+You can give short names (like <b>dc</b> and <b>rdfs</b>) to
+your own schemas, or collections of schemas, using an Eyeball
+<i>config file</i>, but you'll have to see the
+<a href="full.html">manual</a> to find out how.
+
+<h2>unknown class reports</h2>
+
+<p>
+You may see messages like this:
+
+<pre>
+class not declared in any schema: <i>someClassURI</i>
+</pre>
+
+<p>
+Having read the previous section, you can probably work out
+what's going on: Eyeball reads the schemas (and imports)
+and extracts the declared OntClasses. Then anything used
+as a class that isn't one of those declared classes is
+reported..
+
+<p>
+And that's exactly it. "Used as a class" means appearing
+as <b>C</b> or <b>D</b> in any statement of the form:
+
+<ul>
+<li>_ rdf:type C
+<li>_ rdfs:domain C
+<li>_ rdfs:range C
+<li>C rdfs:subClassOf D
+</ul>
+
+<h2>suppressing inspectors</h2>
+
+<p>
+It may be that you're not interested in the "unknown predicate"
+or "unknown class" reports until you've sorted out the URIs.
+Or maybe you don't care about them. In that case, you can
+switch them off.
+
+<p>
+Eyeball's different checks are carried out by <i>inspector</i>
+classes. These classes are given short names by entries in
+Eyeball config files (which are RDF files written using N3; you
+can see the default config file by looking in Eyeball's
+<code>etc</code> directory for <code>eyeball2-config.n3</code>).
+By adding eg:
+
+<blockquote>
+-exclude property class
+</blockquote>
+
+<p>to the Eyeball command line, you can <i>exclude</i> the inspectors
+with those short names from the check. <i>property</i> is the
+short name for the "unknown property" inspector, and
+<i>class</i> is the short name for the "unknown class"
+inspector.
+
+<h2>namespace and URI reports</h2>
+
+Eyeball checks all the URIs in the model, including (if available)
+those used for namespaces. (And literals, but see below.) Here's
+an example:
+
+<pre>
+bad namespace URI: "file:some-filename"
+ on prefix: "pqr"
+ for reason: file URI inappropriate for namespace
+</pre>
+
+A "bad namespace URI" means that Eyeball doesn't like the URI
+for a namespace in the model. The "on prefix" part of the
+report says what the namespace prefix is, and the "for reason"
+part gives the reason. In this case, we (the designer of Eyeball)
+feel that it is unwise to use file URIs - which tend to depend
+on internal details of your directory structure - for global
+concepts.
+
+<p>A more usual reason is that the URI is syntactically illegal.
+Here are some possibilities:
+
+<table border>
+
+<tr>
+ <td>URI contains spaces
+ <td>literal spaces are not legal in URIs. This usually arises from
+ file URIs when the file has a space in its name. Spaces in URIs
+ have to be encoded.
+
+<tr>
+ <td>URI has no scheme
+ <td>The URI has no scheme at all. This usually happens when some relative
+ URI hasn't been resolved properly, eg there's no xml base in an
+ RDF/XML document.
+
+<tr>
+ <td>URI has an unrecognised scheme
+ <td>The scheme part of the URI - the bit before the first colon - isn't
+ recognised. Eyeball knows, by default, four schemes:
+ <b>http</b>, <b>ftp</b>, <b>file</b>, and <b>urn</b>. This
+ usually arises when a QName has "escaped" from somewhere, or from
+ a typo.
+
+ <p>You can tell Eyeball about other schemes, if you need them.
+
+<tr>
+ <td>scheme should be lower-case
+ <td>The scheme part of the URI contains uppercase letters. While this
+ is not actually <i>wrong</i>, it is unconventional and pointless.
+
+<tr>
+ <td>URI doesn't fit pattern
+ <td>Eyeball has some (weak) checks on the syntax of URIs in different
+ schemes, expressed as patterns in its config files. If a URI doesn't
+ match the pattern, Eyeball reports this problem. At the moment,
+ you'll only get this report for a <b>urn</b> URI like
+ <i>urn:x-hp:23487682347</i> where the URN id (the bit between the
+ first and second colons, here <i>x-hp</i>) is illegal.
+
+<tr>
+ <td>URI syntax error
+ <td>A catch-all error: Java couldn't make any sense of this URI at all.
+
+</table>
+
+<h2>problems with literals</h2>
+
+<p>Eyeball checks literals (using the <i>literal inspector</i>,
+whose short name is <b>literal</b> if you want to switch it off),
+but the checking is quite weak because it doesn't understand
+types at the moment. You can get two different classes of error.
+
+<pre>
+bad language: someLanguageCode
+on literal: theLiteralInQuestion
+</pre>
+
+<p>Literals with language codes (things like <b>en-UK</b> or
+<b>de</b>) are checked to make sure that the language code
+conforms to the general syntax for language codes: alphanumeric
+words separated by hyphens, with the first containing no digits.
+
+<p>(Later versions of Eyeball will likely allow you to specify
+<i>which</i> language codes you want to permit in your models.
+But we haven't got there yet.)
+
+<pre>
+bad datatype URI: someURI
+on literal: theLiteralInQuestion
+for reason: theReason
+</pre>
+
+<p>Similarly, literals with datatypes are checked to make sure
+that the type URI is legal. That's it for the moment: Eyeball
+doesn't try to find out if the URI really is a type URI, or
+if the spelling of the literal is OK for that type. But it
+spots the bad URIs. (The messages are the same as those that
+appear in the URI checking - above - for the very good reason
+that it's the same code doing the checking.)
+
+<h2>problematic prefixes</h2>
+
+<p>
+Both RDF/XML and N3 allow (and RDF/XML requires) namespaces to
+be abbreviated by prefixes. Eyeball checks prefixes for two
+possible problems. The first:
+
+<pre>
+non-standard namespace for prefix
+</pre>
+
+<p>
+This arises when a "standard" prefix has been bound to a namespace
+URI which isn't its usual one. The "standard" prefixes are taken from
+Jena's <code>PrefixMapping.Extended</code> and are currently:
+
+<blockquote>
+<b>rdf, rdfs, daml, owl, xsd, rss, vcard</b>
+</blockquote>
+
+<p>And the second:
+
+<pre>
+Jena generated prefix found
+</pre>
+
+<p>
+This arises when the model contains prefixes of the form <code>j.N</code>,
+where N is a number. These are generated by Jena when writing RDF/XML
+for URIs that must have a prefix (because they are used as types or
+predicates) but haven't been given one.
+
+<p>
+If you're not bothered about inventing short prefixes for your
+namespaces, you can <b>-exclude</b> <code>jena-prefix</code>
+to suppress this inspection.
+
+<h1>but how do I ...</h1>
+
+<p>The reports described so far are part of Eyeball's default
+set of inspections. There are some other checks that it can do
+that are switched off by default, because they are expensive,
+initially overwhelming, or downright obscure. If you need
+to add these checks to your eyeballing, this is how to do it.
+</p>
+
+<h2>... make sure everything is typed?</h2>
+
+<p>
+Some applications (or a general notion of cleanliness) require
+that every individual in an RDF model has an explicit
+<code>rdf:type</code>. The Eyeball check for this isn't
+enabled by default, because lots of casual RDF use doesn't
+need it, and more sophisticated use has models with enough
+inference power to infer types.
+
+<p>
+You can add the <b>all-typed</b> inspector to the inspectors
+that Eyeball will run by adding to the command line:
+
+<blockquote>
+-inspectors defaultInspectors all-typed
+</blockquote>
+
+<p>The <b>all-typed</b> inspector will generate a message
+
+<pre>
+resource has no rdf:type
+</pre>
+
+<p>for each resource in the model which is not the subject of
+an <code>rdf:type</code> statement.
+
+<h2>... check for type consistency?</h2>
+
+<p>
+One easy mistake to make in RDF is to make an assertion - we'll
+call it <b>S P O</b> - about some subject <b>S</b> which is
+"of the wrong type", that is, not of whatever type <b>P</b>'s
+domain is. This isn't, in principle, an error, since RDF resources
+can have multiple types, and this just makes <b>S</b> have a type
+which is a subtype of both <b>P</b>'s domain and whatever type
+it was supposed to have.
+
+<p>To spot this, and related problems, Eyeball has the
+<b>consistent-type</b> inspector. You can add it to the
+inspections in the same way as the <b>all-typed</b>
+inspector:
+
+<blockquote>
+-inspectors defaultInspectors consistent-type
+</blockquote>
+
+<p>
+It checks that every resource which has been given at least
+one type has a type which is a subtype of all its types,
+under an additional assumption:
+
+<blockquote>
+Types in the type graph (the network of rdfs:subClassOf statements)
+are disjoint (share no instances) unless the type graph says they're
+not.
+</blockquote>
+
+<p>For example, suppose that both <b>A</b> and <b>B</b> are
+subclasses of <b>Top</b>, ande that there are no other subclass
+relationships. Then <b>consistent-types</b> assumes that there
+are (supposed to be) no resources which have both <b>A</b> and
+<b>B</b> as types. If it finds a resource <b>X</b> which <i>does</i>
+have both types, it generates a message like this:
+
+<pre>
+no consistent type for: X
+has associated type: A
+has associated type: B
+has associated type: Top
+</pre>
+
+<p>
+It's up to you to disentangle the types and work out what went
+wrong.
+
+<p>
+<i>Note</i>: this test requires that Eyeball do a significant amount
+of inference, to complete the type hierarchy and check the
+domains and ranges of proeprties. It's quite slow, which is
+one reason it isn't switched on by default.
+
+<h2>... check the right number of values for a property?</h2>
+
+<p>You want to make sure that your data has the right properties
+for things of a certain type: say, that a book has at least one
+author (or editor), an album has at least one track, nobody in
+your organisation has more than ten managers, a Jena contrib
+has at least a <code>dc:creator</code>, a <code>dc:name</code>,
+and a <code>dc:description</code>. You write some OWL
+<i>cardinality constraints</i>:
+
+<blockquote>
+my:Type rdfs:subClassOf [owl:onProperty my:track; owl:minCardinality 1]
+</blockquote>
+
+Then you discover that, for wildly technical reasons, the OWL
+validation code in Jena doesn't think it's an error for some
+album to have no tracks (maybe there's a namespace error).
+</p>
+
+<p>You can enable Eyeball's <i>cardinality inspector</i> by
+adding
+
+<blockquote>
+-inspectors cardinality
+</blockquote>
+
+to the command line. You'll now get a report item for every resource
+that has <code>rdf:type</code> your restricted type (<code>my:Type</code>
+above) but doesn't have the right (at least one) value for the property.
+It will look something like:
+
+<pre>
+cardinality failure for: my:Instance
+ on type: my:Type
+ on property: my:track
+ cardinality range: [min: 1]
+ number of values: 0
+ values: {}
+</pre>
+
+If there are some values for the property - say you've supplied
+an <code>owl:maxCardinality</code> restriction and then gone
+over the top - they get listed inside the <code>values</code>
+curly braces.
+</p>
+
+
+</body>
+</html>
Added: jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-full-template.html
URL: http://svn.apache.org/viewvc/jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-full-template.html?rev=1398843&view=auto
==============================================================================
--- jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-full-template.html (added)
+++ jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-full-template.html Tue Oct 16 15:20:36 2012
@@ -0,0 +1,1397 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+ <title>Eyeball 2.4</title>
+ <link type="text/css" rel="stylesheet" href="styles/doc.css" />
+ <script>
+ function invert( id )
+ {
+ x = document.getElementById( id )
+ x.className = x.className == "hide" ? "show" : "hide"
+ }
+ </script>
+</head>
+<body>
+ <h1>summary</h1>
+
+ <p>This document describes Eyeball 2.4, an
+ "<a href="http://www.w3.org/RDF/">RDF</a>
+ <a href="http://en.wikipedia.org/wiki/Lint_programming_tool">lint</a>";
+ see the
+ <a href="ReleaseNotes.text">release notes</a> for descriptions
+ of changes from previous versions.
+ Eyeball is part of the Jena family of RDF/OWL tools: see
+ <a href="http://jena.sourceforge.net">jena.sourceforge.net</a>
+ for the Jena documentation and downloads. Support for the
+ Jena family is provided on the mailing lists
+ <i>jena-dev@yahoogroups.com</i> (for developers using Jena)
+ and <i>jena-devel@lists.sourceforge.net</i> (for developers
+ modifying or extending Jena). Note that, ny support is provided
+ on a voluntary basis, as and when the effort is available.
+ </p>
+
+ <p>
+ Throughout this document, the prefix <i>eye</i> stands for the
+ URL <i>http://jena.hpl.hp.com/Eyeball#</i>.
+ </p>
+
+ <h1 onClick="invert('TOC')">table of contents [click to reveal]</h1>
+
+ <div id="TOC" class="hide">
+ <div class="toc">
+ </div>
+ </div>
+
+ <h1>Eyeball - checking RDF for common problems</h1>
+
+ <p>Eyeball is a
+ library and command-line tool for checking RDF and OWL models for
+ various common problems. These problems often result in
+ technically correct but implausible RDF. Eyeball checks against
+ user-provided schema files and makes various closed-world
+ assumptions.
+ </p>
+
+ <p>Eyeball 2.4 can check for:</p>
+
+ <ul>
+ <li>unknown [with respect to the schemas] properties and classes</li>
+ <li>bad prefix namespaces</li>
+ <li>ill-formed URIs, with user-specifiable constraints</li>
+ <li>ill-formed language tags on literals</li>
+ <li>datatyped literals with illegal lexical forms</li>
+ <li>unexpected local names in schema namespaces</li>
+ <li>untyped resources and literals</li>
+ <li>individuals having consistent types, assuming complete typing</li>
+ <li>likely cardinality violations</li>
+ <li>broken RDF list structures</li>
+ <li>suspected broken use of the typed list idiom</li>
+ <li>obviously broken OWL restrictions</li>
+ <li>user-specified constraints written in SPARQL</li>
+ </ul>
+
+ <p>Eyeball's checks are performed by Inspector plug-ins and can
+ be customised by the user. Rendering its reports to output is
+ performed by Renderer plug-ins which can also be customised by
+ the user.</p>
+
+ <h2>installation</h2>
+
+ <p>Fetch the Eyeball distribution zipfile and unpack it somewhere
+ convenient. Read the documention in the <i>doc</i> directory: the
+ one-minute guide <i>index.html</i>, the brief introduction
+ <i>brief.html</i>, and when necessary the manual <i>full.html</i>
+ (that's what this is).</p>
+
+ <p>Eyeball 2.4 comes with its own copy of Jena 2.5 with CVS
+ updates. Do <i>not</i> attempt to use other versions of Jena with
+ Eyeball.</p>
+
+ <p>In the Eyeball distribution directory, run the Eyeball
+ tests:
+ </p>
+
+ <blockquote>
+ ant test
+ </blockquote>
+
+ <p>
+ If these tests fail, something is wrong.
+
+ (The message <i>(Note:
+ statistician test disabled; don't worry about this.)</i> is not a
+ failure.)
+
+ Sometimes
+ it's no more than a classpath problem, which you can fix. If not,
+ use the <i>jena-dev</i> mailing list to request assistance. Note that,
+ just as with Jena itself, any support is provided on a voluntary
+ basis, as and when the effort is available.
+ </p>
+
+ <p>
+ If the tests have passed, you can use Eyeball from the installation
+ directory, or copy <i>lib</i>, <i>etc</i> and <i>mirror</i> to
+ somewhere convenient.
+ </p>
+
+ <h2>command line operation</h2>
+
+ <p>
+ You must ensure that <i>all</i> the Eyeball jars from <i>lib</i>
+ are on your classpath. (Note that Eyeball comes with its own Jena
+ jar files and <i>may not work</i> with other Jena jars.) The
+ directories <i>etc</i> and <i>mirror</i> should be in the
+ current directory or also on your classpath.
+ </p>
+
+ <p>Run the Eyeball command:</p>
+
+ <pre>
+java [java options eg classpath and proxy] jena.eyeball
+ (-check | -sign | -accept) specialURL+
+ [-assume Reference*]
+ [-config fileOrURL*]
+ [-set Setting*]
+ [-root rootURI]
+ [-render Name]
+ [-include shortName*]
+ [-exclude shortName*]
+ [-analyse | -repair]
+ [-remark] [-version]
+</pre>
+
+ <p>
+ The -<i>whatever</i> sections can come in any order
+ and may be repeated, in which case the additonal arguments are appended
+ to the existing ones. Exactly one of <i>-check</i>, <i>-sign</i>,
+ <i>-accept</i>, or <i>version</i> must be provided; all the other
+ options are optional.
+ </p>
+
+ <p>
+ When Eyeball resolves ordinary filenames or URLs it uses the
+ Jena file manager to possibly map those names (<i>eg</i> to
+ redirect an <code>http:</code> URL to a local cached copy).
+ See the
+ <a href="http://jena.sourceforge.net/how-to/filemanager.html">
+ file manager howto</a> for details on how to configure the
+ file manager.
+ </p>
+
+ <h3>examples of command-line use</h3>
+
+ <pre>
+java jena.eyeball -version
+
+java jena.eyeball -check myDataFile.rdf
+
+java jena.eyeball -assume dc -check http://example.com/nosuch.n3
+
+java jena.eyeball -assume mySchema.rdf -check myData.rdf -render xml
+
+java jena.eyeball -check myData.rdf -include consistent-type
+
+java jena.eyeball -check myConfig.ttl -sign >signedConfig.ttl
+</pre>
+
+ <h3>-check specialURL+</h3>
+
+ <p>The <i>-check</i> command checks the specified models for
+ problems. The <i>specialURL</i>s designate the models to be
+ checked. In the simplest case, these are plain filenames,
+ <code>file:</code> URLs, or <code>http:</code> URLs. At least one
+ <i>specialURL</i> must be specified. Each specified model is
+ checked independently of the others.</p>
+
+ <pre>
+-check myModel.ttl
+-check file:///c:/rdf/pizza.owl
+-check http://example.com/rdf/beer.rdf
+</pre>
+
+ <p>If the <i>specialURL</i> is of the form <i>ont:NAME:base</i>,
+ then the checked model is the model <i>base</i> treated as an
+ OntModel with the specification
+ <code>OntModelSpec.<i>NAME</i></code>; see <a href=
+ "http://jena.sourceforge.net/ontology/index.html#creatingModels">the
+ Jena ontology documentation</a> for the available names.</p>
+ <pre>
+-check ont:OWL_MEM_RDFS_INF:myModel.ttl
+-check ont:OWL_DL_MEM_RULE_INF:http://example.com/rdf/beer.rdf
+</pre>
+
+ <p>If the <i>specialURL</i> is of the form <i>ja:R@AF</i>, then
+ the model is that described by the resource <i>R</i> in the Jena
+ <a href=
+ "http://jena.sourceforge.net/assembler/index.html">assembler</a>
+ description file <i>AF</i>. <i>R</i> is prefix-expanded using the
+ prefixes in <i>AF</i>.</p>
+ <pre>
+-check ja:my:root@my-assembly.ttl
+-check ont:OWL_MEM_RDFS_INF:my:root@my-assembly.ttl
+</pre>
+
+ <p>If the URL (or the base) is of the form
+ <i>jdbc:DB:head:model</i>, then the checked model is the one
+ called <i>model</i> in the database with connection
+ <i>jdbc:DB:head</i>. (The database user and password must be
+ specified independently using the <i>jena.db.user</i> and
+ <i>jena.db.password</i> system properties.)</p>
+ <pre>
+-check jdbc:mysql://localhost/test:example
+</pre>
+
+ <h3>-config fileOrURL and -root rootURI</h3>
+
+ <p>The <i>-config fileOrURL</i> options specify the Eyeball
+ <a href=
+ "http://jena.sourceforge.net/assembler/index.html">assembler</a>
+ configuration files to load. A single configuration model is
+ constructed as the union of the contents of those files. If this
+ option is omitted, the default configuration file
+ <i>etc/eyeball-config.n3</i> is loaded. See <a href=
+ "#inside-configuration">inside the Eyeball configuration file</a>
+ for details of the configuration file.</p>
+ <pre>
+-config my-hacked-config-file.n3
+-config etc/eyeball-config.n3 extras.ttl
+</pre>
+
+ <p>The <i>-root rootURI</i> option specifies the root resource in
+ the Eyeball configuration. If this option is omitted,
+ <i>eye:eyeball</i> is used by default. <i>rootURI</i> is
+ prefix-expanded using the prefixes in the configuration file.</p>
+ <pre>
+-root my:root
+-root my:sparse-config
+-root urn:x-hp:eyeball-roots:special
+</pre>
+
+ <h3>-set Setting*</h3>
+
+ <p>
+ The <i>-set</i> option allows command-line tweaks to the
+ configuration, <i>eg</i> for enabling checking URIs for
+ empty local names. <i>You will rarely need to use this</i>;
+ it is presented here because of its association with
+ the <code>-config</code> and <code>-root</code> options.
+ </p>
+
+ <p>
+ Each <i>Setting</i> has the form <code>S.P=O</code> and adds
+ the statement <code>(S' P' O')</code> to the configuration.
+ </p>
+
+ <p>
+ The current Eyeball converts the components of the
+ <code>S.P=O</code> string into RDF nodes <code>S'</code>,
+ <code>P'</code>, <code>O'</code> using some special rules:
+ </p>
+
+ <ul>
+ <li>
+ A component starting with a digit is treated as an
+ xsd:integer literal (and hence should only appear as
+ the object of the setting).
+ </li>
+
+ <li>
+ A component starting with a quote, either <code>"</code>
+ or <code>'</code>, is treated as a literal whose lexical
+ form extends to the matching closing quote. Note:
+ (a) <i>literals with embedded spaces are not supported</i>;
+ (b) your command-line interpreter may treat quotes
+ specially, and to allow the quotes to pass through to
+ Eyeball, you'll have to use another (different) pair of
+ quotes!
+ </li>
+
+ <li>
+ A component starting with <code>_</code> is treated
+ as a blank node with that label.
+ </li>
+
+ <li>
+ Otherwise, the component is treated as a URI reference.
+ If it starts with a prefix (<i>eg</i>, <code>rdf:</code>)
+ that prefix is expanded using the prefixes of the configuration
+ file. If it has no prefix, it is as though the empty prefix
+ was specified: in the default configuration file, that is
+ set to the Eyeball namespace, so it is as though the prefix
+ <code>eye:</code> had been used.
+ </li>
+ </ul>
+
+ <p>
+ For example, to enable the URI inspectors non-default reporting
+ of URIs with empty local names, use:
+ </p>
+
+ <pre>
+-set URIInspector.reportEmptyLocalNames="'true'"
+</pre>
+
+ <p>
+ Note the nested different quotes required to pass 'true'
+ to Eyeball so that it can interpret this as a literal.
+ </p>
+
+ <h3>-include/-exclude shortNames</h3>
+
+ <p>
+ The various Eyeball inspectors are given <i>short names</i> in
+ the configuration file. By default, an Eyeball check uses a
+ specific set of inspectors with short name
+ <i>defaultInspectors</i>. Additional inspectors can be enabled
+ using the <i>-include</i> option, and default inspectors can be
+ disabled using the <i>-exclude</i> option. See below for the
+ available inspectors and their short names, and see <a href=
+ "#inspectors-configuration">inspectors configuration</a> for
+ how to configure inspectors.
+ </p>
+
+ <pre>
+-include list all-typed
+-exclude cardinality
+-include owl -exclude consistent-type
+</pre>
+
+ <h3>-assume Reference</h3>
+
+ <p>The -assume <i>Reference</i>s identifies any assumed schemas
+ used to specify the predicates and classes of the data model. The
+ reference may be a file name or a URL (and may be mapped by the
+ file manager).</p>
+
+ <p>Eyeball automatically assumes the RDF and RDFS schemas, and
+ the built-in XSD datatype classes. The short name <i>owl</i> can
+ be used to refer to the OWL schema, <i>dc</i> to the Dublin Core
+ schema, <i>dcterms</i> to the Dublin Core terms schema, and
+ <i>dc-all</i> to both.</p>
+
+<pre>
+-assume owl
+-assume owl dc-all
+-assume owl my-ontology.owl
+</pre>
+
+ <h3>-sign and -accept (experimental)</h3>
+
+ <p>If <i>-sign</i> is specified, Eyeball first does a
+ <i>-check</i>. If no problem reports are
+ generated, Eyeball writes a <i>signed</i> version of
+ the current model to the standard output. The signature
+ records the Eyeball configuration used and a weak hash
+ of the model. If the input model is already signed, that
+ signature is discarded before computing the new signature
+ and writing the output.
+ </p>
+
+ <p>
+ If <i>-accept</i> is specified, the model is checked for its
+ signature. If it is not signed, or if the signature does
+ not match the content of the model -- either the hash fails,
+ or the recorded configuration is not sufficient -- a problem
+ is reported; otherwise not.
+ </p>
+
+ <p>
+ The intended use of <i>-sign</i> and <i>-accept</i>
+ is that an application can require signed models
+ which have passed some minimum set of inspections.
+ The application code can then rely on the model
+ having the desired properties, without having to
+ run potentially expensive validation checks every
+ time a model is loaded.
+ </p>
+
+ <p>
+ <i>Important</i>. Model signing is intended to catch careless
+ mistakes, not for security against malicious users.
+ </p>
+
+ <h3>-version</h3>
+
+ <p>
+ Eyeball will print its version on the standard error
+ stream (currently "<i>Eyeball 2.4 (A Verbs Omen)</i>").
+ </p>
+
+ <h3>-remark</h3>
+
+ <p>Normally Eyeball issues its report or signed model to
+ the standard output and exits with code 0 (success)
+ or 1 (failure) with no additional output. Specifying
+ <i>-remark</i> causes it to report <i>success</i>
+ or <i>some problems reported</i> to standard error.
+ </p>
+
+
+ <h3>-repair and -analyse (experimental)</h3>
+
+ <p>These operations are not currently documented. Try them at
+ your peril: <i>-repair</i> may attempt to update your models.
+ </p>
+
+ <h3>-render Name</h3>
+
+ <p>The eyeball reports are written to the standard output; by
+ default, the reports appear as text (RDF rendered by omitting the
+ subjects - which are all blank nodes - and lightly prettifying
+ the predicate and object). To change the rendering style, supply
+ the <i>-render</i> option with the name of the renderer as its
+ value. Eyeball comes with N3, XML, and text renderers; the
+ Eyeball config file associates renderer names with their
+ classes.</p>
+ <pre>
+-render n3
+-render rdf
+</pre>
+
+ <h3>setting the proxy</h3>
+
+ <p>
+ If any of the data or schema are identified by an http: URL,
+ and you are behind a firewall, you will need specify the proxy to
+ Java using system properties; one way to do this is by using the
+ Java command line options:
+ </p>
+
+ <pre>
+ -DproxySet=true
+ -DproxyHost=theProxyHostName
+ -DproxyPort=theProxyPortNumber
+</pre>
+
+ <h2>inspectors shipped with Eyeball</h2>
+
+ <p>Eyeball comes with a collection of inspectors that do
+ relatively simple checks.</p>
+
+ <h3>PropertyInspector (short name: "property")</h3>
+
+ <p>Checks that every predicate that appears in the model is
+ declared in some <i>-assume</i>d schema or
+ <code>owl:import</code>ed model -- that is, is given
+ <code>rdf:type</code> <code>rdf:Property</code> or some subclass
+ of it.</p>
+
+ <h3>ClassInspector (short name: "presumed-class")</h3>
+
+ <p>Checks that every resource in the model that is used as a
+ class, <i>ie</i> that appears as the object of an
+ <code>rdf:type</code>, <code>rdfs:domain</code>, or
+ <code>rdfs:range</code> statement, or as the subject or object of
+ an <code>rdfs:subClassOf</code> statement, has been declared as a
+ <code>Class</code> in the <i>-assume</i>d schemas or in the model
+ under test.</p>
+
+ <h3>URIInspector (short name: "URI")</h3>
+
+ <p>Checks that every URI in the model is well-formed according to
+ the rules of the Jena IRI library. May apply additional rules
+ specified in the configuration file: see <a href=
+ "#uri-configuration">uri configuration</a> later for details.</p>
+
+ <h3>LiteralInspector (short name: "literal")</h3>
+
+ <p>
+ Checks literals for syntactically correct language codes,
+ syntactically correct datatype URIs (using the same rules as the
+ URIInspector), and conformance of the lexical form of typed
+ literals to their datatype.
+ </p>
+
+ <h3>PrefixInspector (short name: "prefix")</h3>
+
+ <p>The PrefixInspector checks that the prefix declarations of the
+ model have namespaces that are valid URIs and that if the prefix
+ name is "well-known" (<code>rdf</code>, <code>rdfs</code>,
+ <code>owl</code>, <code>xsd</code>, and <code>dc</code>) then the
+ associated URI is the one usually associated with the prefix.</p>
+
+ <p>The PrefixInspector also reports a problem if any prefix looks
+ like an Jena automatically-generated prefix,
+ <code>j.<i>Number</i></code>. (Jena generates these prefixes when
+ writing RDF/XML if the XML syntactically requires a prefix but
+ the model hasn't defined one.)</p>
+
+ <h3>VocabularyInspector (short name: "vocabulary")</h3>
+
+ <p>Checks that every URI in the model with a namespace which is
+ mentioned in some schema is one of the URIs declared for that
+ namespace -- that is, it assumes that the schemas define a closed
+ set of URIs.</p>
+
+ <p>The inspector may be configured to suppress this check for
+ specified namespaces: see <a href=
+ "#configure-vocabulary">vocabulary configuration</a> later.</p>
+
+ <h3>OwlSyntaxInspector (short name: "owl")</h3>
+
+ <p>This inspector looks for "suspicious restrictions" which have
+ some of the OWL restriction properties but not exactly one
+ owl:onProperty and exactly one constraint (owl:allValuesFrom,
+ etc).</p>
+
+ <h3>SparqlDrivenInspector (short name: "sparql")</h3>
+
+ <p>The SparqlDrivenInspector is configured according to <a href=
+ "#SPARQL-driven">configuring the SPARQL-driven inspector</a>, and
+ applies arbitrary SPARQL queries to the model. The queries can be
+ required to match or prohibited from matching; a problem is
+ reported if the constraint fails.</p>
+
+ <h3>AllTypedInspector (short name: "all-typed")</h3>
+
+ <p>
+ Checks that all URI and bnode resources in the model have an
+ rdf:type property in the model or the schema(s). If there is
+ a statement in the confiuration with property
+ <code>eye:checkLiteralTypes</code> and value <code>eye:true</code>,
+ also checks that every literal has a type or a language.
+ <i>Not</i> in the default set of inspectors.
+ </p>
+
+ <h3>ConsistentTypeInspector (short name: "consistent-type")</h3>
+
+ <p>
+ Checks that every subject in the model can
+ be given a type which is the intersection of the subclasses of
+ all its "attached" types -- a "consistent type".
+ </p>
+
+ <p>
+ For example, if the model contains three types
+ <code>Top</code>, <code>Left</code>, and <code>Right</code>, with
+ <code>Left</code> and <code>Right</code> both being subtypes of
+ <code>Top</code> and with no other subclass statements, then some
+ <code>S</code> with <code>rdf:type</code>s <code>Left</code> and
+ <code>Right</code> would generate this warning.
+ </p>
+
+ <h3>CardinalityInspector (short name: "cardinality")</h3>
+
+ <p>
+ Looks for classes <i>C</i> that are subclasses of cardinality
+ restrictions on some property <i>P</i> with cardinality range
+ <i>min</i> to <i>max</i>. For any <i>X</i> of <code>rdf:type</code>
+ <i>C</i>, it checks that the number of values of <i>P</i> is in
+ the range <i>min..max</i> and generates a report if it isn't.
+ </p>
+
+ <p>Literals are counted as distinct if their values (not just their
+ lexical form) are distinct. Resources are counted as distinct if
+ they have different case-sensitive URIs: the CardinalityInspector
+ takes no account of <code>owl:sameAs</code> statements.
+ </p>
+
+ <h3>ListInspector (short name: "list")</h3>
+
+ <p>The ListInspector performs two separate checks:
+ </p>
+
+ <ul>
+ <li>looks for lists that are ill-formed by having multiple or
+ missing rdf:first or rdf:rest properties on their elements.
+ </li>
+
+ <li>looks for possible mis-uses of the "typed list" idiom, and
+ reports the types so defined.
+ </li>
+ </ul>
+
+ <p>The <i>typed list idiom</i> is boilerplate OWL for defining
+ a type which is List-of-T for some type T. It takes the form:
+ </p>
+
+ <pre>
+my:EList a owl:Class
+ ; rdfs:subClassOf rdf:List
+ ; rdfs:subClassOf [owl:onProperty rdf:first; owl:allValuesFrom my:Element]
+ ; rdfs:subClassOf [owl:onProperty rdf:rest; owl:allValuesFrom my:EList]
+ .
+</pre>
+
+ <p>
+ The type <code>my:Element</code> is the element type of the
+ list, and the type <code>EList</code> is the resulting typed list.
+ The list inspector checks that all the subclasses of
+ <code>rdf:List</code> (such as <i>EList</i> above) that are also
+ subclasses of any bnode (such as the two other superclasses of
+ <i>EList) </i>that has any property (<i>eg</i>, <i>owl:onProperty</i>)
+ that has as an object either <code>rdf:first</code> or
+ <code>rdf:rest</code> is a subclass defined by the full idiom above:
+ if not, it reports it as a <code> suspectListIdiom</code>.
+ </p>
+
+ <h2>Eyeball problem reports</h2>
+
+ <p>Eyeball generates its reports as <i>items</i> in a model. Each
+ item has <code>rdf:type</code> <code>eye:Item</code>, and its
+ other properties determine what problem report it is. The default
+ text renderer displays a prettified form of each item; use
+ <i>-render n3</i> to expose the complete report structure.
+ </p>
+
+ <p>One of the item's properties is its <i>main property</i>,
+ which identifies the problem; the others are qualifications
+ supplying additional detail.
+ </p>
+
+ <h3>PropertyInspector: predicate not declared</h3>
+
+ <blockquote>
+ [] eye:unknownPredicate "<i>URIString</i>".
+ </blockquote>
+
+ <p>The predicate with the given URI is not defined in any
+ of the <i>-assumed</i> schemas.
+ </p>
+
+ <h3>ClassInspector: class not declared</h3>
+
+ <blockquote>
+ [] eye:unknownClass "<i>URIString</i>".
+ </blockquote>
+
+ <p>The resource with the given URI is used as a Class, but not
+ defined in any of the <i>-assumed</i> schemas.
+ </p>
+
+ <h3>URIInspector: bad URI</h3>
+
+ <blockquote>
+ [] eye:badURI "<i>URIString</i>"; eye:forReason <i>Reason</i>.
+ </blockquote>
+
+ <p>The <i>URIString</i> isn't legal as a URI, or is legal but fails
+ a user-specified spelling constraint. <i>Reason</i> is a
+ resource or string identifying the reason.
+ </p>
+
+ <table border="1" style="margin-left: 4ex; margin-right: 4ex; font-size: x-small">
+ <thead>
+ <tr><th>reason</th><th>explanation</th></tr>
+ </thead>
+ <tr>
+ <td>eye:uriContainsSpaces</td>
+ <td>the URI contains unencoded spaces, probably as a result
+ of sloppy use of file: URLs.</td>
+ </tr>
+
+ <tr>
+ <td>eye:uriFileInappropriate</td>
+ <td>a URI used as a namespace is a file: URI, which is
+ inappropriate as a global identifier.</td>
+ </tr>
+
+ <tr>
+ <td>eye:uriHasNoScheme</td>
+ <td>a URI has no scheme field, probably a misused relative
+ URI.</td>
+ </tr>
+
+ <tr>
+ <td>eye:schemeShouldBeLowercase</td>
+ <td>the scheme part of a URI is not lower-case; while
+ technically correct, this is not usual practice.</td>
+ </tr>
+
+ <tr>
+ <td>eye:uriFailsPattern</td>
+ <td>a URI fails the pattern appropriate to its schema (as
+ defined in the configuration for this eyeball).</td>
+ </tr>
+
+ <tr>
+ <td>eye:unrecognisedScheme</td>
+ <td>the URI scheme is unknown, perhaps a misplaced
+ QName.</td>
+ </tr>
+
+ <tr>
+ <td>eye:uriNoHttpAuthority</td>
+ <td>an http: URI has no authority (domain name/port)
+ component.</td>
+ </tr>
+
+ <tr>
+ <td>eye:uriSyntaxFailure</td>
+ <td>the URI can't be parsed using the general URI syntax,
+ even with any spaces removed.</td>
+ </tr>
+
+ <tr>
+ <td>eye:namespaceEndsWithNameCharacter</td>
+ <td>a namespace URI ends in a character that can appear in a
+ name, leading to possible ambiguities.</td>
+ </tr>
+
+ <tr>
+ <td>eye:uriHasNoLocalname</td>
+ <td>a URI has no local name according to the XML
+ name-splitting rules. (For example, the URI
+ <i>http://x.com/foo#12345</i> has no local name because a
+ local name cannot start with a digit.)</td>
+ </tr>
+
+ <tr>
+ <td>"did not match required pattern <i>Tail<sub>i</sub></i> for prefix <i>Head</i>".
+ </td>
+ <td>This badURI starts with <i>Head</i>, but the remainder doesn't
+ match any of the <i>Tail<sub>i</sub></i>s associated with that
+ prefix.
+ </td>
+ </tr>
+
+ <tr>
+ <td>"matched prohibited pattern <i>Tail</i> for prefix <i>Head</i>".
+ </td>
+ <td>This badURI starts with <i>Head</i>, and the remainder matched
+ a prohibited <i>Tail</i> associated with that prefix.
+ </td>
+ </tr>
+ </table>
+
+ <h3>LiteralInspector: illegal language code</h3>
+
+ <blockquote>
+ [] eye:badLanguage "<i>badCode</i>"; eye:onLiteral "<i>spelling</i>".
+ </blockquote>
+
+ <p>A literal with the lexical form <i>spelling</i> has the illegal
+ language code <i>badCode</i>.
+ </p>
+
+ <h3>LiteralInspector: bad datatype URI</h3>
+
+ <blockquote>
+ [] eye:badDatatypeURI "<i>badURI</i>"; eye:onLiteral "<i>spelling</i>".
+ </blockquote>
+
+ <p>A literal with the lexical form <i>spelling</i> has the illegal
+ datatype URI <i>badURI</i>.
+ </p>
+
+ <h3>LiteralInspector: bad lexical form</h3>
+
+ <blockquote>
+ [] eye:badLexicalForm "<i>spelling</i>"; eye:forDatatype "<i>dtURI</i>".
+ </blockquote>
+
+ <p>A literal with the datatype URI <i>dtURI</i> has the lexical form
+ <i>spelling</i>, which isn't legal for that datatype.
+ </p>
+
+ <h3>PrefixInspector: bad namespace URI</h3>
+
+ <blockquote>
+ [] eye:badNamespaceURI "<i>URIString</i>"
+ ; eye:onPrefix "<i>prefix</i>"
+ ; eye:forReason <i>Reason</i>.
+ </blockquote>
+
+ <p>The namespace <i>URIString</i> for the declaration of <i>prefix</i>
+ is suspicious for the given <i>Reason</i> (see the URIInspector reports
+ for details of the possible reasons).
+ </p>
+
+ <h3>PrefixInspector: Jena prefix found</h3>
+
+ <blockquote>
+ [] eye:jenaPrefixFound "<i>j.Digits</i>"; eye:forNamespace "<i>URIString</i>".
+ </blockquote>
+
+ <p>The namespace <i>URIString</i> has an automatically-generated
+ Jena prefix.
+ </p>
+
+ <h3>PrefixInspector: multiple prefixes for namespace</h3>
+
+ <blockquote>
+ [] eye:multiplePrefixesForNamespace "<i>NameSpace</i>"
+ ; eye:onPrefix "<i>prefix<sub>1</sub>"</i> ...
+ </blockquote>
+
+ <p>
+ There are multiple prefix declarations for <i>NameSpace</i>,
+ namely, <i>prefix<sub>1</sub></i> etc.
+ </p>
+
+ <h3>VocabularyInspector: not from schema</h3>
+
+ <blockquote>
+ [] eye:notFromSchema "<i>NameSpace</i>"; eye:onResource <i>Resource</i>.
+ </blockquote>
+
+ <p>The <i>Resource</i> has a URI in the <i>NameSpace</i>, but isn't declared
+ in the schema associated with that <i>NameSpace</i>.
+ </p>
+
+ <h3>OwlSyntaxInspector: suspicious restriction</h3>
+
+ <blockquote>
+ [] eye:suspiciousRestriction <i>R</i>; eye:forReason <i>Reason</i>...
+ </blockquote>
+
+ <p>The presumed restriction <i>R</i> is suspicious for the given <i>Reason</i>s:
+ <ul>
+ <li><code>eye:missingOnProperty</code> -- there is no
+ <code>owl:onProperty</code> property in this suspicious restriction.
+ </li>
+ <li><code>eye:multipleOnProperty</code> -- there are multiple
+ <code>owl:onProperty</code> properties in this suspicious restriction.
+ </li>
+ <li><code>eye:missingConstraint</code> -- there is no <code>owl:hasValue</code>,
+ <code>owl:allValuesFrom</code>, <code>owl:someValuesFrom</code>,
+ or <code>owl:[minC|maxC|c]ardinality</code> property in this suspicious
+ restriction.
+ </li>
+ <li><code>eye:multipleConstraint</code> -- there are multiple constraints
+ (as above) in this suspicious restriction.
+ </li>
+ </ul>
+ </p>
+
+ <p>The restriction <i>R</i> is identified by (a) supplying its immediate properties,
+ and (b) identifying its named equivalent classes and subclasses.
+ </p>
+
+ <h3>SparqlDrivenInspector: require failed</h3>
+
+ <blockquote>
+ [] eye:sparqlRequireFailed "<i>message</i>".
+ </blockquote>
+
+ <p>A SPARQL query that was required to succeed against the model did not.
+ The <i>message</i> is either the query that failed or a meaningful
+ description, depending on the inspector configuration.
+ </p>
+
+ <h3>SparqlDrivenInspector: prohibit failed</h3>
+
+ <blockquote>
+ [] eye:sparqlProhibitFailed "<i>message</i>".
+ </blockquote>
+
+ <p>A SPARQL query that was required to fail against the model did not.
+ The <i>message</i> is either the query that succeeded or a meaningful
+ description, depending on the inspector configuration.
+ </p>
+
+ <h3>AllTypedInspector: should have type</h3>
+
+ <blockquote>
+ [] eye:shouldHaveType <i>Resource</i>.
+ </blockquote>
+
+ <p>The <i>Resource</i> has no <code>rdf:type</code>. Note that
+ when using models with inference, this report is unlikely, since
+ inference may well give the resource a type even if it has
+ no explicit type in the original model.
+ </p>
+
+ <h3>ConsistentTypeInspector: inconsistent types for resource</h3>
+
+ <blockquote>
+ [] eye:noConsistentTypeFor <i>URI</i>
+ ; eye:hasAttachedType <i>TypeURI<sub>i</sub></i> ...
+ </blockquote>
+
+ <p>
+ The resource <i>URI</i> has been given the various types
+ <i>TypeURI<sub>i</sub></i>, but if we assume that subtypes are
+ disjoint unless otherwise specified, these types have no
+ intersection.
+ </p>
+
+ <p>The ConsistentTypeInspector must do at least some type
+ inference. This release of Eyeball compromises by doing RDFS
+ inference augmented by (very) limited union and intersection
+ reasoning, as described in the Jena rules in
+ <code>etc/owl-like.rules</code>, so its reports must be
+ treated with caution. Even with these restrictions, doing type inference
+ over a large model is costly: you may need to suppress it with
+ <code>-exclude</code> until any other warnings are dealt
+ with.
+ </p>
+
+ <p>While, technically, a resource with no attached types at all
+ is automatically inconsistent, Eyeball quietly ignores such
+ resources, since they turn up quite often in simple RDF
+ models.
+ </p>
+
+ <h3>CardinalityInspector: cardinality failure</h3>
+
+ <blockquote>
+ [] eye:cardinalityFailure <i>Subject</i>; eye:onType <i>T</i>; eye:onProperty <i>P</i>
+ </blockquote>
+
+ <p>
+ The <i>Subject</i> has a cardinality-constrained <code>rdf:type</code> <i>T</i>
+ with <code>owl:onProperty</code> <i>P</i>, but the number of distinct values
+ in the model isn't consistent with the cardinality restriction.
+ </p>
+
+ <p>Additional properties describe the cardinality restriction and the values found:
+
+ <ul>
+ <li><code>eye:numValues</code> <i>N</i>: the number of distinct values
+ for (<i>Subject</i>, <i>P</i>) in the model.
+ </li>
+ <li><code>eye:cardinality</code>
+ [<code>eye:min</code> <i>min</i>; <code>eye:max</code> <i>max</i>]:
+ the minimum and maximum cardinalities permitted.
+ </li>
+ <li><code>eye:values</code> <i>Set</i>:
+ A blank node of type <code>eye:Set</code> with an <code>rdfs:member</code>
+ value for each of the values of <i>P</i>.
+ </li>
+ </ul>
+ </p>
+
+ <h3>ListInspector: ill-formed list</h3>
+
+ <blockquote>
+ [] eye:illFormedList <i>URI</i>
+ ; eye:because [eye:element <i>index<sub>i</sub></i>; <i>Problem<sub>i</sub></i>]<sub>i</sub> ...
+ </blockquote>
+
+ <p>The list starting at <i>URI</i> is ill-formed because the element with
+ index <i>index<sub>i</sub></i> had <i>Problem<sub>i</sub></i>. The
+ possible problems are:
+ <ul>
+ <li><code>eye:hasNoRest</code> -- the element has no <code>rdf:rest</code> property.
+ </li>
+ <li><code>eye:hasMultipleRests</code> -- the element has more than one
+ <code>rdf:rest</code> property.
+ </li>
+ <li><code>eye:hasNoFirst</code> -- the element has no <code>rdf:first</code> property.
+ </li>
+ <li><code>eye:hasMultipleFirsts</code> -- the element has more than one
+ <code>rdf:rest</code> property.
+ </li>
+ </ul>
+
+ </p>
+
+ <h3>ListInspector: suspect list idiom</h3>
+
+ <blockquote>
+ [] eye:suspectListIdiom <i>Type</i>.
+ </blockquote>
+
+ <p>
+ The resource <i>Type</i> looks like it's supposed to be a use of the
+ "typed list idiom", but it isn't complete/accurate.
+ </p>
+
+ <h2><a name="inside-configuration">inside the Eyeball configuration file</a></h2>
+
+ <h3><a name="load-config-files" id="load-config-files"></a>configuration files</h3>
+
+ The Eyeball
+ command-line utility is configured by files (or URLs) specified
+ on the command line: their RDF contents are unioned together into
+ a single config model. If no config file is specified, then
+ <i>etc/eyeball-config.n3</i> is loaded.
+
+ <p>
+ The configuration file is a Jena assembler description
+ (see <a href="http://jena.sourceforge.net/assembler/index.html">
+ http://jena.sourceforge.net/assembler/index.html</a>)
+ with added Eyeball vocabulary.
+ </p>
+
+ <p>Eyeball is also configured by the location-mapping file
+ <i>etc/location-mapping.n3</i>. The Eyeball jar contains copies
+ of both the default config and the location mapper; these are
+ used by default. You can provide your own
+ <i>etc/eyeball-config.n3</i> file earlier on your classpath or in
+ your current directory; this config replaces the default. You may
+ provide <i>additional</i> location-mapping files earlier on your
+ classpath or in your current directory.</p>
+
+ <h3>configuring schema names</h3>
+
+ To avoid having to quote schema
+ names in full on the Eyeball command line, (collections of)
+ schemas can be given short names.
+
+ <pre>
+[] eye:shortName <i>shortNameLiteral</i>
+ ; eye:schema <i>fullSchemaURL</i>
+ ...
+ .
+</pre>
+
+ <p>
+ A shortname can name several schemas. The Eyeball
+ delivery has the short names <i>rdf</i>, <i>rdfs</i>, <i>owl</i>,
+ and <i>dc</i> for the corresponding schemas (and mirror versions
+ of those schemas so that they don't need to be downloaded each
+ time Eyeball is run.)
+ </p>
+
+ <h3><a name="inspectors-configuration">configuring inspectors</a></h3>
+
+ <p>
+ The inspectors that Eyeball runs
+ over the model are specfied by <i>eye:inspector</i> properties of
+ inspector resources. These resources are identified by
+ <code>eye:shortName</code>s (supplied on the command line). Each
+ such property value must be a plain string literal whose value is
+ the full name of the Inspector class to load and run; see the
+ Javadoc of Inspector for details.
+ </p>
+
+ <p>An inspector resource may refer to other inspector resources
+ to include their inspectors, using either of the two properties
+ <code>eye:include</code> or <code>eye:includeByName</code>. The
+ value of an <code>include</code> property should be another
+ inspector resource; the value of an <code>includeByName</code>
+ property should be the <code>shortName</code> of an inspector
+ resource.</p>
+
+ <h3><a name="uri-configuration">configuring the URI inspector</a></h3>
+
+ <p>As well as applying the standard URI rules, Eyeball allows
+ extra pattern-oriented checks to be applied to URIs. These are
+ specified by <code>eye:check</code> properties of the
+ <code>URIInspector</code> object in the configuration.</p>
+
+ <p>The object of an <code>eye:check</code> property is a bnode
+ with <code>eye:prefix</code>, <code>eye:prohibit</code>, and
+ <code>eye:require</code> properties. The objects of these
+ properties must be string literals.</p>
+
+ <p>If a URI <i>U</i> can be split into a prefix <i>P</i> and
+ suffix <i>S</i>, and there is a <i>check</i> property with that
+ prefix, and either:</p>
+
+ <ul>
+ <li>there's a <i>prohibit</i> property and <i>S</i> matches the
+ object of that property, or</li>
+
+ <li>there's a <i>require</i> property and <i>S</i> does not
+ match the object of that property,</li>
+ </ul>
+
+ <p>then a problem is reported. If there are multiple
+ <code>prohibit</code>s, then a problem is reported if <i>any</i>
+ prohibition is violated; if there are multiple
+ <code>require</code>s, a problem is reported if <i>none</i> of
+ them succeed.
+ </p>
+
+ <pre>
+eye:URIInspector eye:check
+ [eye:prefix "urn:x-hp:"; eye:prohibit ".*:.*"]
+ ; [eye:prefix "http://example.com/"; eye:require ".*eyeball.*"]
+</pre>The prefixes, requires, and prohibits are treated as Java
+patterns.
+
+ <p>
+ The URI inspector can be configured to report URIs with an
+ empty local name. These arise because the meaning of "local
+ name" comes from XML, and in XML a local name must start with
+ an NCName character, typically a letter but not a digit. Hence
+ URIs like <code>http://example.com/productCode#1829</code>
+ have an empty local name. This is sometimes confusing.
+ </p>
+
+ <p>
+ To report empty local names, add the property
+ <code>eye:reportEmptyLocalNames</code> to the inspector
+ <code>eye:URIInspector</code> with the property value
+ <code>true</code>. You may edit the configuration file
+ or use the <code>-set</code> command-line option.
+ </p>
+
+ <h3><a name="configure-vocabulary">configuring the vocabulary inspector</a></h3>
+
+ <p>The vocabulary inspector defaults to assuming that schema
+ namespaces are closed. To disable this for specified namespaces,
+ the inspector object in the configuration can be given
+ <code>eye:openNamespace</code> properties.</p>
+
+ <p>The object of each of these properties must be a resource; the
+ URI of this resource is an open namespace for which the inspector
+ will not report problems.</p>
+ <pre>
+eye:VocabularyInspector eye:openNamespace <http://example.com/examples#>
+</pre>
+
+ <h3><a name="SPARQL-driven">configuring the SPARQL-driven inspector</a></h3>
+
+ <p>The SPARQL inspector object in the configuration may be given
+ <code>eye:sparql</code> properties whose objects are resources
+ specifying SPARQL queries and problem messages.
+ </p>
+
+ <pre>
+eye:SparqlDrivenInspector eye:sparql [...]
+</pre>
+
+ <p>The resource may specify a SPARQL query which must succeed in
+ the model, and a message to produce if it does not.
+ </p>
+ <pre>
+eye:SparqlDrivenInspector eye:sparql
+ [eye:require "select * where {?s ?p ?o}"; eye:message "must be non-empty"]
+</pre>
+
+ <p>If the query is non-trivial, the string may contain a
+ reference to a file containing the query, rather than the entire
+ query.
+ </p>
+
+ <pre>
+eye:require "@'/home/kers/example/query-one.sparql'"
+</pre>
+
+ <p>The quoted filename is read using the Jena file manager and
+ so respects any filename mappings. "@" characters not followed
+ by "'" are not subject to substitution, except that the
+ sequence "@@" is replaced by "@".
+ </p>
+
+ <p>Using
+ <code>eye:prohibit</code> rather than <code>eye:require</code>
+ means that the problem is reported if the query succeeds, rather
+ than if it fails.
+ </p>
+
+ <h3>configuring renderers</h3>
+
+ <p>
+ The renderer class that Eyeball
+ uses to render the report into text is giving in the config file
+ by triples of the form:
+ </p>
+
+ <pre>
+[]
+ eye:renderer FullClassName
+ ; eye:shortName ShortClassHandler
+</pre>
+
+ <p>
+ The <code>FullClassName</code> is a string literal giving the
+ full class name of the rendering class. That class must implement
+ the <i>Renderer</i> interface and have a constructor that takes a
+ <code>Resource</code>, its configuration root, as its argument.
+ </p>
+
+ <p>The <code>ShortClassHandle</code> is a string literal giving
+ the short name used to refer to the class. The default short name
+ used is <b>default</b>. There should be no more than one
+ <i>eye:shortName</i> statement with the same ShortClassHandle in
+ the configuation file, but the same class can have many different
+ short names.</p>
+
+ <p>The <code>TextRenderer</code> supports an additional property
+ <code>eye:labels</code> to allow the appropriate labels for an
+ ontology to be supplied to the renderer. Each object of a
+ <code>eye:labels</code> statement names a model; all the
+ <code>rdfs:label</code> statements in that model are used to
+ supply strings which are used to render resources.</p>
+
+ <p>The model names are strings which are interpreted by Jena's
+ <code>FileManager</code>, so they may be redirected using Jena's
+ file mappings.</p>
+
+ <h2>inside the Eyeball code</h2>
+
+ <p>Eyeball can be used from within Java code; the command line
+ merely provides a convenient external interface.</p>
+
+ <h3>creating an Eyeball</h3>
+
+ <p>An Eyeball object has three subcomponents: the assumptions
+ against which the model is to be checked, the inspectors which do
+ the checking, and the renderer used to display the reports.</p>
+
+ <p>The assumptions are bundled into a single OntModel. Multiple
+ assumptions can be supplied either by adding them as sub-models
+ or by loading their content directly into the OntModel.</p>
+
+ <p>The inspectors are supplied as a single Inspector object. The
+ method <code>Inspector.Operations.create(List)</code> creates a
+ single Inspector from a list of Inspectors; this inspector
+ delegates all its inspection methods to all of its
+ sub-inspectors.</p>
+
+ <p>The renderer can be anything that implements the (simple)
+ renderer interface.</p>
+
+ <p>To create an Eyeball:</p>
+
+ <pre>Eyeball eyeball = new Eyeball( inspector, assumptions, renderer );
+</pre>
+
+ <h3>to eyeball a model</h3>
+
+ <p>Models to be inspected are provided as OntModels. The problems
+ are delivered to a Report object, where they are represented as
+ an RDF model.</p>
+
+ <blockquote>
+ eyeball.inspect( report, ontModelToBeInspected )
+ </blockquote>
+
+ <p>The result is that same report object. The
+ <i>Report::model()</i> method delivers an RDF model which
+ describes the problems found by the inspection. The inspections
+ supplied in the distribution use the EYE vocabulary, and are used
+ in the standard reports:
+ </p>
+
+ <p>Every report item in the model is a blank node with
+ <code>rdf:type eye:Item</code>. See earlier sections for
+ the descriptions of the properties attached to an Item.
+ </p>
+
+ <h2>rebuilding Eyeball</h2>
+
+ <p>
+ The provided ant script can be used to rebuild Eyeball from
+ source:
+ </p>
+
+ <pre>
+ant clean build jar
+</pre>
+
+ <p>(Omitting <code>clean</code> will do an incremental build, useful
+ for small changes.)
+ </p>
+
+ <p>
+ The libraries required by Eyeball are all in the <code>lib</code>
+ directory, including the necessary Jena jars.
+ </p>
+
+ <h2>creating and configuring an inspector</h2>
+
+ <p>
+ To make a new inspector available to Eyeball, a new Inspector
+ class must be created and that class has to be described in
+ the Eyeball configuration.
+ </p>
+
+ <h3>creating an Inspector</h3>
+
+ <p>
+ Any inspector must implement the Inspector interface,
+ which has four operations:
+ </p>
+
+ <ul>
+ <li><i>begin( Report r, OntModel assume )</i>:
+ Begin a new inspection. <code>r</code> is the <code>Report</code>
+ object which will accept the reports in this inpsection;
+ <code>assume</code> is the model containing the assumed
+ ontologies. <code>begin</code> is responsible for declaring
+ this inspectors <i>report properties</i>.
+ </li>
+ <li><i>inspectModel( Report r, OntModel m )</i>:
+ Do a whole-model inspection of <code>m</code>, issuing
+ reports to <code>r</code>.
+ </li>
+ <li><i>inspectStatement( Report r, Statement s )</i>:
+ Inspect the single statement <code>s</code>, issuing
+ reports to <code>r</code>.
+ </li>
+ <li><i>end( Report r )</i>:
+ Do any tidying-up reports required.
+ </li>
+ </ul>
+
+ <p>
+ Typically <code>end</code> and one of <code>inspectModel</code> or
+ <code>inspectStatement</code> do nothing.
+ </p>
+
+ <p>
+ An inspector must also have a constructor that takes a <code>Resource</code>
+ argument. When Eyeball creates the Inspector object, it passes the
+ <code>Resource</code> which is the root of this inspector's
+ configuration. (This is, for example, how the SPARQL-driven inspector
+ receives the query strings to use.)
+ </p>
+
+ <p>
+ Developers may find the class <code>InpsectorBase</code> useful; it
+ has empty implementations for all the <code>Inspector</code> methods.
+ They may also find <code>InspectorTestBase</code> useful when writing
+ their inspector's tests, both for its convenience methods and because
+ it requires that their class has the appropriate constructors.
+ </p>
+
+ <h3>reports and report properties</h3>
+
+ <p>
+ Eyeball reports are statements in a report model. To let the
+ renderer know which property of a report is the "main" one,
+ and which order the other properties should appear in, the
+ inspector's <code>begin</code> method should declare the
+ properties:
+ </p>
+
+ <pre>
+r.declareProperty( EYE.badDatatypeURI );
+r.declareOrder( EYE.badLanguage, EYE.onLiteral );
+</pre>
+
+ <p>
+ <code>declareProperty(P)</code> announces that <code>P</code>
+ is a report property of this inspector. <code>declareOrder(F,S)</code>
+ says that both <code>F</code> and <code>S</code> are report properties,
+ and that <code>F</code> should appear before <code>S</code> in the
+ rendered report.
+ </p>
+
+ <p>
+ Reports are made up of <i>report items</i>, which are the subjects
+ of the report properties. To create a report item, use one of
+ <code>reportItem()</code> or <code>reportItem(S)</code>. The
+ second form is appropriate when the report is attached to some
+ statement <code>S</code> of the model being inspected; a report
+ renderer will attempt to display <code>S</code>.
+ </p>
+
+ <p>
+ To add the main property to a report item <code>R</code>, use
+ <code>R.addMainProperty(P,O)</code>; to add non-main properties,
+ use <code>R.addProperty(P,O)</code>.
+ </p>
+
+ <h3>configuring an inspector</h3>
+
+ <p>
+ To add an inspector to a configuration file, choose a URI for
+ it (here we're using <code>my:Fresh</code> and assuming
+ a prefix declaration for <code>my:</code>) and a short name
+ (here, "fresh") and add a description to the configuration file:
+ </p>
+
+ <pre>
+my:Fresh a eye:Inspector
+ ; eye:shortName "fresh"
+ ; rdfs:label "fresh checks for my application"
+ ; eye:className "full.path.to.Fresh"
+ .
+</pre>
+
+ <p>
+ Replace <code>full.path.to.Fresh</code> with the full classname
+ of your inspector. Now you can use <code>Fresh</code> by adding
+ <i>-include fresh</i> to the Eyeball command line (and ensuring
+ that the class is on your classpath).
+ </p>
+
+ <p>
+ If you want <code>Fresh</code> to be included by default, then
+ you must add it as an <code>eye:inspector</code> property
+ of the configuration root, <i>eg</i>:
+ </p>
+
+ <pre>
+eye:eyeball a eye:Eyeball
+ ; eye:inspector
+ eye:PrefixInspector, # as delivered
+ <span style="background: white">my:FreshInspector</span>, # new inspector
+ eye:URIInspector, # as delivered
+ ...
+</pre>
+
+ <p>
+ </p>
+
+
+</body>
+</html>
Re: svn commit: r1398843 [1/2] - in /jena/Scratch/Eyeball/trunk/doc:
./ eyeball-1-doc/
Posted by Ian Dickinson <ia...@epimorphics.com>.
Hi Chris,
When I migrated our documentation to the Apache web site, I converted
the eyeball documentation to the online form to be consistent with the
other Jena documentation. I suggest that you update the online docs,
rather than the old version hidden away inside svn:
http://jena.apache.org/documentation/tools/eyeball-getting-started.html
Ian
On 16/10/12 16:20, chrisdollin@apache.org wrote:
> Author: chrisdollin
> Date: Tue Oct 16 15:20:36 2012
> New Revision: 1398843
>
> URL: http://svn.apache.org/viewvc?rev=1398843&view=rev
> Log:
> added version info to document names, started docs for E2.4.
>
> Added:
> jena/Scratch/Eyeball/trunk/doc/eyeball-2.3-brief.html
> - copied unchanged from r1398314, jena/Scratch/Eyeball/trunk/doc/brief.html
> jena/Scratch/Eyeball/trunk/doc/eyeball-2.3-full-template.html
> - copied unchanged from r1398314, jena/Scratch/Eyeball/trunk/doc/full-template.html
> jena/Scratch/Eyeball/trunk/doc/eyeball-2.3-full.html
> - copied unchanged from r1398314, jena/Scratch/Eyeball/trunk/doc/full.html
> jena/Scratch/Eyeball/trunk/doc/eyeball-2.3-index.html
> - copied unchanged from r1398314, jena/Scratch/Eyeball/trunk/doc/index.html
> jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-brief.html
> jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-full-template.html
> jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-full.html
> jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-index.html
> Removed:
> jena/Scratch/Eyeball/trunk/doc/brief.html
> jena/Scratch/Eyeball/trunk/doc/classpath.text
> jena/Scratch/Eyeball/trunk/doc/eyeball-1-doc/
> jena/Scratch/Eyeball/trunk/doc/full-template.html
> jena/Scratch/Eyeball/trunk/doc/full.html
> jena/Scratch/Eyeball/trunk/doc/index.html
> jena/Scratch/Eyeball/trunk/doc/old-full.html
>
> Added: jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-brief.html
> URL: http://svn.apache.org/viewvc/jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-brief.html?rev=1398843&view=auto
> ==============================================================================
> --- jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-brief.html (added)
> +++ jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-brief.html Tue Oct 16 15:20:36 2012
> @@ -0,0 +1,406 @@
> +<html>
> +<head>
> +<title>Eyeball 2.4</title>
> +<link type="text/css" rel="stylesheet" href="styles/doc.css">
> +</head>
> +<body>
> +
> +<h1>caveat</h1>
> +
> +This document is a work-in-progress; refer to the
> +<a href="full.html">manual</a> for details when this page
> +doesn't help.
> +
> +<h1>brief guide</h1>
> +
> +<p>
> +So you've got Eyeball installed and you've run it on one of your
> +files, and Eyeball doesn't like it. You're not sure why, or what
> +to do about it. Here's what's going on.
> +
> +<p>
> +Eyeball inspects your model against a set of <i>schemas</i>.
> +The default set of schemas includes RDF, RDFS, the XSD datatypes,
> +and any models your model imports: you can add additional schemas
> +from the command line or configuration file.
> +Eyeball uses those schemas to work out what URIs count as "declared"
> +in advance. It also checks URIs and literals for syntactic
> +correctness and name space prefixes for being "sensible".
> +Let's look at some of the messages you can get.
> +
> +<h2>unknown predicate reports</h2>
> +
> +<p>
> +You'll probably find several messages like this:
> +
> +<pre>
> +predicate not declared in any schema: <i>somePredicateURI</i>
> +</pre>
> +
> +Eyeball treats the imported models, and (independently) the
> +specified schemas, as single OntModels, and extracts those
> +OntModels' properties. It includes the RDF and RDFS schemas.
> +Anything used as a predicate that isn't one of those properties
> +is reported.
> +
> +<p>If you're using OWL, you can silence the "undeclared property"
> +messages about OWL properties by adding to your Eyeball command line
> +the option:
> +
> +<blockquote>
> +-assume owl
> +</blockquote>
> +
> +<p>
> +Eyeball will read the OWL schema (it has a copy stashed away in the
> +<i>mirror</i> directory) and add the declared properties to
> +its known list. This works for any filename or URL you like, so long as
> +there's RDF there and it has a suitable file suffix - <i>.n3</i> for
> +N3 or <i>.rdf</i> or <i>.owl</i> for RDF/XML - and for the built-in
> +names <i>dc</i> (basic Dublin Core), <i>dcterms</i> (Dublin Core terms)
> +and <i>dc-all</i> (both). So you
> +can construct your own schemas, which declare your own domain-specific
> +property declarations, and invoke Eyeball with
> +
> +<blockquote>
> +-assume owl <i>mySchemaFile.n3</i> <i>otherSchemaFile.rdf</i>
> +</blockquote>
> +
> +<p>
> +You can give short names (like <b>dc</b> and <b>rdfs</b>) to
> +your own schemas, or collections of schemas, using an Eyeball
> +<i>config file</i>, but you'll have to see the
> +<a href="full.html">manual</a> to find out how.
> +
> +<h2>unknown class reports</h2>
> +
> +<p>
> +You may see messages like this:
> +
> +<pre>
> +class not declared in any schema: <i>someClassURI</i>
> +</pre>
> +
> +<p>
> +Having read the previous section, you can probably work out
> +what's going on: Eyeball reads the schemas (and imports)
> +and extracts the declared OntClasses. Then anything used
> +as a class that isn't one of those declared classes is
> +reported..
> +
> +<p>
> +And that's exactly it. "Used as a class" means appearing
> +as <b>C</b> or <b>D</b> in any statement of the form:
> +
> +<ul>
> +<li>_ rdf:type C
> +<li>_ rdfs:domain C
> +<li>_ rdfs:range C
> +<li>C rdfs:subClassOf D
> +</ul>
> +
> +<h2>suppressing inspectors</h2>
> +
> +<p>
> +It may be that you're not interested in the "unknown predicate"
> +or "unknown class" reports until you've sorted out the URIs.
> +Or maybe you don't care about them. In that case, you can
> +switch them off.
> +
> +<p>
> +Eyeball's different checks are carried out by <i>inspector</i>
> +classes. These classes are given short names by entries in
> +Eyeball config files (which are RDF files written using N3; you
> +can see the default config file by looking in Eyeball's
> +<code>etc</code> directory for <code>eyeball2-config.n3</code>).
> +By adding eg:
> +
> +<blockquote>
> +-exclude property class
> +</blockquote>
> +
> +<p>to the Eyeball command line, you can <i>exclude</i> the inspectors
> +with those short names from the check. <i>property</i> is the
> +short name for the "unknown property" inspector, and
> +<i>class</i> is the short name for the "unknown class"
> +inspector.
> +
> +<h2>namespace and URI reports</h2>
> +
> +Eyeball checks all the URIs in the model, including (if available)
> +those used for namespaces. (And literals, but see below.) Here's
> +an example:
> +
> +<pre>
> +bad namespace URI: "file:some-filename"
> + on prefix: "pqr"
> + for reason: file URI inappropriate for namespace
> +</pre>
> +
> +A "bad namespace URI" means that Eyeball doesn't like the URI
> +for a namespace in the model. The "on prefix" part of the
> +report says what the namespace prefix is, and the "for reason"
> +part gives the reason. In this case, we (the designer of Eyeball)
> +feel that it is unwise to use file URIs - which tend to depend
> +on internal details of your directory structure - for global
> +concepts.
> +
> +<p>A more usual reason is that the URI is syntactically illegal.
> +Here are some possibilities:
> +
> +<table border>
> +
> +<tr>
> + <td>URI contains spaces
> + <td>literal spaces are not legal in URIs. This usually arises from
> + file URIs when the file has a space in its name. Spaces in URIs
> + have to be encoded.
> +
> +<tr>
> + <td>URI has no scheme
> + <td>The URI has no scheme at all. This usually happens when some relative
> + URI hasn't been resolved properly, eg there's no xml base in an
> + RDF/XML document.
> +
> +<tr>
> + <td>URI has an unrecognised scheme
> + <td>The scheme part of the URI - the bit before the first colon - isn't
> + recognised. Eyeball knows, by default, four schemes:
> + <b>http</b>, <b>ftp</b>, <b>file</b>, and <b>urn</b>. This
> + usually arises when a QName has "escaped" from somewhere, or from
> + a typo.
> +
> + <p>You can tell Eyeball about other schemes, if you need them.
> +
> +<tr>
> + <td>scheme should be lower-case
> + <td>The scheme part of the URI contains uppercase letters. While this
> + is not actually <i>wrong</i>, it is unconventional and pointless.
> +
> +<tr>
> + <td>URI doesn't fit pattern
> + <td>Eyeball has some (weak) checks on the syntax of URIs in different
> + schemes, expressed as patterns in its config files. If a URI doesn't
> + match the pattern, Eyeball reports this problem. At the moment,
> + you'll only get this report for a <b>urn</b> URI like
> + <i>urn:x-hp:23487682347</i> where the URN id (the bit between the
> + first and second colons, here <i>x-hp</i>) is illegal.
> +
> +<tr>
> + <td>URI syntax error
> + <td>A catch-all error: Java couldn't make any sense of this URI at all.
> +
> +</table>
> +
> +<h2>problems with literals</h2>
> +
> +<p>Eyeball checks literals (using the <i>literal inspector</i>,
> +whose short name is <b>literal</b> if you want to switch it off),
> +but the checking is quite weak because it doesn't understand
> +types at the moment. You can get two different classes of error.
> +
> +<pre>
> +bad language: someLanguageCode
> +on literal: theLiteralInQuestion
> +</pre>
> +
> +<p>Literals with language codes (things like <b>en-UK</b> or
> +<b>de</b>) are checked to make sure that the language code
> +conforms to the general syntax for language codes: alphanumeric
> +words separated by hyphens, with the first containing no digits.
> +
> +<p>(Later versions of Eyeball will likely allow you to specify
> +<i>which</i> language codes you want to permit in your models.
> +But we haven't got there yet.)
> +
> +<pre>
> +bad datatype URI: someURI
> +on literal: theLiteralInQuestion
> +for reason: theReason
> +</pre>
> +
> +<p>Similarly, literals with datatypes are checked to make sure
> +that the type URI is legal. That's it for the moment: Eyeball
> +doesn't try to find out if the URI really is a type URI, or
> +if the spelling of the literal is OK for that type. But it
> +spots the bad URIs. (The messages are the same as those that
> +appear in the URI checking - above - for the very good reason
> +that it's the same code doing the checking.)
> +
> +<h2>problematic prefixes</h2>
> +
> +<p>
> +Both RDF/XML and N3 allow (and RDF/XML requires) namespaces to
> +be abbreviated by prefixes. Eyeball checks prefixes for two
> +possible problems. The first:
> +
> +<pre>
> +non-standard namespace for prefix
> +</pre>
> +
> +<p>
> +This arises when a "standard" prefix has been bound to a namespace
> +URI which isn't its usual one. The "standard" prefixes are taken from
> +Jena's <code>PrefixMapping.Extended</code> and are currently:
> +
> +<blockquote>
> +<b>rdf, rdfs, daml, owl, xsd, rss, vcard</b>
> +</blockquote>
> +
> +<p>And the second:
> +
> +<pre>
> +Jena generated prefix found
> +</pre>
> +
> +<p>
> +This arises when the model contains prefixes of the form <code>j.N</code>,
> +where N is a number. These are generated by Jena when writing RDF/XML
> +for URIs that must have a prefix (because they are used as types or
> +predicates) but haven't been given one.
> +
> +<p>
> +If you're not bothered about inventing short prefixes for your
> +namespaces, you can <b>-exclude</b> <code>jena-prefix</code>
> +to suppress this inspection.
> +
> +<h1>but how do I ...</h1>
> +
> +<p>The reports described so far are part of Eyeball's default
> +set of inspections. There are some other checks that it can do
> +that are switched off by default, because they are expensive,
> +initially overwhelming, or downright obscure. If you need
> +to add these checks to your eyeballing, this is how to do it.
> +</p>
> +
> +<h2>... make sure everything is typed?</h2>
> +
> +<p>
> +Some applications (or a general notion of cleanliness) require
> +that every individual in an RDF model has an explicit
> +<code>rdf:type</code>. The Eyeball check for this isn't
> +enabled by default, because lots of casual RDF use doesn't
> +need it, and more sophisticated use has models with enough
> +inference power to infer types.
> +
> +<p>
> +You can add the <b>all-typed</b> inspector to the inspectors
> +that Eyeball will run by adding to the command line:
> +
> +<blockquote>
> +-inspectors defaultInspectors all-typed
> +</blockquote>
> +
> +<p>The <b>all-typed</b> inspector will generate a message
> +
> +<pre>
> +resource has no rdf:type
> +</pre>
> +
> +<p>for each resource in the model which is not the subject of
> +an <code>rdf:type</code> statement.
> +
> +<h2>... check for type consistency?</h2>
> +
> +<p>
> +One easy mistake to make in RDF is to make an assertion - we'll
> +call it <b>S P O</b> - about some subject <b>S</b> which is
> +"of the wrong type", that is, not of whatever type <b>P</b>'s
> +domain is. This isn't, in principle, an error, since RDF resources
> +can have multiple types, and this just makes <b>S</b> have a type
> +which is a subtype of both <b>P</b>'s domain and whatever type
> +it was supposed to have.
> +
> +<p>To spot this, and related problems, Eyeball has the
> +<b>consistent-type</b> inspector. You can add it to the
> +inspections in the same way as the <b>all-typed</b>
> +inspector:
> +
> +<blockquote>
> +-inspectors defaultInspectors consistent-type
> +</blockquote>
> +
> +<p>
> +It checks that every resource which has been given at least
> +one type has a type which is a subtype of all its types,
> +under an additional assumption:
> +
> +<blockquote>
> +Types in the type graph (the network of rdfs:subClassOf statements)
> +are disjoint (share no instances) unless the type graph says they're
> +not.
> +</blockquote>
> +
> +<p>For example, suppose that both <b>A</b> and <b>B</b> are
> +subclasses of <b>Top</b>, ande that there are no other subclass
> +relationships. Then <b>consistent-types</b> assumes that there
> +are (supposed to be) no resources which have both <b>A</b> and
> +<b>B</b> as types. If it finds a resource <b>X</b> which <i>does</i>
> +have both types, it generates a message like this:
> +
> +<pre>
> +no consistent type for: X
> +has associated type: A
> +has associated type: B
> +has associated type: Top
> +</pre>
> +
> +<p>
> +It's up to you to disentangle the types and work out what went
> +wrong.
> +
> +<p>
> +<i>Note</i>: this test requires that Eyeball do a significant amount
> +of inference, to complete the type hierarchy and check the
> +domains and ranges of proeprties. It's quite slow, which is
> +one reason it isn't switched on by default.
> +
> +<h2>... check the right number of values for a property?</h2>
> +
> +<p>You want to make sure that your data has the right properties
> +for things of a certain type: say, that a book has at least one
> +author (or editor), an album has at least one track, nobody in
> +your organisation has more than ten managers, a Jena contrib
> +has at least a <code>dc:creator</code>, a <code>dc:name</code>,
> +and a <code>dc:description</code>. You write some OWL
> +<i>cardinality constraints</i>:
> +
> +<blockquote>
> +my:Type rdfs:subClassOf [owl:onProperty my:track; owl:minCardinality 1]
> +</blockquote>
> +
> +Then you discover that, for wildly technical reasons, the OWL
> +validation code in Jena doesn't think it's an error for some
> +album to have no tracks (maybe there's a namespace error).
> +</p>
> +
> +<p>You can enable Eyeball's <i>cardinality inspector</i> by
> +adding
> +
> +<blockquote>
> +-inspectors cardinality
> +</blockquote>
> +
> +to the command line. You'll now get a report item for every resource
> +that has <code>rdf:type</code> your restricted type (<code>my:Type</code>
> +above) but doesn't have the right (at least one) value for the property.
> +It will look something like:
> +
> +<pre>
> +cardinality failure for: my:Instance
> + on type: my:Type
> + on property: my:track
> + cardinality range: [min: 1]
> + number of values: 0
> + values: {}
> +</pre>
> +
> +If there are some values for the property - say you've supplied
> +an <code>owl:maxCardinality</code> restriction and then gone
> +over the top - they get listed inside the <code>values</code>
> +curly braces.
> +</p>
> +
> +
> +</body>
> +</html>
>
> Added: jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-full-template.html
> URL: http://svn.apache.org/viewvc/jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-full-template.html?rev=1398843&view=auto
> ==============================================================================
> --- jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-full-template.html (added)
> +++ jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-full-template.html Tue Oct 16 15:20:36 2012
> @@ -0,0 +1,1397 @@
> +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
> +<html>
> +<head>
> + <title>Eyeball 2.4</title>
> + <link type="text/css" rel="stylesheet" href="styles/doc.css" />
> + <script>
> + function invert( id )
> + {
> + x = document.getElementById( id )
> + x.className = x.className == "hide" ? "show" : "hide"
> + }
> + </script>
> +</head>
> +<body>
> + <h1>summary</h1>
> +
> + <p>This document describes Eyeball 2.4, an
> + "<a href="http://www.w3.org/RDF/">RDF</a>
> + <a href="http://en.wikipedia.org/wiki/Lint_programming_tool">lint</a>";
> + see the
> + <a href="ReleaseNotes.text">release notes</a> for descriptions
> + of changes from previous versions.
> + Eyeball is part of the Jena family of RDF/OWL tools: see
> + <a href="http://jena.sourceforge.net">jena.sourceforge.net</a>
> + for the Jena documentation and downloads. Support for the
> + Jena family is provided on the mailing lists
> + <i>jena-dev@yahoogroups.com</i> (for developers using Jena)
> + and <i>jena-devel@lists.sourceforge.net</i> (for developers
> + modifying or extending Jena). Note that, ny support is provided
> + on a voluntary basis, as and when the effort is available.
> + </p>
> +
> + <p>
> + Throughout this document, the prefix <i>eye</i> stands for the
> + URL <i>http://jena.hpl.hp.com/Eyeball#</i>.
> + </p>
> +
> + <h1 onClick="invert('TOC')">table of contents [click to reveal]</h1>
> +
> + <div id="TOC" class="hide">
> + <div class="toc">
> + </div>
> + </div>
> +
> + <h1>Eyeball - checking RDF for common problems</h1>
> +
> + <p>Eyeball is a
> + library and command-line tool for checking RDF and OWL models for
> + various common problems. These problems often result in
> + technically correct but implausible RDF. Eyeball checks against
> + user-provided schema files and makes various closed-world
> + assumptions.
> + </p>
> +
> + <p>Eyeball 2.4 can check for:</p>
> +
> + <ul>
> + <li>unknown [with respect to the schemas] properties and classes</li>
> + <li>bad prefix namespaces</li>
> + <li>ill-formed URIs, with user-specifiable constraints</li>
> + <li>ill-formed language tags on literals</li>
> + <li>datatyped literals with illegal lexical forms</li>
> + <li>unexpected local names in schema namespaces</li>
> + <li>untyped resources and literals</li>
> + <li>individuals having consistent types, assuming complete typing</li>
> + <li>likely cardinality violations</li>
> + <li>broken RDF list structures</li>
> + <li>suspected broken use of the typed list idiom</li>
> + <li>obviously broken OWL restrictions</li>
> + <li>user-specified constraints written in SPARQL</li>
> + </ul>
> +
> + <p>Eyeball's checks are performed by Inspector plug-ins and can
> + be customised by the user. Rendering its reports to output is
> + performed by Renderer plug-ins which can also be customised by
> + the user.</p>
> +
> + <h2>installation</h2>
> +
> + <p>Fetch the Eyeball distribution zipfile and unpack it somewhere
> + convenient. Read the documention in the <i>doc</i> directory: the
> + one-minute guide <i>index.html</i>, the brief introduction
> + <i>brief.html</i>, and when necessary the manual <i>full.html</i>
> + (that's what this is).</p>
> +
> + <p>Eyeball 2.4 comes with its own copy of Jena 2.5 with CVS
> + updates. Do <i>not</i> attempt to use other versions of Jena with
> + Eyeball.</p>
> +
> + <p>In the Eyeball distribution directory, run the Eyeball
> + tests:
> + </p>
> +
> + <blockquote>
> + ant test
> + </blockquote>
> +
> + <p>
> + If these tests fail, something is wrong.
> +
> + (The message <i>(Note:
> + statistician test disabled; don't worry about this.)</i> is not a
> + failure.)
> +
> + Sometimes
> + it's no more than a classpath problem, which you can fix. If not,
> + use the <i>jena-dev</i> mailing list to request assistance. Note that,
> + just as with Jena itself, any support is provided on a voluntary
> + basis, as and when the effort is available.
> + </p>
> +
> + <p>
> + If the tests have passed, you can use Eyeball from the installation
> + directory, or copy <i>lib</i>, <i>etc</i> and <i>mirror</i> to
> + somewhere convenient.
> + </p>
> +
> + <h2>command line operation</h2>
> +
> + <p>
> + You must ensure that <i>all</i> the Eyeball jars from <i>lib</i>
> + are on your classpath. (Note that Eyeball comes with its own Jena
> + jar files and <i>may not work</i> with other Jena jars.) The
> + directories <i>etc</i> and <i>mirror</i> should be in the
> + current directory or also on your classpath.
> + </p>
> +
> + <p>Run the Eyeball command:</p>
> +
> + <pre>
> +java [java options eg classpath and proxy] jena.eyeball
> + (-check | -sign | -accept) specialURL+
> + [-assume Reference*]
> + [-config fileOrURL*]
> + [-set Setting*]
> + [-root rootURI]
> + [-render Name]
> + [-include shortName*]
> + [-exclude shortName*]
> + [-analyse | -repair]
> + [-remark] [-version]
> +</pre>
> +
> + <p>
> + The -<i>whatever</i> sections can come in any order
> + and may be repeated, in which case the additonal arguments are appended
> + to the existing ones. Exactly one of <i>-check</i>, <i>-sign</i>,
> + <i>-accept</i>, or <i>version</i> must be provided; all the other
> + options are optional.
> + </p>
> +
> + <p>
> + When Eyeball resolves ordinary filenames or URLs it uses the
> + Jena file manager to possibly map those names (<i>eg</i> to
> + redirect an <code>http:</code> URL to a local cached copy).
> + See the
> + <a href="http://jena.sourceforge.net/how-to/filemanager.html">
> + file manager howto</a> for details on how to configure the
> + file manager.
> + </p>
> +
> + <h3>examples of command-line use</h3>
> +
> + <pre>
> +java jena.eyeball -version
> +
> +java jena.eyeball -check myDataFile.rdf
> +
> +java jena.eyeball -assume dc -check http://example.com/nosuch.n3
> +
> +java jena.eyeball -assume mySchema.rdf -check myData.rdf -render xml
> +
> +java jena.eyeball -check myData.rdf -include consistent-type
> +
> +java jena.eyeball -check myConfig.ttl -sign >signedConfig.ttl
> +</pre>
> +
> + <h3>-check specialURL+</h3>
> +
> + <p>The <i>-check</i> command checks the specified models for
> + problems. The <i>specialURL</i>s designate the models to be
> + checked. In the simplest case, these are plain filenames,
> + <code>file:</code> URLs, or <code>http:</code> URLs. At least one
> + <i>specialURL</i> must be specified. Each specified model is
> + checked independently of the others.</p>
> +
> + <pre>
> +-check myModel.ttl
> +-check file:///c:/rdf/pizza.owl
> +-check http://example.com/rdf/beer.rdf
> +</pre>
> +
> + <p>If the <i>specialURL</i> is of the form <i>ont:NAME:base</i>,
> + then the checked model is the model <i>base</i> treated as an
> + OntModel with the specification
> + <code>OntModelSpec.<i>NAME</i></code>; see <a href=
> + "http://jena.sourceforge.net/ontology/index.html#creatingModels">the
> + Jena ontology documentation</a> for the available names.</p>
> + <pre>
> +-check ont:OWL_MEM_RDFS_INF:myModel.ttl
> +-check ont:OWL_DL_MEM_RULE_INF:http://example.com/rdf/beer.rdf
> +</pre>
> +
> + <p>If the <i>specialURL</i> is of the form <i>ja:R@AF</i>, then
> + the model is that described by the resource <i>R</i> in the Jena
> + <a href=
> + "http://jena.sourceforge.net/assembler/index.html">assembler</a>
> + description file <i>AF</i>. <i>R</i> is prefix-expanded using the
> + prefixes in <i>AF</i>.</p>
> + <pre>
> +-check ja:my:root@my-assembly.ttl
> +-check ont:OWL_MEM_RDFS_INF:my:root@my-assembly.ttl
> +</pre>
> +
> + <p>If the URL (or the base) is of the form
> + <i>jdbc:DB:head:model</i>, then the checked model is the one
> + called <i>model</i> in the database with connection
> + <i>jdbc:DB:head</i>. (The database user and password must be
> + specified independently using the <i>jena.db.user</i> and
> + <i>jena.db.password</i> system properties.)</p>
> + <pre>
> +-check jdbc:mysql://localhost/test:example
> +</pre>
> +
> + <h3>-config fileOrURL and -root rootURI</h3>
> +
> + <p>The <i>-config fileOrURL</i> options specify the Eyeball
> + <a href=
> + "http://jena.sourceforge.net/assembler/index.html">assembler</a>
> + configuration files to load. A single configuration model is
> + constructed as the union of the contents of those files. If this
> + option is omitted, the default configuration file
> + <i>etc/eyeball-config.n3</i> is loaded. See <a href=
> + "#inside-configuration">inside the Eyeball configuration file</a>
> + for details of the configuration file.</p>
> + <pre>
> +-config my-hacked-config-file.n3
> +-config etc/eyeball-config.n3 extras.ttl
> +</pre>
> +
> + <p>The <i>-root rootURI</i> option specifies the root resource in
> + the Eyeball configuration. If this option is omitted,
> + <i>eye:eyeball</i> is used by default. <i>rootURI</i> is
> + prefix-expanded using the prefixes in the configuration file.</p>
> + <pre>
> +-root my:root
> +-root my:sparse-config
> +-root urn:x-hp:eyeball-roots:special
> +</pre>
> +
> + <h3>-set Setting*</h3>
> +
> + <p>
> + The <i>-set</i> option allows command-line tweaks to the
> + configuration, <i>eg</i> for enabling checking URIs for
> + empty local names. <i>You will rarely need to use this</i>;
> + it is presented here because of its association with
> + the <code>-config</code> and <code>-root</code> options.
> + </p>
> +
> + <p>
> + Each <i>Setting</i> has the form <code>S.P=O</code> and adds
> + the statement <code>(S' P' O')</code> to the configuration.
> + </p>
> +
> + <p>
> + The current Eyeball converts the components of the
> + <code>S.P=O</code> string into RDF nodes <code>S'</code>,
> + <code>P'</code>, <code>O'</code> using some special rules:
> + </p>
> +
> + <ul>
> + <li>
> + A component starting with a digit is treated as an
> + xsd:integer literal (and hence should only appear as
> + the object of the setting).
> + </li>
> +
> + <li>
> + A component starting with a quote, either <code>"</code>
> + or <code>'</code>, is treated as a literal whose lexical
> + form extends to the matching closing quote. Note:
> + (a) <i>literals with embedded spaces are not supported</i>;
> + (b) your command-line interpreter may treat quotes
> + specially, and to allow the quotes to pass through to
> + Eyeball, you'll have to use another (different) pair of
> + quotes!
> + </li>
> +
> + <li>
> + A component starting with <code>_</code> is treated
> + as a blank node with that label.
> + </li>
> +
> + <li>
> + Otherwise, the component is treated as a URI reference.
> + If it starts with a prefix (<i>eg</i>, <code>rdf:</code>)
> + that prefix is expanded using the prefixes of the configuration
> + file. If it has no prefix, it is as though the empty prefix
> + was specified: in the default configuration file, that is
> + set to the Eyeball namespace, so it is as though the prefix
> + <code>eye:</code> had been used.
> + </li>
> + </ul>
> +
> + <p>
> + For example, to enable the URI inspectors non-default reporting
> + of URIs with empty local names, use:
> + </p>
> +
> + <pre>
> +-set URIInspector.reportEmptyLocalNames="'true'"
> +</pre>
> +
> + <p>
> + Note the nested different quotes required to pass 'true'
> + to Eyeball so that it can interpret this as a literal.
> + </p>
> +
> + <h3>-include/-exclude shortNames</h3>
> +
> + <p>
> + The various Eyeball inspectors are given <i>short names</i> in
> + the configuration file. By default, an Eyeball check uses a
> + specific set of inspectors with short name
> + <i>defaultInspectors</i>. Additional inspectors can be enabled
> + using the <i>-include</i> option, and default inspectors can be
> + disabled using the <i>-exclude</i> option. See below for the
> + available inspectors and their short names, and see <a href=
> + "#inspectors-configuration">inspectors configuration</a> for
> + how to configure inspectors.
> + </p>
> +
> + <pre>
> +-include list all-typed
> +-exclude cardinality
> +-include owl -exclude consistent-type
> +</pre>
> +
> + <h3>-assume Reference</h3>
> +
> + <p>The -assume <i>Reference</i>s identifies any assumed schemas
> + used to specify the predicates and classes of the data model. The
> + reference may be a file name or a URL (and may be mapped by the
> + file manager).</p>
> +
> + <p>Eyeball automatically assumes the RDF and RDFS schemas, and
> + the built-in XSD datatype classes. The short name <i>owl</i> can
> + be used to refer to the OWL schema, <i>dc</i> to the Dublin Core
> + schema, <i>dcterms</i> to the Dublin Core terms schema, and
> + <i>dc-all</i> to both.</p>
> +
> +<pre>
> +-assume owl
> +-assume owl dc-all
> +-assume owl my-ontology.owl
> +</pre>
> +
> + <h3>-sign and -accept (experimental)</h3>
> +
> + <p>If <i>-sign</i> is specified, Eyeball first does a
> + <i>-check</i>. If no problem reports are
> + generated, Eyeball writes a <i>signed</i> version of
> + the current model to the standard output. The signature
> + records the Eyeball configuration used and a weak hash
> + of the model. If the input model is already signed, that
> + signature is discarded before computing the new signature
> + and writing the output.
> + </p>
> +
> + <p>
> + If <i>-accept</i> is specified, the model is checked for its
> + signature. If it is not signed, or if the signature does
> + not match the content of the model -- either the hash fails,
> + or the recorded configuration is not sufficient -- a problem
> + is reported; otherwise not.
> + </p>
> +
> + <p>
> + The intended use of <i>-sign</i> and <i>-accept</i>
> + is that an application can require signed models
> + which have passed some minimum set of inspections.
> + The application code can then rely on the model
> + having the desired properties, without having to
> + run potentially expensive validation checks every
> + time a model is loaded.
> + </p>
> +
> + <p>
> + <i>Important</i>. Model signing is intended to catch careless
> + mistakes, not for security against malicious users.
> + </p>
> +
> + <h3>-version</h3>
> +
> + <p>
> + Eyeball will print its version on the standard error
> + stream (currently "<i>Eyeball 2.4 (A Verbs Omen)</i>").
> + </p>
> +
> + <h3>-remark</h3>
> +
> + <p>Normally Eyeball issues its report or signed model to
> + the standard output and exits with code 0 (success)
> + or 1 (failure) with no additional output. Specifying
> + <i>-remark</i> causes it to report <i>success</i>
> + or <i>some problems reported</i> to standard error.
> + </p>
> +
> +
> + <h3>-repair and -analyse (experimental)</h3>
> +
> + <p>These operations are not currently documented. Try them at
> + your peril: <i>-repair</i> may attempt to update your models.
> + </p>
> +
> + <h3>-render Name</h3>
> +
> + <p>The eyeball reports are written to the standard output; by
> + default, the reports appear as text (RDF rendered by omitting the
> + subjects - which are all blank nodes - and lightly prettifying
> + the predicate and object). To change the rendering style, supply
> + the <i>-render</i> option with the name of the renderer as its
> + value. Eyeball comes with N3, XML, and text renderers; the
> + Eyeball config file associates renderer names with their
> + classes.</p>
> + <pre>
> +-render n3
> +-render rdf
> +</pre>
> +
> + <h3>setting the proxy</h3>
> +
> + <p>
> + If any of the data or schema are identified by an http: URL,
> + and you are behind a firewall, you will need specify the proxy to
> + Java using system properties; one way to do this is by using the
> + Java command line options:
> + </p>
> +
> + <pre>
> + -DproxySet=true
> + -DproxyHost=theProxyHostName
> + -DproxyPort=theProxyPortNumber
> +</pre>
> +
> + <h2>inspectors shipped with Eyeball</h2>
> +
> + <p>Eyeball comes with a collection of inspectors that do
> + relatively simple checks.</p>
> +
> + <h3>PropertyInspector (short name: "property")</h3>
> +
> + <p>Checks that every predicate that appears in the model is
> + declared in some <i>-assume</i>d schema or
> + <code>owl:import</code>ed model -- that is, is given
> + <code>rdf:type</code> <code>rdf:Property</code> or some subclass
> + of it.</p>
> +
> + <h3>ClassInspector (short name: "presumed-class")</h3>
> +
> + <p>Checks that every resource in the model that is used as a
> + class, <i>ie</i> that appears as the object of an
> + <code>rdf:type</code>, <code>rdfs:domain</code>, or
> + <code>rdfs:range</code> statement, or as the subject or object of
> + an <code>rdfs:subClassOf</code> statement, has been declared as a
> + <code>Class</code> in the <i>-assume</i>d schemas or in the model
> + under test.</p>
> +
> + <h3>URIInspector (short name: "URI")</h3>
> +
> + <p>Checks that every URI in the model is well-formed according to
> + the rules of the Jena IRI library. May apply additional rules
> + specified in the configuration file: see <a href=
> + "#uri-configuration">uri configuration</a> later for details.</p>
> +
> + <h3>LiteralInspector (short name: "literal")</h3>
> +
> + <p>
> + Checks literals for syntactically correct language codes,
> + syntactically correct datatype URIs (using the same rules as the
> + URIInspector), and conformance of the lexical form of typed
> + literals to their datatype.
> + </p>
> +
> + <h3>PrefixInspector (short name: "prefix")</h3>
> +
> + <p>The PrefixInspector checks that the prefix declarations of the
> + model have namespaces that are valid URIs and that if the prefix
> + name is "well-known" (<code>rdf</code>, <code>rdfs</code>,
> + <code>owl</code>, <code>xsd</code>, and <code>dc</code>) then the
> + associated URI is the one usually associated with the prefix.</p>
> +
> + <p>The PrefixInspector also reports a problem if any prefix looks
> + like an Jena automatically-generated prefix,
> + <code>j.<i>Number</i></code>. (Jena generates these prefixes when
> + writing RDF/XML if the XML syntactically requires a prefix but
> + the model hasn't defined one.)</p>
> +
> + <h3>VocabularyInspector (short name: "vocabulary")</h3>
> +
> + <p>Checks that every URI in the model with a namespace which is
> + mentioned in some schema is one of the URIs declared for that
> + namespace -- that is, it assumes that the schemas define a closed
> + set of URIs.</p>
> +
> + <p>The inspector may be configured to suppress this check for
> + specified namespaces: see <a href=
> + "#configure-vocabulary">vocabulary configuration</a> later.</p>
> +
> + <h3>OwlSyntaxInspector (short name: "owl")</h3>
> +
> + <p>This inspector looks for "suspicious restrictions" which have
> + some of the OWL restriction properties but not exactly one
> + owl:onProperty and exactly one constraint (owl:allValuesFrom,
> + etc).</p>
> +
> + <h3>SparqlDrivenInspector (short name: "sparql")</h3>
> +
> + <p>The SparqlDrivenInspector is configured according to <a href=
> + "#SPARQL-driven">configuring the SPARQL-driven inspector</a>, and
> + applies arbitrary SPARQL queries to the model. The queries can be
> + required to match or prohibited from matching; a problem is
> + reported if the constraint fails.</p>
> +
> + <h3>AllTypedInspector (short name: "all-typed")</h3>
> +
> + <p>
> + Checks that all URI and bnode resources in the model have an
> + rdf:type property in the model or the schema(s). If there is
> + a statement in the confiuration with property
> + <code>eye:checkLiteralTypes</code> and value <code>eye:true</code>,
> + also checks that every literal has a type or a language.
> + <i>Not</i> in the default set of inspectors.
> + </p>
> +
> + <h3>ConsistentTypeInspector (short name: "consistent-type")</h3>
> +
> + <p>
> + Checks that every subject in the model can
> + be given a type which is the intersection of the subclasses of
> + all its "attached" types -- a "consistent type".
> + </p>
> +
> + <p>
> + For example, if the model contains three types
> + <code>Top</code>, <code>Left</code>, and <code>Right</code>, with
> + <code>Left</code> and <code>Right</code> both being subtypes of
> + <code>Top</code> and with no other subclass statements, then some
> + <code>S</code> with <code>rdf:type</code>s <code>Left</code> and
> + <code>Right</code> would generate this warning.
> + </p>
> +
> + <h3>CardinalityInspector (short name: "cardinality")</h3>
> +
> + <p>
> + Looks for classes <i>C</i> that are subclasses of cardinality
> + restrictions on some property <i>P</i> with cardinality range
> + <i>min</i> to <i>max</i>. For any <i>X</i> of <code>rdf:type</code>
> + <i>C</i>, it checks that the number of values of <i>P</i> is in
> + the range <i>min..max</i> and generates a report if it isn't.
> + </p>
> +
> + <p>Literals are counted as distinct if their values (not just their
> + lexical form) are distinct. Resources are counted as distinct if
> + they have different case-sensitive URIs: the CardinalityInspector
> + takes no account of <code>owl:sameAs</code> statements.
> + </p>
> +
> + <h3>ListInspector (short name: "list")</h3>
> +
> + <p>The ListInspector performs two separate checks:
> + </p>
> +
> + <ul>
> + <li>looks for lists that are ill-formed by having multiple or
> + missing rdf:first or rdf:rest properties on their elements.
> + </li>
> +
> + <li>looks for possible mis-uses of the "typed list" idiom, and
> + reports the types so defined.
> + </li>
> + </ul>
> +
> + <p>The <i>typed list idiom</i> is boilerplate OWL for defining
> + a type which is List-of-T for some type T. It takes the form:
> + </p>
> +
> + <pre>
> +my:EList a owl:Class
> + ; rdfs:subClassOf rdf:List
> + ; rdfs:subClassOf [owl:onProperty rdf:first; owl:allValuesFrom my:Element]
> + ; rdfs:subClassOf [owl:onProperty rdf:rest; owl:allValuesFrom my:EList]
> + .
> +</pre>
> +
> + <p>
> + The type <code>my:Element</code> is the element type of the
> + list, and the type <code>EList</code> is the resulting typed list.
> + The list inspector checks that all the subclasses of
> + <code>rdf:List</code> (such as <i>EList</i> above) that are also
> + subclasses of any bnode (such as the two other superclasses of
> + <i>EList) </i>that has any property (<i>eg</i>, <i>owl:onProperty</i>)
> + that has as an object either <code>rdf:first</code> or
> + <code>rdf:rest</code> is a subclass defined by the full idiom above:
> + if not, it reports it as a <code> suspectListIdiom</code>.
> + </p>
> +
> + <h2>Eyeball problem reports</h2>
> +
> + <p>Eyeball generates its reports as <i>items</i> in a model. Each
> + item has <code>rdf:type</code> <code>eye:Item</code>, and its
> + other properties determine what problem report it is. The default
> + text renderer displays a prettified form of each item; use
> + <i>-render n3</i> to expose the complete report structure.
> + </p>
> +
> + <p>One of the item's properties is its <i>main property</i>,
> + which identifies the problem; the others are qualifications
> + supplying additional detail.
> + </p>
> +
> + <h3>PropertyInspector: predicate not declared</h3>
> +
> + <blockquote>
> + [] eye:unknownPredicate "<i>URIString</i>".
> + </blockquote>
> +
> + <p>The predicate with the given URI is not defined in any
> + of the <i>-assumed</i> schemas.
> + </p>
> +
> + <h3>ClassInspector: class not declared</h3>
> +
> + <blockquote>
> + [] eye:unknownClass "<i>URIString</i>".
> + </blockquote>
> +
> + <p>The resource with the given URI is used as a Class, but not
> + defined in any of the <i>-assumed</i> schemas.
> + </p>
> +
> + <h3>URIInspector: bad URI</h3>
> +
> + <blockquote>
> + [] eye:badURI "<i>URIString</i>"; eye:forReason <i>Reason</i>.
> + </blockquote>
> +
> + <p>The <i>URIString</i> isn't legal as a URI, or is legal but fails
> + a user-specified spelling constraint. <i>Reason</i> is a
> + resource or string identifying the reason.
> + </p>
> +
> + <table border="1" style="margin-left: 4ex; margin-right: 4ex; font-size: x-small">
> + <thead>
> + <tr><th>reason</th><th>explanation</th></tr>
> + </thead>
> + <tr>
> + <td>eye:uriContainsSpaces</td>
> + <td>the URI contains unencoded spaces, probably as a result
> + of sloppy use of file: URLs.</td>
> + </tr>
> +
> + <tr>
> + <td>eye:uriFileInappropriate</td>
> + <td>a URI used as a namespace is a file: URI, which is
> + inappropriate as a global identifier.</td>
> + </tr>
> +
> + <tr>
> + <td>eye:uriHasNoScheme</td>
> + <td>a URI has no scheme field, probably a misused relative
> + URI.</td>
> + </tr>
> +
> + <tr>
> + <td>eye:schemeShouldBeLowercase</td>
> + <td>the scheme part of a URI is not lower-case; while
> + technically correct, this is not usual practice.</td>
> + </tr>
> +
> + <tr>
> + <td>eye:uriFailsPattern</td>
> + <td>a URI fails the pattern appropriate to its schema (as
> + defined in the configuration for this eyeball).</td>
> + </tr>
> +
> + <tr>
> + <td>eye:unrecognisedScheme</td>
> + <td>the URI scheme is unknown, perhaps a misplaced
> + QName.</td>
> + </tr>
> +
> + <tr>
> + <td>eye:uriNoHttpAuthority</td>
> + <td>an http: URI has no authority (domain name/port)
> + component.</td>
> + </tr>
> +
> + <tr>
> + <td>eye:uriSyntaxFailure</td>
> + <td>the URI can't be parsed using the general URI syntax,
> + even with any spaces removed.</td>
> + </tr>
> +
> + <tr>
> + <td>eye:namespaceEndsWithNameCharacter</td>
> + <td>a namespace URI ends in a character that can appear in a
> + name, leading to possible ambiguities.</td>
> + </tr>
> +
> + <tr>
> + <td>eye:uriHasNoLocalname</td>
> + <td>a URI has no local name according to the XML
> + name-splitting rules. (For example, the URI
> + <i>http://x.com/foo#12345</i> has no local name because a
> + local name cannot start with a digit.)</td>
> + </tr>
> +
> + <tr>
> + <td>"did not match required pattern <i>Tail<sub>i</sub></i> for prefix <i>Head</i>".
> + </td>
> + <td>This badURI starts with <i>Head</i>, but the remainder doesn't
> + match any of the <i>Tail<sub>i</sub></i>s associated with that
> + prefix.
> + </td>
> + </tr>
> +
> + <tr>
> + <td>"matched prohibited pattern <i>Tail</i> for prefix <i>Head</i>".
> + </td>
> + <td>This badURI starts with <i>Head</i>, and the remainder matched
> + a prohibited <i>Tail</i> associated with that prefix.
> + </td>
> + </tr>
> + </table>
> +
> + <h3>LiteralInspector: illegal language code</h3>
> +
> + <blockquote>
> + [] eye:badLanguage "<i>badCode</i>"; eye:onLiteral "<i>spelling</i>".
> + </blockquote>
> +
> + <p>A literal with the lexical form <i>spelling</i> has the illegal
> + language code <i>badCode</i>.
> + </p>
> +
> + <h3>LiteralInspector: bad datatype URI</h3>
> +
> + <blockquote>
> + [] eye:badDatatypeURI "<i>badURI</i>"; eye:onLiteral "<i>spelling</i>".
> + </blockquote>
> +
> + <p>A literal with the lexical form <i>spelling</i> has the illegal
> + datatype URI <i>badURI</i>.
> + </p>
> +
> + <h3>LiteralInspector: bad lexical form</h3>
> +
> + <blockquote>
> + [] eye:badLexicalForm "<i>spelling</i>"; eye:forDatatype "<i>dtURI</i>".
> + </blockquote>
> +
> + <p>A literal with the datatype URI <i>dtURI</i> has the lexical form
> + <i>spelling</i>, which isn't legal for that datatype.
> + </p>
> +
> + <h3>PrefixInspector: bad namespace URI</h3>
> +
> + <blockquote>
> + [] eye:badNamespaceURI "<i>URIString</i>"
> + ; eye:onPrefix "<i>prefix</i>"
> + ; eye:forReason <i>Reason</i>.
> + </blockquote>
> +
> + <p>The namespace <i>URIString</i> for the declaration of <i>prefix</i>
> + is suspicious for the given <i>Reason</i> (see the URIInspector reports
> + for details of the possible reasons).
> + </p>
> +
> + <h3>PrefixInspector: Jena prefix found</h3>
> +
> + <blockquote>
> + [] eye:jenaPrefixFound "<i>j.Digits</i>"; eye:forNamespace "<i>URIString</i>".
> + </blockquote>
> +
> + <p>The namespace <i>URIString</i> has an automatically-generated
> + Jena prefix.
> + </p>
> +
> + <h3>PrefixInspector: multiple prefixes for namespace</h3>
> +
> + <blockquote>
> + [] eye:multiplePrefixesForNamespace "<i>NameSpace</i>"
> + ; eye:onPrefix "<i>prefix<sub>1</sub>"</i> ...
> + </blockquote>
> +
> + <p>
> + There are multiple prefix declarations for <i>NameSpace</i>,
> + namely, <i>prefix<sub>1</sub></i> etc.
> + </p>
> +
> + <h3>VocabularyInspector: not from schema</h3>
> +
> + <blockquote>
> + [] eye:notFromSchema "<i>NameSpace</i>"; eye:onResource <i>Resource</i>.
> + </blockquote>
> +
> + <p>The <i>Resource</i> has a URI in the <i>NameSpace</i>, but isn't declared
> + in the schema associated with that <i>NameSpace</i>.
> + </p>
> +
> + <h3>OwlSyntaxInspector: suspicious restriction</h3>
> +
> + <blockquote>
> + [] eye:suspiciousRestriction <i>R</i>; eye:forReason <i>Reason</i>...
> + </blockquote>
> +
> + <p>The presumed restriction <i>R</i> is suspicious for the given <i>Reason</i>s:
> + <ul>
> + <li><code>eye:missingOnProperty</code> -- there is no
> + <code>owl:onProperty</code> property in this suspicious restriction.
> + </li>
> + <li><code>eye:multipleOnProperty</code> -- there are multiple
> + <code>owl:onProperty</code> properties in this suspicious restriction.
> + </li>
> + <li><code>eye:missingConstraint</code> -- there is no <code>owl:hasValue</code>,
> + <code>owl:allValuesFrom</code>, <code>owl:someValuesFrom</code>,
> + or <code>owl:[minC|maxC|c]ardinality</code> property in this suspicious
> + restriction.
> + </li>
> + <li><code>eye:multipleConstraint</code> -- there are multiple constraints
> + (as above) in this suspicious restriction.
> + </li>
> + </ul>
> + </p>
> +
> + <p>The restriction <i>R</i> is identified by (a) supplying its immediate properties,
> + and (b) identifying its named equivalent classes and subclasses.
> + </p>
> +
> + <h3>SparqlDrivenInspector: require failed</h3>
> +
> + <blockquote>
> + [] eye:sparqlRequireFailed "<i>message</i>".
> + </blockquote>
> +
> + <p>A SPARQL query that was required to succeed against the model did not.
> + The <i>message</i> is either the query that failed or a meaningful
> + description, depending on the inspector configuration.
> + </p>
> +
> + <h3>SparqlDrivenInspector: prohibit failed</h3>
> +
> + <blockquote>
> + [] eye:sparqlProhibitFailed "<i>message</i>".
> + </blockquote>
> +
> + <p>A SPARQL query that was required to fail against the model did not.
> + The <i>message</i> is either the query that succeeded or a meaningful
> + description, depending on the inspector configuration.
> + </p>
> +
> + <h3>AllTypedInspector: should have type</h3>
> +
> + <blockquote>
> + [] eye:shouldHaveType <i>Resource</i>.
> + </blockquote>
> +
> + <p>The <i>Resource</i> has no <code>rdf:type</code>. Note that
> + when using models with inference, this report is unlikely, since
> + inference may well give the resource a type even if it has
> + no explicit type in the original model.
> + </p>
> +
> + <h3>ConsistentTypeInspector: inconsistent types for resource</h3>
> +
> + <blockquote>
> + [] eye:noConsistentTypeFor <i>URI</i>
> + ; eye:hasAttachedType <i>TypeURI<sub>i</sub></i> ...
> + </blockquote>
> +
> + <p>
> + The resource <i>URI</i> has been given the various types
> + <i>TypeURI<sub>i</sub></i>, but if we assume that subtypes are
> + disjoint unless otherwise specified, these types have no
> + intersection.
> + </p>
> +
> + <p>The ConsistentTypeInspector must do at least some type
> + inference. This release of Eyeball compromises by doing RDFS
> + inference augmented by (very) limited union and intersection
> + reasoning, as described in the Jena rules in
> + <code>etc/owl-like.rules</code>, so its reports must be
> + treated with caution. Even with these restrictions, doing type inference
> + over a large model is costly: you may need to suppress it with
> + <code>-exclude</code> until any other warnings are dealt
> + with.
> + </p>
> +
> + <p>While, technically, a resource with no attached types at all
> + is automatically inconsistent, Eyeball quietly ignores such
> + resources, since they turn up quite often in simple RDF
> + models.
> + </p>
> +
> + <h3>CardinalityInspector: cardinality failure</h3>
> +
> + <blockquote>
> + [] eye:cardinalityFailure <i>Subject</i>; eye:onType <i>T</i>; eye:onProperty <i>P</i>
> + </blockquote>
> +
> + <p>
> + The <i>Subject</i> has a cardinality-constrained <code>rdf:type</code> <i>T</i>
> + with <code>owl:onProperty</code> <i>P</i>, but the number of distinct values
> + in the model isn't consistent with the cardinality restriction.
> + </p>
> +
> + <p>Additional properties describe the cardinality restriction and the values found:
> +
> + <ul>
> + <li><code>eye:numValues</code> <i>N</i>: the number of distinct values
> + for (<i>Subject</i>, <i>P</i>) in the model.
> + </li>
> + <li><code>eye:cardinality</code>
> + [<code>eye:min</code> <i>min</i>; <code>eye:max</code> <i>max</i>]:
> + the minimum and maximum cardinalities permitted.
> + </li>
> + <li><code>eye:values</code> <i>Set</i>:
> + A blank node of type <code>eye:Set</code> with an <code>rdfs:member</code>
> + value for each of the values of <i>P</i>.
> + </li>
> + </ul>
> + </p>
> +
> + <h3>ListInspector: ill-formed list</h3>
> +
> + <blockquote>
> + [] eye:illFormedList <i>URI</i>
> + ; eye:because [eye:element <i>index<sub>i</sub></i>; <i>Problem<sub>i</sub></i>]<sub>i</sub> ...
> + </blockquote>
> +
> + <p>The list starting at <i>URI</i> is ill-formed because the element with
> + index <i>index<sub>i</sub></i> had <i>Problem<sub>i</sub></i>. The
> + possible problems are:
> + <ul>
> + <li><code>eye:hasNoRest</code> -- the element has no <code>rdf:rest</code> property.
> + </li>
> + <li><code>eye:hasMultipleRests</code> -- the element has more than one
> + <code>rdf:rest</code> property.
> + </li>
> + <li><code>eye:hasNoFirst</code> -- the element has no <code>rdf:first</code> property.
> + </li>
> + <li><code>eye:hasMultipleFirsts</code> -- the element has more than one
> + <code>rdf:rest</code> property.
> + </li>
> + </ul>
> +
> + </p>
> +
> + <h3>ListInspector: suspect list idiom</h3>
> +
> + <blockquote>
> + [] eye:suspectListIdiom <i>Type</i>.
> + </blockquote>
> +
> + <p>
> + The resource <i>Type</i> looks like it's supposed to be a use of the
> + "typed list idiom", but it isn't complete/accurate.
> + </p>
> +
> + <h2><a name="inside-configuration">inside the Eyeball configuration file</a></h2>
> +
> + <h3><a name="load-config-files" id="load-config-files"></a>configuration files</h3>
> +
> + The Eyeball
> + command-line utility is configured by files (or URLs) specified
> + on the command line: their RDF contents are unioned together into
> + a single config model. If no config file is specified, then
> + <i>etc/eyeball-config.n3</i> is loaded.
> +
> + <p>
> + The configuration file is a Jena assembler description
> + (see <a href="http://jena.sourceforge.net/assembler/index.html">
> + http://jena.sourceforge.net/assembler/index.html</a>)
> + with added Eyeball vocabulary.
> + </p>
> +
> + <p>Eyeball is also configured by the location-mapping file
> + <i>etc/location-mapping.n3</i>. The Eyeball jar contains copies
> + of both the default config and the location mapper; these are
> + used by default. You can provide your own
> + <i>etc/eyeball-config.n3</i> file earlier on your classpath or in
> + your current directory; this config replaces the default. You may
> + provide <i>additional</i> location-mapping files earlier on your
> + classpath or in your current directory.</p>
> +
> + <h3>configuring schema names</h3>
> +
> + To avoid having to quote schema
> + names in full on the Eyeball command line, (collections of)
> + schemas can be given short names.
> +
> + <pre>
> +[] eye:shortName <i>shortNameLiteral</i>
> + ; eye:schema <i>fullSchemaURL</i>
> + ...
> + .
> +</pre>
> +
> + <p>
> + A shortname can name several schemas. The Eyeball
> + delivery has the short names <i>rdf</i>, <i>rdfs</i>, <i>owl</i>,
> + and <i>dc</i> for the corresponding schemas (and mirror versions
> + of those schemas so that they don't need to be downloaded each
> + time Eyeball is run.)
> + </p>
> +
> + <h3><a name="inspectors-configuration">configuring inspectors</a></h3>
> +
> + <p>
> + The inspectors that Eyeball runs
> + over the model are specfied by <i>eye:inspector</i> properties of
> + inspector resources. These resources are identified by
> + <code>eye:shortName</code>s (supplied on the command line). Each
> + such property value must be a plain string literal whose value is
> + the full name of the Inspector class to load and run; see the
> + Javadoc of Inspector for details.
> + </p>
> +
> + <p>An inspector resource may refer to other inspector resources
> + to include their inspectors, using either of the two properties
> + <code>eye:include</code> or <code>eye:includeByName</code>. The
> + value of an <code>include</code> property should be another
> + inspector resource; the value of an <code>includeByName</code>
> + property should be the <code>shortName</code> of an inspector
> + resource.</p>
> +
> + <h3><a name="uri-configuration">configuring the URI inspector</a></h3>
> +
> + <p>As well as applying the standard URI rules, Eyeball allows
> + extra pattern-oriented checks to be applied to URIs. These are
> + specified by <code>eye:check</code> properties of the
> + <code>URIInspector</code> object in the configuration.</p>
> +
> + <p>The object of an <code>eye:check</code> property is a bnode
> + with <code>eye:prefix</code>, <code>eye:prohibit</code>, and
> + <code>eye:require</code> properties. The objects of these
> + properties must be string literals.</p>
> +
> + <p>If a URI <i>U</i> can be split into a prefix <i>P</i> and
> + suffix <i>S</i>, and there is a <i>check</i> property with that
> + prefix, and either:</p>
> +
> + <ul>
> + <li>there's a <i>prohibit</i> property and <i>S</i> matches the
> + object of that property, or</li>
> +
> + <li>there's a <i>require</i> property and <i>S</i> does not
> + match the object of that property,</li>
> + </ul>
> +
> + <p>then a problem is reported. If there are multiple
> + <code>prohibit</code>s, then a problem is reported if <i>any</i>
> + prohibition is violated; if there are multiple
> + <code>require</code>s, a problem is reported if <i>none</i> of
> + them succeed.
> + </p>
> +
> + <pre>
> +eye:URIInspector eye:check
> + [eye:prefix "urn:x-hp:"; eye:prohibit ".*:.*"]
> + ; [eye:prefix "http://example.com/"; eye:require ".*eyeball.*"]
> +</pre>The prefixes, requires, and prohibits are treated as Java
> +patterns.
> +
> + <p>
> + The URI inspector can be configured to report URIs with an
> + empty local name. These arise because the meaning of "local
> + name" comes from XML, and in XML a local name must start with
> + an NCName character, typically a letter but not a digit. Hence
> + URIs like <code>http://example.com/productCode#1829</code>
> + have an empty local name. This is sometimes confusing.
> + </p>
> +
> + <p>
> + To report empty local names, add the property
> + <code>eye:reportEmptyLocalNames</code> to the inspector
> + <code>eye:URIInspector</code> with the property value
> + <code>true</code>. You may edit the configuration file
> + or use the <code>-set</code> command-line option.
> + </p>
> +
> + <h3><a name="configure-vocabulary">configuring the vocabulary inspector</a></h3>
> +
> + <p>The vocabulary inspector defaults to assuming that schema
> + namespaces are closed. To disable this for specified namespaces,
> + the inspector object in the configuration can be given
> + <code>eye:openNamespace</code> properties.</p>
> +
> + <p>The object of each of these properties must be a resource; the
> + URI of this resource is an open namespace for which the inspector
> + will not report problems.</p>
> + <pre>
> +eye:VocabularyInspector eye:openNamespace <http://example.com/examples#>
> +</pre>
> +
> + <h3><a name="SPARQL-driven">configuring the SPARQL-driven inspector</a></h3>
> +
> + <p>The SPARQL inspector object in the configuration may be given
> + <code>eye:sparql</code> properties whose objects are resources
> + specifying SPARQL queries and problem messages.
> + </p>
> +
> + <pre>
> +eye:SparqlDrivenInspector eye:sparql [...]
> +</pre>
> +
> + <p>The resource may specify a SPARQL query which must succeed in
> + the model, and a message to produce if it does not.
> + </p>
> + <pre>
> +eye:SparqlDrivenInspector eye:sparql
> + [eye:require "select * where {?s ?p ?o}"; eye:message "must be non-empty"]
> +</pre>
> +
> + <p>If the query is non-trivial, the string may contain a
> + reference to a file containing the query, rather than the entire
> + query.
> + </p>
> +
> + <pre>
> +eye:require "@'/home/kers/example/query-one.sparql'"
> +</pre>
> +
> + <p>The quoted filename is read using the Jena file manager and
> + so respects any filename mappings. "@" characters not followed
> + by "'" are not subject to substitution, except that the
> + sequence "@@" is replaced by "@".
> + </p>
> +
> + <p>Using
> + <code>eye:prohibit</code> rather than <code>eye:require</code>
> + means that the problem is reported if the query succeeds, rather
> + than if it fails.
> + </p>
> +
> + <h3>configuring renderers</h3>
> +
> + <p>
> + The renderer class that Eyeball
> + uses to render the report into text is giving in the config file
> + by triples of the form:
> + </p>
> +
> + <pre>
> +[]
> + eye:renderer FullClassName
> + ; eye:shortName ShortClassHandler
> +</pre>
> +
> + <p>
> + The <code>FullClassName</code> is a string literal giving the
> + full class name of the rendering class. That class must implement
> + the <i>Renderer</i> interface and have a constructor that takes a
> + <code>Resource</code>, its configuration root, as its argument.
> + </p>
> +
> + <p>The <code>ShortClassHandle</code> is a string literal giving
> + the short name used to refer to the class. The default short name
> + used is <b>default</b>. There should be no more than one
> + <i>eye:shortName</i> statement with the same ShortClassHandle in
> + the configuation file, but the same class can have many different
> + short names.</p>
> +
> + <p>The <code>TextRenderer</code> supports an additional property
> + <code>eye:labels</code> to allow the appropriate labels for an
> + ontology to be supplied to the renderer. Each object of a
> + <code>eye:labels</code> statement names a model; all the
> + <code>rdfs:label</code> statements in that model are used to
> + supply strings which are used to render resources.</p>
> +
> + <p>The model names are strings which are interpreted by Jena's
> + <code>FileManager</code>, so they may be redirected using Jena's
> + file mappings.</p>
> +
> + <h2>inside the Eyeball code</h2>
> +
> + <p>Eyeball can be used from within Java code; the command line
> + merely provides a convenient external interface.</p>
> +
> + <h3>creating an Eyeball</h3>
> +
> + <p>An Eyeball object has three subcomponents: the assumptions
> + against which the model is to be checked, the inspectors which do
> + the checking, and the renderer used to display the reports.</p>
> +
> + <p>The assumptions are bundled into a single OntModel. Multiple
> + assumptions can be supplied either by adding them as sub-models
> + or by loading their content directly into the OntModel.</p>
> +
> + <p>The inspectors are supplied as a single Inspector object. The
> + method <code>Inspector.Operations.create(List)</code> creates a
> + single Inspector from a list of Inspectors; this inspector
> + delegates all its inspection methods to all of its
> + sub-inspectors.</p>
> +
> + <p>The renderer can be anything that implements the (simple)
> + renderer interface.</p>
> +
> + <p>To create an Eyeball:</p>
> +
> + <pre>Eyeball eyeball = new Eyeball( inspector, assumptions, renderer );
> +</pre>
> +
> + <h3>to eyeball a model</h3>
> +
> + <p>Models to be inspected are provided as OntModels. The problems
> + are delivered to a Report object, where they are represented as
> + an RDF model.</p>
> +
> + <blockquote>
> + eyeball.inspect( report, ontModelToBeInspected )
> + </blockquote>
> +
> + <p>The result is that same report object. The
> + <i>Report::model()</i> method delivers an RDF model which
> + describes the problems found by the inspection. The inspections
> + supplied in the distribution use the EYE vocabulary, and are used
> + in the standard reports:
> + </p>
> +
> + <p>Every report item in the model is a blank node with
> + <code>rdf:type eye:Item</code>. See earlier sections for
> + the descriptions of the properties attached to an Item.
> + </p>
> +
> + <h2>rebuilding Eyeball</h2>
> +
> + <p>
> + The provided ant script can be used to rebuild Eyeball from
> + source:
> + </p>
> +
> + <pre>
> +ant clean build jar
> +</pre>
> +
> + <p>(Omitting <code>clean</code> will do an incremental build, useful
> + for small changes.)
> + </p>
> +
> + <p>
> + The libraries required by Eyeball are all in the <code>lib</code>
> + directory, including the necessary Jena jars.
> + </p>
> +
> + <h2>creating and configuring an inspector</h2>
> +
> + <p>
> + To make a new inspector available to Eyeball, a new Inspector
> + class must be created and that class has to be described in
> + the Eyeball configuration.
> + </p>
> +
> + <h3>creating an Inspector</h3>
> +
> + <p>
> + Any inspector must implement the Inspector interface,
> + which has four operations:
> + </p>
> +
> + <ul>
> + <li><i>begin( Report r, OntModel assume )</i>:
> + Begin a new inspection. <code>r</code> is the <code>Report</code>
> + object which will accept the reports in this inpsection;
> + <code>assume</code> is the model containing the assumed
> + ontologies. <code>begin</code> is responsible for declaring
> + this inspectors <i>report properties</i>.
> + </li>
> + <li><i>inspectModel( Report r, OntModel m )</i>:
> + Do a whole-model inspection of <code>m</code>, issuing
> + reports to <code>r</code>.
> + </li>
> + <li><i>inspectStatement( Report r, Statement s )</i>:
> + Inspect the single statement <code>s</code>, issuing
> + reports to <code>r</code>.
> + </li>
> + <li><i>end( Report r )</i>:
> + Do any tidying-up reports required.
> + </li>
> + </ul>
> +
> + <p>
> + Typically <code>end</code> and one of <code>inspectModel</code> or
> + <code>inspectStatement</code> do nothing.
> + </p>
> +
> + <p>
> + An inspector must also have a constructor that takes a <code>Resource</code>
> + argument. When Eyeball creates the Inspector object, it passes the
> + <code>Resource</code> which is the root of this inspector's
> + configuration. (This is, for example, how the SPARQL-driven inspector
> + receives the query strings to use.)
> + </p>
> +
> + <p>
> + Developers may find the class <code>InpsectorBase</code> useful; it
> + has empty implementations for all the <code>Inspector</code> methods.
> + They may also find <code>InspectorTestBase</code> useful when writing
> + their inspector's tests, both for its convenience methods and because
> + it requires that their class has the appropriate constructors.
> + </p>
> +
> + <h3>reports and report properties</h3>
> +
> + <p>
> + Eyeball reports are statements in a report model. To let the
> + renderer know which property of a report is the "main" one,
> + and which order the other properties should appear in, the
> + inspector's <code>begin</code> method should declare the
> + properties:
> + </p>
> +
> + <pre>
> +r.declareProperty( EYE.badDatatypeURI );
> +r.declareOrder( EYE.badLanguage, EYE.onLiteral );
> +</pre>
> +
> + <p>
> + <code>declareProperty(P)</code> announces that <code>P</code>
> + is a report property of this inspector. <code>declareOrder(F,S)</code>
> + says that both <code>F</code> and <code>S</code> are report properties,
> + and that <code>F</code> should appear before <code>S</code> in the
> + rendered report.
> + </p>
> +
> + <p>
> + Reports are made up of <i>report items</i>, which are the subjects
> + of the report properties. To create a report item, use one of
> + <code>reportItem()</code> or <code>reportItem(S)</code>. The
> + second form is appropriate when the report is attached to some
> + statement <code>S</code> of the model being inspected; a report
> + renderer will attempt to display <code>S</code>.
> + </p>
> +
> + <p>
> + To add the main property to a report item <code>R</code>, use
> + <code>R.addMainProperty(P,O)</code>; to add non-main properties,
> + use <code>R.addProperty(P,O)</code>.
> + </p>
> +
> + <h3>configuring an inspector</h3>
> +
> + <p>
> + To add an inspector to a configuration file, choose a URI for
> + it (here we're using <code>my:Fresh</code> and assuming
> + a prefix declaration for <code>my:</code>) and a short name
> + (here, "fresh") and add a description to the configuration file:
> + </p>
> +
> + <pre>
> +my:Fresh a eye:Inspector
> + ; eye:shortName "fresh"
> + ; rdfs:label "fresh checks for my application"
> + ; eye:className "full.path.to.Fresh"
> + .
> +</pre>
> +
> + <p>
> + Replace <code>full.path.to.Fresh</code> with the full classname
> + of your inspector. Now you can use <code>Fresh</code> by adding
> + <i>-include fresh</i> to the Eyeball command line (and ensuring
> + that the class is on your classpath).
> + </p>
> +
> + <p>
> + If you want <code>Fresh</code> to be included by default, then
> + you must add it as an <code>eye:inspector</code> property
> + of the configuration root, <i>eg</i>:
> + </p>
> +
> + <pre>
> +eye:eyeball a eye:Eyeball
> + ; eye:inspector
> + eye:PrefixInspector, # as delivered
> + <span style="background: white">my:FreshInspector</span>, # new inspector
> + eye:URIInspector, # as delivered
> + ...
> +</pre>
> +
> + <p>
> + </p>
> +
> +
> +</body>
> +</html>
>
>
--
____________________________________________________________
Ian Dickinson Epimorphics Ltd, Bristol, UK
mailto:ian@epimorphics.com http://www.epimorphics.com
cell: +44-7786-850536 landline: +44-1275-399069
------------------------------------------------------------
Epimorphics Ltd. is a limited company registered in England
(no. 7016688). Registered address: Court Lodge, 105 High St,
Portishead, Bristol BS20 6PT, UK