FOAF Syntax: Tips and Examples

It is sometimes easiest to learn from examples. But sometimes it isn't clear from an example which things are important, which bits can be changed and which things are optional. FOAF documents are designed to be flexible and genuinely extensible: you can miss out information you don't know, or add in new information using other vocabularies. So long as you stick to the basic pattern for organising the structure of a FOAF document, you can use it to make all sorts of assertions.

The basic structure of a FOAF document is that of W3C's RDF (Resource Description Framework) syntax. This is just a way of writing text files in a way that maps into a set of "triples" corresponding to claims about the world. Each triple says of some object that is has some specified relationship to another object or textual value. For the most part, you can ignore this and just copy-and-paste from examples. However, if you don't know the rules of the RDF syntax, it can be easy to mess up and create a document that doesn't work by the RDF rules. The RDF syntax rules may seem a bit abstract compared to traditional file formats which say exactly what can and can't appear in a file. However it is just this flexibility that allows FOAF to be easily extended.

The examples below show some common mistakes with RDF syntax. These errors can be detected using validators such as the one W3C run (www.w3.org/RDF/Validator) or the RDF parsers used by FOAF toolkits.

Example 1: 3 common mistakes

<foaf:Person>
  <foaf:name>Dan Brickley</foaf:name>
  <foaf:homepage> rdfweb.org/people/danbri/ </foaf:homepage>
  <foaf:knows>
    <foaf:Person>
      <foaf:mbox rdf:resource="mailto:edd@xml.com" />
      <foaf:name>Edd Dumbill</foaf:name>
    </foaf:Person>
    <foaf:Person>
      <foaf:mbox rdf:resource="bijan@monkeyfist.com" />
      <foaf:name>Bijan Parsia</foaf:name>
    </foaf:Person>
  </foaf:knows>
</foaf:Person> 

This XML example (apart from ommitting namespace declarations) contains 3 syntactic errors.

* the foaf:homepage element uses the wrong syntax for URIs
* one of the mailboxes isn't identified using the mailto: URI scheme
* there should be a foaf:knows around each foaf:Person element

Details follow...

tip 1: URIs are treated differently

'URI' (Uniform Resource Identifier) is the modern name for things like URLs, names for things on the Web. Websites, mailboxes etc. We use them a lot in RDF, and hence in FOAF, as they provide a consistent strategy for identification.

The RDF syntax above has two URI-related errors.

* the foaf:homepage URI doesn't use RDF's URI syntax for properties * we've written: <foaf:homepage> rdfweb.org/people/danbri/ </foaf:homepage> * it should be: foaf:homepage rdf:resource = "rdfweb.org/people/danbri/" /> * one of the mailbox addresses uses RDF's URI syntax, but isn't represented as a URI * we've written: <foaf:mbox rdf:resource = "bijan@monkeyfist.com" /> * it should be: <foaf:mbox rdf:resource = "mailto:bijan@monkeyfist.com" />

By using these conventions for identifying things, we make it easier for RDF databases to merge together FOAF documents from various sources. For example, we could merge this information with more data about those documents or the people with those mailboxes. The syntax errors shown above would make such merging impossible.

There is one more error:

tip 2: RDF syntax is 'striped'

The above piece of XML reads fairly intuitively to a human reader. It seems to say (roughly) "there is a person, dan, who knows two other people, Edd and Bijan".

Unfortunately, a syntax error means that RDF tools won't read it this way. In RDF, the main pattern for writing information down is to making alternating use of XML elements to represent things, and then their relationships. The 'Person' elements represent objects (people); the 'knows' element represents a relationship. One of the RDF syntax rules is that this has to be done very explicitly for each relationship to something. So instead of writing the above markup, we should have written the following...

(note that the URI errors are also corrected)

<foaf:Person>
  <foaf:name>Dan Brickley</foaf:name>
  <foaf:homepage rdf:resource="rdfweb.org/people/danbri/" />
  <foaf:knows>
    <foaf:Person>
      <foaf:mbox rdf:resource="mailto:edd@xml.com" />
      <foaf:name>Edd Dumbill</foaf:name>
    </foaf:Person>
  </foaf:knows>
  <foaf:knows>
    <foaf:Person>
      <foaf:mbox rdf:resource="mailto:bijan@monkeyfist.com" />
      <foaf:name>Bijan Parsia</foaf:name>
    </foaf:Person>
  </foaf:knows>
</foaf:Person> 

This is more text to write, but it makes the document easier for machines to interpret. The difference is just that each foaf:Person element is wrapped in its own foaf:knows element.

tip 3: international characters

If you use the W3C RDF validator on your FOAF file and it validates, but when you try to use FOAF Explorer or some other tool and it does not, it may be because one of the "characters" in your FOAF file is not ASCII, in particular if you have someone in your file who's name contains a non-ASCII character, such as "Sébastien Paquet". The solution is to put this at the top of your file, above the opening rdf:RDF tag:

<?xml version="1.0" encoding="iso-8859-1"?>

There are other possible encodings, but this is the the one that seems to work best with more common text editors that support international characters.

Further Reading

  * W3C RDF page (for specs)
  * Understanding the RDF Striped Syntax

Editing notes

additions/suggestions welcomed. If you edit this page, please take care to make sure that XML examples display OK.

CategoryTutorial