RDFa-DOM-API

From RDFa Working Group Wiki
Jump to: navigation, search

Draft specification of an RDFa DOM API

contact: Benjamin Adrian, mailto:benjamin.adrian@dfki.de

This is a first version of an RDFa DOM API [1]. It is ready for comments and code snippets that show merits or flaws of this API.

Web IDL

 #pragma prefix "w3c.org.dom"
 module rdfa {


An RDFResource is the abstract root type in the hierarchy of RDF datatypes used in the RDFa DOM API.

 interface RDFResource {}              // This interface builds the abstract root of an RDF hierarchy.

An RDFLiteral represents literal values in RDFa. In RDF literals may be attached with either a language tag or a datatype as URI. The language tag is a two characters long identifier for a certain language. If given it defines the language of the literal value. The datatype URI defines the datatype of the literal's value such as xsd:DataTime or xsd:boolean. If a type is given, the language tag must be null. If the language tag is given, the type is set to RDF:Literal.

 interface RDFLiteral : RDFResource {
    readonly attribute DOMString value;                                           // the lexical value of this literal.
    readonly attribute DOMString language;                                        // a language tag as defined by [RFC-3066], normalized to lowercase.
    readonly attribute URI type;                                                  // a datatype URI being an RDF URI reference.
 
    RDFLiteral createLiteral(in DOMString value, optional in DOMString language);
    RDFLiteral createLiteral(in DOMString value, optional in URI type);
 }

RDFNode is an abstract type in an RDF graph subsuming the disjunctive subtypes URI and BlankNode.

 interface RDFNode : RDFResource {}


The type URI models a URI reference inside the RDF graph as it specified in [2].

 // A URI consists of a lexical representation that can be split into two components, namespace and suffix.
 // Two URIs are the same if their lexical representation equals on character level.
 interface URI : RDFNode {
 
    readonly attribute DOMString value;                    // The lexical representation of the URI reference.
    readonly attribute DOMString namespace;                // The namespace component of the URI reference.
 
    URI createURI(in DOMString value);
    URI createURI(in DOMString namespace, in DOMString suffix);
 }

A BlankNode is an anonymous RDFNode as defined in [3].

 // For comparing two BlankNodes an identifier is used. Two BlankNodes are the same if the their identifiers equal on character level.
 interface BlankNode :RDFNode {
    readonly attribute DOMString id;                       // The identifier of the BlankNode
 
    BlankNode createBlankNode(in DOMString identifier);
 }


This is the basic data structure to represent an RDF triples as defined in [4].

 interface RDFTriple {
 
 readonly attribute RDFNode subject;                          // subject value of a RDFTriple.
 readonly attribute URI predicate;                            // predicate value of a RDFTriple.
 readonly attribute RDFResource object;                       // object value of a RDFTriple.
 
 // quad extension to model the triple's provenance
 readonly attribute DOMString context;                      // an IRI, representing the base URI of the current web page
 
 // create a new Triple with an object of type RDF_TYPE_BLANK_NODE or RDF_TYPE_IRI
 RDFTriple createTriple(
                           in RDFNode subject,        // subject value of an RDFTriple.
                           in URI predicate,          // predicate value of an RDFTriple.
                           in RDFResource object      // object value of an RDFTriple.
 );
 };
  • Comments from Toby Inkster:
    • provide a predicateType method (even if we know it will always return RDF_TYPE_IRI) for consistency
      • Benjamin Adrian added an RDF hierarchy of RDFResource -> RDFLiteral; RDFNode -> BlankNode; URI to distinguish.
    • perhaps subject, predicate and object are too RDF-jargony? Maybe reuse RDFa terminology and call them about, property/rel and content/resource?
    • change the createRDFTriple functions to be called createTriple instead. An initialism (RDF) looks bad in a camel-case function name. Are we worried that we need to be specific that we're not creating non-RDF triples?

This is a data structure for a plain list of RDFTriple objects (see also w3c:dom:NodeList).

 // A simple list of RDFTriple objects. As simple as DOM::NodeList
 interface RDFTripleList {
 
 readonly attribute unsigned long length;                 // returns the current amount of RDFTriple objects inside this list
 
 // returns the RDFTriple object inside this list at position index
 RDFTriple item(
                           in unsigned long index         // a positive integer value less than RDFTripleList::length that represents an index inside the RDFTripleList
 );
 };

This is a function for testing RDFTriple objects if they are valid or not. It can be implemented by application developers. In addition it is useful to predefine a bunch of static RDFTripleFilter objects for common RDF queries, i.e., filter for triples with predicate RDF::type, or the RDFTriple::object's type is RDF_TYPE_PLAIN_LITERAL, or RDF_TYPE_TYPED_LITERAL, etc.

 interface RDFTripleFilter {
 
 // This function returns true if the passed RDFTriple triple is tested as valid. Otherwise it returns false
 boolean acceptRDFTriple(
                           in RDFTriple triple            // the triple that should be tested
 );
 };

This is an extension of DOM::Node specification. It add two methods, one for testing if RDFa content can be extracted from a Node, the other for extracting this content as RDFTripleList.

 // see w3c:dom:Node
 interface Node {
 
 // This function returns true if the current DOM Node object contains any RDFa content. An optional RDFTripleFilter can be passed to test Node objects for certain kind of RDFTriples.
 boolean containsRDFa(
                           in optional RDFTripleFilter filter    // This optional RDFTripleFilter can be used to test for certain kinds of RDFa content.
 );
 
 // This function returns a RDFTripleList of RDFTriple objects that can be extracted form th DOM Node object's RDFa content. An optional RDFTripleFilter can be passed to filter the Node objects for certain kind of RDFTriple objects.
 RDFTripleList getTriples(
                           in optional RDFTripleFilter filter    // This optional RDFTripleFilter can be used to test for certain kinds of RDFa content.
 );
 
 };

The RDFTripleIterator is a data structure that iterates through RDFa content inside Nodes of the DOM tree.

 //  The RDFTripleIterator is design the same way like the DocumentTraversal::NodeIterator.
 interface RDFTripleIterator {
 
 readonly attribute Node root;                                        // The Node inside the DOM Tree taken as root node to start from the extraction of RDFa content. 
 
 readonly attribute RDFTripleFilter filter;                           // The RDFTripleFilter object that filters the Node objects in the subtree for certain RDFa content.
 
 RDFTriple nextRDFTriple()                                            // Returns the next RDFTriple object that is found inside the subtree of DOM nodes or NULL if no more exist.
 
 RDFTriple previousRDFTriple()                                        // Returns the previous RDFTriple object that is found inside the subtree of DOM nodes or NULL if no previous RDFTriples exist.
 
 // factory method to create newRDFTripleIterator objects.
 RDFTripleIterator createRDFTripleIterator(
                                          in Node root,               // The Node inside the DOM Tree taken as root node to start from the extraction of RDFa content. 
                                          in RDFTripleFilter filter   // An RDFTripleFilter object that filters the Node objects in the subtree for certain RDFa content.
 );
 };

This is an extension of w3c:org:dom::Document. It adds one function to retrieve RDF data from web pages.

 interface Document {
  // This function extracts RDFa content from the current document in form of a list of RDFTriple objects
 RDFTripleList getRDFTriples(
                                          in optional RDFTripleFilter filter  // An RDFTripleFilter object that filters the Node objects in the DOM tree for certain RDFa content.
 );
 };

Code Snippets

The following code snippets reveal merits or flaws of the upper defined RDFa DOM API.

Get DOM nodes that contain RDFtriples with subject dbpedia:Kaiserslautern

function myNodeFilter(node) {
  if (node.containsRDFa(myTripleFilter)) return NodeFilter.FILTER_ACCEPT;
  else return NodeFilter.FILTER_SKIP;
}
 
 
function myTripleFilter(triple) {
  return (triple.subject == '[dbpedia:Kaiserslautern]');
}
 
var klFinder = document.createNodeIterator(document,
                                          NodeFilter.SHOW_ELEMENT,
                                          myNodeFilter);
 
var klNode;
while((klNode = jkFinder.nextNode()) != null) {
   alert('Hello K-Town')
}