I’ve been working with FOAF a bit recently which has entailed a fair amount of reading through the FOAF namespace document. Doing a “View Source” on that page is also useful as you can then examine the embedded RDF Schema that describes the FOAF vocabulary; there’s a lot more in the schema than is visible in the HTML.
But this soon got frustrating so I gave some thought to a better approach.

First of all I dug out a link to a stylesheet posted by Edd Dumbill that can be used to extract the RDF into a separate file. I’ve put a local copy of it here.
However that also got frustrating, as it’s still not particularly readable. So, whilst thinking about an idea of Dan Brickley’s to label the FOAF properties with indications of their stability, I decided to write up an XSLT stylesheet to generate a more complete HTML presentation of the FOAF documentation.
The results — still currently a work in progress — are available here: foaf2doc.xsl and the sample output which works on the extracted RDF Schema.
As a work in progress this is liable to change. For example there are additional properties that could be added, including the aforementioned stability labelling. Comments are very welcome however. The XSLT should work with any RDF Schema, although it relies on the owl:Ontology element to describe the schema. See the FOAF schema for an example of this.
The magic of URL pipelining can be used to combine these two stylesheets together to generate documentation on-the-fly. The key additional ingredient being the W3C XSLT Service:
Building this up step by step we start with:

  1. Extracting the RDF Schema — using Edd’s stylesheet, and then
  2. Generating the Documentation — using foaf2doc.xsl

Easy huh?

9 thoughts on “foaf2doc

  1. Very nice 🙂
    Didn’t mention this in IRC, but wanted to ask: how attached are you to XSLT for this? I’m interested in the tradeoffs between using XSLT vs API-based approaches…
    Featurereq: Highlighting owl:InverseFunctionalProperty properties would be a good feature to add; those properties are pretty special in that they facilitate semweb data merging. Others do too, but they’re the crux.
    So I’m not yet sure about going over to XSLT for this. Maybe cos personally I just find it hard. At a minimum, I might ‘borrow’ your Javadoc-style layout for the foaf namespace doc, which is currently generated with a cheesy ruby script. For gory details,
    see this script masquerading as a Makefile, or the Ruby script itself at (which could now be a bunch cleaner, as I’ve a built-in RDF parser and a nicer Cwm-esque API)…

  2. I’m not that attached to XSLT, and have been thinking about building a tool around Jena that could process a number of schema and build an interlinked set of documentation. Basically, even closer to Javadoc.
    You could imagine a 3-pane view with:
    – namespaces (top left)
    – class/properties (bottom left)
    – namespace details (main body; laid out as above)
    One feature I was going to add to this as to embed the schema back into the documentation. Then you’d be able to generate the FOAF namespace doc using this stylesheet. Although we’d have to add more info to the dc:description element to include the more complete introduction.

  3. This is really nice. If you’re thinking of doing it through an API, consider putting it together as an Ant task – don’t know if you’ve looked at them before, but it’s dead straightforward. Being able to produce the “OntoDoc” along with a build and JavaDoc would be very sweet…
    I just searched to see if that name had been used, it has, for exactly the same purpose by Joe Kopena :
    Seems heavyweight though, uses DAMLJessKB. Hasn’t been updated for a year, perhaps you could ask for the name? JOntoDoc? (ugh!)

  4. Self-documenting ontologies

    Leigh’s put together an XSLT stylesheet to make a pretty HTML representation of an RDF Schema. Just tried it on…

  5. Hi Danny glad you liked it, and thanks for trying this out on another schema — saves me doing it!
    An Ant task sounds like a good idea, I’ll add it to my TODO list.
    After posting my earlier comment in response to Dan it occured to me that I am quite wedded to XSLT! Specifically, I wouldn’t want to generate the HTML presentation programmatically as it’d limit the options for altering the layout.
    So I’m thinking that perhaps a better version of this would be to use Jena to load the RDF Schema, pull in seeAlsos and other referenced schemas (owl:imports?) to build a complete model to be documented. This can then be written out to a single (large!) RDF file that can then be processed using XSLT as I’m doing now.
    This has the benefit of avoiding having to traverse multiple RDF schema in XSLT and will also limit some of the syntax variability.
    Wrapping that in an Ant task ought to be straight-forward.
    re: URL splitting. It’s just finding the last index of “/” in the URL. I should probably try “#” first and then “/” otherwise. The relevant bit of code is in the “substring-after-last” named template that I stole from the XSLT FAQ.
    I’m pretty sure that there are likely to be other glitches when using this with other RDF schemas. For example I should probably check for an rdf:Description for the schema if there isn’t an owl:Ontology section.

  6. Yep, I think what you’re saying about XSLT is probably a good approach (like danbri I find it hard, but think it’s just soooo nifty that it’s worth the effort). It would be good to try and keep a clear separation between the XSLT and Jena bits though – both should be reusable on their own in other environments.
    re. grabbing rdf:Description etc – might be worth seeing how the different alternatives are done in the XSLT RDF (to NTriples) parser(s) – should be linked from the ESW Wiki somewhere.

Comments are closed.