Shape Expressions 1.0 Primer

Abstract

Shape Expressions associate RDF graphs with labeled patterns called "shapes". Shapes can be used for validation, documentation and transformation of RDF data.

Shape Expressions Primer is a general introduction to the Shape Expressions language. The concepts in this document are linked to the normative definitions in Shape Expressions Definition.

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document describes the Shape Expressions langauge developed as a community effort. It is being submitted to W3C so that it can inform the development of a future RDF Data Shape specification.

By publishing this document, W3C acknowledges that the Submitting Members have made a formal Submission request to W3C for discussion. Publication of this document by W3C indicates no endorsement of its content by W3C, nor that W3C has, is, or will be allocating any resources to the issues addressed by it. This document is not the product of a chartered W3C group, but is published as potential input to the W3C Process. A W3C Team Comment has been published in conjunction with this Member Submission. Publication of acknowledged Member Submissions at the W3C site is one of the benefits of W3C Membership. Please consult the requirements associated with Member Submissions of section 3.3 of the W3C Patent Policy. Please consult the complete list of acknowledged W3C Member Submissions.

BASE <http://base.example/#>
PREFIX ex: <http://ex.example/#>
PREFIX foaf: <http://foaf.example/#>
PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>

start = <IssueShape>

Labeled Shape Expression (defn)

A shape expression is a labeled pattern for a set of RDF Triples with a common subject. Syntactically, it's a pairing of a label, which is an IRI or a blank node, and a rule inside a pair of "{" "}". Typically, this rule is a conjunction of constraints separated by ',':

<IssueShape> {
    ex:state (ex:unassigned ex:assigned),
    ex:reportedBy @<UserShape>,
    ex:reportedOn xsd:dateTime,
    ( ex:reproducedBy @<EmployeeShape>,
      ex:reproducedOn xsd:dateTime      )?,
    ex:related @<IssueShape>*
}

The rules in the above example have links to sections describing their interpretation.

---

The following UserShape is referenced by the IssueShape above. Where the above labeled shape expression describes the data related to issues in some issue tracker, this captures the information about the users of that system.

<UserShape> {
    (foaf:name xsd:string
     | foaf:givenName xsd:string+,
       foaf:familyName xsd:string),
    foaf:mbox rdf:Resource
}

---

The EmployeeShape below is referenced by the IssueShape above and included here for completeness. It does not introduce any new features of the language.

<EmployeeShape> {
    foaf:givenName xsd:string+,
    foaf:familyName xsd:string,
    foaf:phone rdf:Resource+,
    foaf:mbox rdf:Resource
}

Cardinality

The <IssueShape> example also includes a GroupRule with a cardinality of 0 or 1:

    ( ex:reproducedBy @<EmployeeShape>,
      ex:reproducedOn xsd:dateTime      )?

As explained above, this requires that the data have either neither or both of those triples.

Cardinality constraints may appear on ArcRules and GroupRules. They may be expressed as one of (?, +, *) or as one or two integers in {}s. If there is only one number in {}s, the minimum cardinality is that number and the maximum is unconstrained. An employee record which permitted from one to three given names would look like

    foaf:givenName xsd:string{1,3}

Inheritance and Inclusion

It is frequently useful to reuse or extend a shape. For instance, if both the <UserShape> and <EmployeeShape> permitted the same alternatives for specifying a name and email address, these could be factored into a separate shape called a <PersonShape>:

<PersonShape> {
    ( foaf:name xsd:string
      | foaf:givenName xsd:string+,
        foaf:familyName xsd:string
    ),
    foaf:mbox rdf:Resource
}

<UserShape> {
    & <PersonShape>
}

<EmployeeShape> {
    & <PersonShape>,
    foaf:phone rdf:Resource+
}

In this example, the <UserShape> provides no additional constraints beyond those of the included <PersonShape>.

We may have several derivatives of <PersonShape>, any of which could provide an <IssueShape>'s ex:reportedBy value. We can signify this by changing <IssueShape> to have ex:reportedBy @<PersonShape> and define sub-shapes of <PersonShape>. This is done with an inclusion directive before the shape definition. We may not want the base <PersonShape> to satisfy any ValueReferences directly, instead requiring only derivates of <PersonShape>. This is accomplished by labeling <PersonShape> VIRTUAL per the hierarchy example:

<IssueShape> {
    ex:state (ex:unassigned ex:assigned),
    ex:reportedBy @<PersonShape>
    # ...
}

VIRTUAL <PersonShape> {
    ( foaf:name xsd:string
      | foaf:givenName xsd:string+,
        foaf:familyName xsd:string
    ),
    foaf:mbox rdf:Resource
}

<UserShape> & <PersonShape> {
    # additional User properties
}

<EmployeeShape> & <PersonShape> {
    foaf:phone rdf:Resource+
    # additional Employee properties
}

Should there be a "greedy" directive to accept only the variant which touches the most triples? An alternative is to say that parent classes are "closed" in the sense that no other properties may appear on a subject matched by that shape.

Semantic Actions

The <IssueShape> example above includes both ex:reportedOn and ex:reproducedOn dateTimes. It would be reasonable in the interest of data quality to ensure that the ex:reproducedOn dateTime, if present, were temporally after the ex:reportedOn dateTime. While ShEx itself has no built-in functionality for comparing dateTimes, specific extensions may offer that functionality. The example below (failed semantic action validation) includes semantic actions to test date order in either Javascript or SPARQL:

    ex:reportedOn xsd:dateTime
        %js{ report = _.o; return true; %},
    (ex:reproducedBy @<EmployeeShape>,
     ex:reproducedOn xsd:dateTime
        %js{ return _.o.lex > report.lex; %}
        %sparql{ ?s ex:reportedOn ?rpt . FILTER (?o > ?rpt) %}
    )

Semantic actions may also be used to generate schema-specific parsers or tools. Below is an excerpt of a tool that uses a DOM tree to translate the the Issue example into an XML document:

<IssueShape> {
    ex:state (ex:unassigned ex:assigned)
        %js{ doc = _.createDocument('http://ex.example/xml', 'Issue', undefined);
             issue = doc.documentElement
             issue.setAttribute('id', _.s.lex.substr(17));
             state = doc.createElementNS('http://ex.example/xml', 'state');
             state.textContent = _.o.lex.substr(17);
             issue.appendChild(state); %},
    ex:reportedBy @<UserShape>,
    …
} %js{ console.log(new XMLSerializer().serializeToString(doc)); %}

This example relies on a particular invocation for semantic actions, but illustrates the power in the extensibility mechanism.

Language Summary

The IssueShape tutorial above is oriented towards a particular use case where the schema will use a very explicit set of predicates and accept no others. Shape Expressions is also useful for controlling describing interfaces or graph patterns where any predicates are allowed except those in controlled namespaces. For example, some systems like Annotea reserved the assertion of dc:creator arcs for the system to maintain provenance information. The language summary below includes language features to describe such an interface.