Templates

Resource templates

Graphity sitemap ontology contains resource templates expressed in RDF/OWL. Resource template defines a class of resources that:

• their URI identifiers share the same URI pattern (match specified URI template)
• their RDF representation was generated from SPARQL queries sharing the same pattern (match specified SPIN template)

An example of a resource template:

<#LabelResourcesContainer> a owl:Class, gp:Template ;
    rdfs:subClassOf foaf:Document, ldp:Container, sioc:Container, lda:ListEndpoint ;
    gp:uriTemplate "/resources/labelled" ;
    spin:query <#DescribeLabelResources> ;
    gp:limit 20 ;
    gp:orderBy "label"^^xsd:string ;
    rdfs:label "Labelled resource container" ;
    rdfs:isDefinedBy <#> .

In this example, resource's URI template is /resources/labelled, defined using gp:uriTemplate property. The template is mapped to the following SPARQL query in SPIN syntax using spin:query property:

<#DescribeLabelResources>    a       sp:Describe, sp:Query ;
      sp:text """PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
PREFIX foaf: <http://xmlns.com/foaf/0.1/>
PREFIX sioc: <http://rdfs.org/sioc/ns#>
PREFIX dc: <http://purl.org/dc/elements/1.1/>
PREFIX dct:  <http://purl.org/dc/terms/>

DESCRIBE ?this ?resource WHERE {
    {
        SELECT ?resource
        WHERE {
            ?resource rdfs:label|dct:title ?label .
            FILTER isURI(?resource) .
        }
    } .
}"""^^xsd:string .

During request processing in Graphity, if a resource with relative URI /resources/labelled(relativized against webapps base URI) is requested, the SPIN query will be built withgp:limitandgp:orderBy` modifier values and executed:

PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
PREFIX foaf: <http://xmlns.com/foaf/0.1/>
PREFIX sioc: <http://rdfs.org/sioc/ns#>
PREFIX dc: <http://purl.org/dc/elements/1.1/>
PREFIX dct:  <http://purl.org/dc/terms/>

DESCRIBE ?this ?resource WHERE {
    {
        SELECT ?resource
        WHERE {
            ?resource rdfs:label|dct:title ?label .
            FILTER isURI(?resource) .
        }
    LIMIT 20
    ORDER BY ?label
    } .
}

URI templates

Graphity is currently using JAX-RS @Path URI template syntax, which is based on Java-style regexp pattern. JAX-RS defines a priority algorithm which Graphity is using to select the best match even if the request URI is matching multiple templates. For example, more specific /resources/labelled takes precedence over the catch-all /{path: .*}`.

SPIN templates

Graphity is using TopBraid SPIN API to store and manage SPARQL queries as RDF. Queries are attached to resource classes as SPIN queries using the spin:query property. It expects a query resource, i.e. an instance of sp:Ask, sp:Describe etc., usually as a blank node. SPIN also allows using instances of SPIN Templates wherever a query is expected (they are known as "template calls").

Like in SPIN API, ?this variable has a special meaning in Graphity. When processsing SPARQL query, it is always bound to the URI of the request (including query string). In other words, if you define a template with query DESCRIBE ?this, what will be executed is DESCRIBE <http://localhost:8080/> if request to http://localhost:8080 matches this template.

Read more about SPIN: SPIN - SPARQL Inferencing Notation.

XSLT

Graphity Client XSLT stylesheets work by transforming raw RDF/XML. Each layout mode is usually produced by transforming RDF result with a group templates for each level of RDF/XML elements, using additional metadata from vocabularies to improve user experience. The default stylesheets are implemented for Jena's RDF/XML layout which groups statements by subject but does not nest:

• /rdf:RDF which represents the RDF model
• /rdf:RDF/rdf:Description resource description which contains properties
• /rdf:RDF/rdf:Description/@rdf:about (subject) resource URI
• /rdf:RDF/rdf:Description/@rdf:nodeID (subject) blank node ID
• /rdf:RDF/rdf:Description/* predicate (e.g. rdf:type) which URI is concat(namespace-uri(), local-name())
• /rdf:RDF/rdf:Description/*/@rdf:resource object resource
• /rdf:RDF/rdf:Description/*/@rdf:nodeID object blank node ID

There are currently following default template modes that should be reused by Graphity applications, if possible:

• rdf:RDF - model level templates found in the master layout stylesheet
  • default one which renders full resource description
  • gc:ListMode renders a list of resources (possibly with descriptions)
  • gc:TableMode renders a table with resources as rows and properties as columns
  • gc:ThumbnailMode renders a gallery of thumbnails
• rdf:Description - resource level templates found in the per-vocabulary import stylesheets
  • default one which renders full resource description (by default header and property list)
  • gc:LabelMode renders resource label
  • gc:DescriptionMode renders resource description
  • gc:HeaderMode renders resource header (by default with type information)
  • gc:PropertyListMode renders definition list with property names and values (by default grouped by resource types)
  • gc:CreateMode which renders an RDF/POST form for creation of new resource
  • gc:EditMode which renders an RDF/POST form for editing of existing resource

The default XSLT 2.0 stylesheets can be found under src/main/resources/org/graphity/client/writer. The master layout stylesheet imports vocabulary-specific resource-level stylesheets, and XSLT import precedence affects selection of the matching template. They use Bootstrap as the front-end HTML/CSS framework. XSLT keys are used to lookup resource descriptions in the RDF/XML tree, for example key('resources-by-page-of', $absolute-path) where the key definition is:

<xsl:key name="resources-by-page-of" match="*[@rdf:about]" use="ldp:pageOf/@rdf:resource"/>

The transformations are plugged into the application using ModelXSLTWriter which implements JAX-RS MessageBodyWriter and has to be registered as a provider in ApplicationBase. The main stylesheet that gets invoked by ModelXSLTWriter to produce response body (in case (X)HTML is requested) is configurable in web.xml. ModelXSLTWriter passes a number of JAX-RS parameters into the XSLTBuilder, such as $base-uri, $request-uri, $lang, $mode, $order-by etc.

DataManager implements URIResolver to resolve known URIs accessed from XSLT into locally cached copies of ontologies that are stored under /src/main/resources/org/graphity/client/vocabulary. Other URIs are ignored by default, but DataManager could be extended so that XSLT would load ontologies and execute queries over HTTP. However, this could dramatically increase transformation time.