RDFaAuthoring

Authors: Martin Hepp, mheppATcomputerDOTorg; Andreas Radinger, andreasDOTradingerATunibw.de

Any feedback and comments to this page are highly appreciated. Please e-mail to mheppATcomputerDOTorg or use the GoodRelations mailing list

Tips for Authoring RDFa

Essentials

  1. Use RDFa in "Snippet Style" rather than combining visible markup and RDFa data markup.

    • See section below for details.

  2. Don't use XML shortcuts for empty div / span elements, for HTML lax parsers will stumble over those.

    • Bad: {=html} <div property="vcard:country-name" content="Germany" xml:lang="en"/>
    • Good: {=html} <div property="vcard:country-name" content="Germany" xml:lang="en"> {=html} </div>

  3. Use ''' {=html} <div> instead of''' for snippet style, because Firefox and other DOM parsers may ignore "empty" spans (but not divs).

    • Bad:
    • Good: {=html} <div property="vcard:country-name" content="Germany" xml:lang="en"> {=html} </div>

  4. Do use XML shortcuts with a space before the slash for elements that are always empty: area, base, basefont, br, col, hr, img, input, isindex, link, meta, and param.

    • Bad:

    • Bad:
    • Good:

  5. Do use both lang and xml:lang attributes when specifying the language of an element in markup languages that support the use of both.

    • For RDFa "snippet style" elements, xml:lang seems sufficient, though.

  6. Ensure that when content or attribute values contain the reserved character & it is used in its escaped form &

    • Bad: {=html} <div rel="gr:hasManufacturer" resource="http:/www.heppnetz.de/gr4shops/brands.html?id=1&lang=de"> {=html} </div>
    • Good: {=html} <div rel="gr:hasManufacturer" resource="http:/www.heppnetz.de/gr4shops/brands.html?id=1&lang=de"> {=html} </div>

  7. We recommend that you properly escape all special characters in element contents and attributes. Hint: When using HTML templating engines like Jinja for Python, you can usually turn this on for all processing. Unescaped special characters are a frequent cause for serious trouble, because there may be just a few entries in your database that contain problematic characters, so resulting problems are hard to spot.

    • Bad: {=html} <div property="rdfs:comment" content="The Rebel T2i EOS 550D is Canon's new fast & robust digital camera"> {=html} </div>
    • Good: {=html} <div property="rdfs:comment" content="The Rebel T2i EOS 550D is Canon&#39;s new fast & robust digital camera"> {=html} </div>

  8. Workflow for the productive authoring of more complicated data structures:
    *Model the data in RDF Turtle Syntax.
    *Convert Turtle to RDF/XML with http://www.rdfabout.com/demo/validator/
    *Convert resulting RDF/XML to RDFa snippet with http://www.ebusiness-unibw.org/tools/rdf2rdfa/
    *If needed, delete the class="description" and class="rdf2rdfa" attributes, unless you need them to control the formatting.

  9. You can serve your XHTML+RDFa pages as either application/xhtml+xml or text/html. Even though the W3C recommends application/xhtml+xml for proper XHTML, we tend to recommend text/html, because some browsers seem to have problems with XHTML served as XML (we have no official source for that suspicion yet, though). General rule:
    *XHTML1.0 + RDFa: Use application/xhtml+xml
    *HTML5 or HTML4 with RDFa: Use text/html

  10. Encode your document in UTF-8 or UTF-16.
    *When delivering the document from a server, set the character encoding for a document via the charset parameter of the HTTP Content-Type header.

    • When not delivering the document from a server, set the encoding via a "meta http-equiv" statement in the document (e.g., {=html} <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> ).

  11. For 1-to-many relationships between data objects that are contained in two different HTML pages, use "rev" on the "many" side instead of "rel" on the "1" side.

    • Example: The link for foo:company gr:offers foo:offer should be put into the "product items" page using the "rev" attribute instead of into the company page using the standard "rel" attribute.
    • This keeps the "1" side (e.g. the company page) short and stable.

  12. For linking back between an RDFa data element and the page containing the RDFa markup, use foaf:page with an empty resource attribute.

RDFa in Snippet Style

Use RDFa in "Snippet Style" rather than combining visible markup and RDFa data markup.

  • Bad: Reusing existing text and values at their original position (for non-trivial data - okay for simple data)
    • Example:

...

+49-89-6004-0

...

  • Good:Putting RDFa meta-data into empty {=html} <div> elements using the content="xyz" attribute at the end of the HTML document

    • Example:

...

Phone: +49-89-6004-0

...

The advantage of combining visible markup and RDFa data markup is that updating the human-readable content means automatically updating the associated meta-data. The downside is that mixing the data level and the presentation level can create complicated mark-up. Also, it is impossible to create generic tools that provide the mark-up for easy copy-and-paste.
The advantage of RDFa in "Snippet Style" is that it is easy to create generic tools that provide the mark-up for easy copy-and-paste or inclusion at the time of creating a dynamic page.
Also, RDFa in "Snippet Style" will not be corrupted by modifications to the visible markup, which may be carried out by developers not familiar with RDFa.


Do you have additional recommendations? Please email to mheppATcomputerDOTorg.

Background Infos on XHTML+RDFa Media Type

We suspect that it is best to serve XHTML+RDFa content as text/html, because serving it as XML via application/xhtml+xml will require a proper XML declaration that may irritate some browsers. All known RDFa extractors (e.g. PyRDFa) can properly handle RDFa from text/html, while not all browsers on the market can properly render XHTML served as XML.

  • <http://www.w3.org/TR/rdfa-syntax/> : "XHTML+RDFa documents SHOULD be labeled with the Internet Media Type "application/xhtml+xml" as defined in [RFC3236]. For further information on using media types with XHTML family markup languages, see the informative note [XHTMLMIME]. "
  • <http://www.w3.org/TR/2002/NOTE-xhtml-media-types-20020801/#application-xhtml-xml> : "As for character encoding issues, as mentioned in "6. Charset default rules" of [RFC3236], 'application/xhtml+xml' has the same considerations as 'application/xml'. See section 3.3 for details."
  • Section 3.3 eq. <http://www.w3.org/TR/2002/NOTE-xhtml-media-types-20020801/#application-xml> : "''Therefore, while it is STRONGLY RECOMMENDED to specify an explicit charset parameter through a higher-level protocol, authors SHOULD include the XML declaration (e.g. {=html} <?xml version="1.0" encoding="EUC-JP"?> ). Note that a meta http-equiv statement will not be recognized by XML processors, and authors SHOULD NOT include such a statement in an XHTML document served as 'application/xml' (and 'application/xhtml+xml' as well for that matter).''"

Acknowledgments

The authors would like to thank Toby A. Inkster, Manu Sporny, and Mark Birbeck for their valuable feedback on using GoodRelations in RDFa.

References and Resources