ShapeMap Structure and Language

Abstract

The Shape Expressions (ShEx) language describes RDF nodes and graph structures. A node constraint describes an RDF node (IRI, blank node or literal) and a shape describes the triples involving nodes in an RDF graph. The ShapeMap language associates RDF nodes with ShEx shapes. These associations can be used to state candidate shape maps as an input to the validation process. They can be the output of a validation process, where the ShEx engine reports the conformance of RDF nodes with respect to ShEx shapes.

This document defines the ShapeMap language. See the Shape Expressions Primer for an introduction to ShEx validation and the Shape Expressions Language for a formal definition of ShEx.

Status of This Document

This specification was published by the Shape Expressions Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

This document has been developed by the Shape Expressions Community Group.

This version is an initial editor's proposal to the CG.

If you wish to make comments regarding this document, please send them to public-shex@w3.org (subscribe, archives).

1. Notation and Terminology

This document assumes an understanding of the ShEx notation and terminology.

ShapeExpression: a Boolean expression of ShEx shapes.
focus node: a node, potentially in an RDF graph, to be inspected for conformance with a shape expression.

ShExMap uses the following terms from RDF semantics [rdf11-mt]:

Node: one of IRI, blank node, Literal.
Graph: a set of Triples of (subject, predicate, object).

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

Conformance criteria are relevant to authors and authoring tool implementers. As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

A ShapeMap document complies with this specification if it conforms to the grammar described in section 6. ShapeMap grammar resulting in a valid ShapeMap structure.

3. ShapeMap structure

ShapeMap: a set of shape associations. Each shape association has at least two members: a nodeSelector and a shapeLabel, and when used for the result of validation, may have any of status, reason, or appInfo:

nodeSelector: an RDF node, or a triple pattern which is used to select RDF nodes.
shapeLabel: ShEx shapeExprLabel or the string "START" for the start shape expression.
status: [default="conformant"] "nonconformant" or "conformant".
reason: [optional] a string stating a reason for failure or success.
appInfo: [optional] an application-specific JSON-LD structure

In this document, these members can be addressed with a '.' operator. For instance, a shape association A would have an A.nodeSelector member.

If the status member is absent, the status is assumed to be "conformant". The reason and appInfo members may also be absent but have no default value.

A triple pattern has a subject pattern, predicate IRI and object pattern.

The subject pattern may be an IRI, a focus selector or a wildcard.
The object pattern may be an IRI, literal, focus selector or a wildcard.

A focus selector identifies the slot (subject or object) to be validated. A wildcard indicates that the slot may hold any value. A triple pattern has exactly one focus selector. A triple pattern maps to a SPARQL triple pattern with the following restrictions:

V (the set of variables) is either a fresh variable or a known token to identify the focus node.
The focus node token appears in either the subject or the object position.
The predicate position is filled by an IRI (I in the SPARQL definitions).

A query ShapeMap is a ShapeMap in which each shape association has only the members nodeSelector and shapeLabel.

A fixed ShapeMap is a query ShapeMap in which each nodeSelector is an RDF node. The ShEx validation process takes as input a fixed ShapeMap.

A result ShapeMap is a fixed ShapeMap with the addition of optional members status, reason and appInfo.

No two shape associations in a ShapeMap may have the same combination of nodeSelector and shapeLabel.

Example 1: invalid ShapeMaps - duplicate nodeSelector/shapeLabel pairs

This JSON ShapeMap would not be valid as it has two entries for a nodeSelector/shapeLabel pair:

[
  { "nodeSelector": "<http://data.example/node1>,
    "shapeLabel": "<http://schema.example/Shape2>,
    "status": "nonconformant" },
  { "nodeSelector": "<http://data.example/node1>,
    "shapeLabel": "<http://schema.example/Shape2> }
]

The above example has conflicting values for the status: the first asserts that node1 does not conform to Shape2; the second has no status and so asserts the default which is that it does conform. The following example is also invalid because it has duplicates even though they do not conflict:

[
  { "nodeSelector": "<http://data.example/node1>,
    "shapeLabel": "<http://schema.example/Shape2> },
  { "nodeSelector": "<http://data.example/node1>,
    "shapeLabel": "<http://schema.example/Shape2> }
]

4. ShapeMap usage

ShapeMaps are designed to express the goal or the result of validating an RDF node against a ShEx schema:

if expressing the goal, the query ShapeMap or fixed ShapeMap expresses the question posed, e.g., "does node1 conform to shape2?"
if expressing the result, the result ShapeMap expresses the outcome of a conformance check, e.g., "node1 conforms to shape2."

A query ShapeMap is converted to a fixed ShapeMap to be used as the input to the validation process. This process takes as input a query ShapeMap and a graph and produces a fixed ShapeMap. For a query ShapeMap Q and a graph G, for each shape association A in Q:

If A.nodeSelector is an RDF node, A is in the fixed ShapeMap.
If A.nodeSelector is a triple pattern, let P be a SPARQL Triple Pattern where
- If A's subject is a focus selector or a wildcard, P's subject is a fresh variable, otherwise P's subject is A's subject.
- P's predicate is A's predicate.
- If A's object is a focus selector or a wildcard, P's object is a fresh variable, otherwise P's subject is A's object.
For each triple T in G which matches P, the fixed ShapeMap has a shape association F where F.shapeLabel = A.shapeLabel and
- If A's subject is a focus selector, F.nodeSelector is T's subject.
- If A's object is a focus selector, F.nodeSelector is T's object.

5. Query and Fixed ShapeMap syntax

ShapeMaps can be easily transmitted and understood with a specialized syntax.

Example 2: simple fixed ShapeMap

A simple fixed ShapeMap might look like this:

# a simple nodeSelector/shapeLabel pair
<http://data.example/#n1> @ <http://data.example/#S2>,

and a result ShapeMap might look the same if there were no errors. It also could include a status="conformant" if there were no errors.

A query ShapeMap can include shape associations with both RDF nodes and triple patterns.

Example 3: query ShapeMap with four shape associations

# Validate a simple nodeSelector/shapeLabel pair.
<http://data.example/#n1> @ <http://data.example/#S2>,
# Validate a literal as S3.
"chat"@en-fr@<http://...S3>,
# validate everything with type Some/Type as the START shape.
{FOCUS a <http://schema.example/Some/Type>}@START,
# Validate all objects of p3.
{_ <http://...p3> FOCUS}@START

The nodeSelector (an RDF node or triple pattern) is before the '@'.
The shapeLabel is immediately after the '@'.
The 'FOCUS' keyword is a focus selector.
The '_' character is a wildcard.
The keyword "a" is a shortcut for the rdf:type (<http://www.w3.org/1999/02/22-rdf-syntax-ns#type>) property.

6. ShapeMap grammar

Production numbers followed by a letter correspond to productions in other grammars:

[1 ]	`shapeMap`	::=	`shapeAssociation (',' shapeAssociation)*`
[2 ]	`shapeAssociation`	::=	`nodeSelector shapeLabel`
[3 ]	`nodeSelector`	::=	`objectTerm \| triplePattern`
[4 ]	`subjectTerm`	::=	`iri \| 'a'`
[5 ]	`objectTerm`	::=	`subjectTerm \| literal`
[6 ]	`triplePattern`	::=	`'{' "FOCUS" iri (objectTerm \| '_') '}' \| '{' (subjectTerm \| '_') iri "FOCUS" '}'`
[7 ]	`shapeLabel`	::=	`'@' (iri \| "START") \| AT_START`
[13t]	`literal`	::=	`rdfLiteral \| numericLiteral \| booleanLiteral`
[16t]	`numericLiteral`	::=	`INTEGER \| DECIMAL \| DOUBLE`
[65x]	`rdfLiteral`	::=	`langString \| string ("^^" iri)?`
[134s]	`booleanLiteral`	::=	`"true" \| "false"`
[135s]	`string`	::=	`STRING_LITERAL1 \| STRING_LITERAL_LONG1 \| STRING_LITERAL2 \| STRING_LITERAL_LONG2`
[66x]	`langString`	::=	`LANG_STRING_LITERAL1 \| LANG_STRING_LITERAL_LONG1 \| LANG_STRING_LITERAL2 \| LANG_STRING_LITERAL_LONG2`
[136s]	`iri`	::=	`IRIREF`
Terminals Text is matched against the longest matching terminal. The PASSED TOKENS below may appear between any terminals or literal strings which appear in the grammar above.
[18t]	<`IRIREF`>	::=	"<" ([^#0000- <>\"{}\|^`\\] \| UCHAR)* ">"
[142s]	<`BLANK_NODE_LABEL`>	::=	`"_:" (PN_CHARS_U \| [0-9]) ((PN_CHARS \| ".")* PN_CHARS)?`
[17]	<`AT_START`>	::=	`"@START"`
The <`AT_START`> terminal has precendence over LANGTAG
[145s]	<`LANGTAG`>	::=	`"@" ([a-zA-Z])+ ("-" ([a-zA-Z0-9])+)*`
[19t]	<`INTEGER`>	::=	`[+-]? [0-9]+`
[20t]	<`DECIMAL`>	::=	`[+-]? [0-9]* "." [0-9]+`
[21t]	<`DOUBLE`>	::=	`[+-]? ([0-9]+ "." [0-9]* EXPONENT \| "."? [0-9]+ EXPONENT)`
[155s]	<`EXPONENT`>	::=	`[eE] [+-]? [0-9]+`
[156s]	<`STRING_LITERAL1`>	::=	`"'" ([^'\\\n\r] \| ECHAR \| UCHAR)* "'"`
[157s]	<`STRING_LITERAL2`>	::=	`'"' ([^\"\\\n\r] \| ECHAR \| UCHAR)* '"'`
[158s]	<`STRING_LITERAL_LONG1`>	::=	`"'''" ( ("'" \| "''")? ([^\\'\\] \| ECHAR \| UCHAR) )* "'''"`
[159s]	<`STRING_LITERAL_LONG2`>	::=	`'"""' ( ('"' \| '""')? ([^\"\\] \| ECHAR \| UCHAR) )* '"""'`
[73x]	<`LANG_STRING_LITERAL1`>	::=	`"'" ([^'\\\n\r] \| ECHAR \| UCHAR)* "'" LANGTAG`
[74x]	<`LANG_STRING_LITERAL2`>	::=	`'"' ([^\"\\\n\r] \| ECHAR \| UCHAR)* '"' LANGTAG`
[75x]	<`LANG_STRING_LITERAL_LONG1`>	::=	`"'''" ( ("'" \| "''")? ([^\\'\\] \| ECHAR \| UCHAR) )* "'''" LANGTAG`
[76x]	<`LANG_STRING_LITERAL_LONG2`>	::=	`'"""' ( ('"' \| '""')? ([^\"\\] \| ECHAR \| UCHAR) )* '"""' LANGTAG`
[26t]	<`UCHAR`>	::=	`"\\u" HEX HEX HEX HEX \| "\\U" HEX HEX HEX HEX HEX HEX HEX HEX`
[160s]	<`ECHAR`>	::=	`"\\" [tbnrf\\\"\\']`
[164s]	<`PN_CHARS_BASE`>	::=	`[A-Z] \| [a-z] \| [#00C0-#00D6] \| [#00D8-#00F6] \| [#00F8-#02FF] \| [#0370-#037D] \| [#037F-#1FFF] \| [#200C-#200D] \| [#2070-#218F] \| [#2C00-#2FEF] \| [#3001-#D7FF] \| [#F900-#FDCF] \| [#FDF0-#FFFD] \| [#10000-#EFFFF]`
[165s]	<`PN_CHARS_U`>	::=	`PN_CHARS_BASE \| "_"`
[167s]	<`PN_CHARS`>	::=	`PN_CHARS_U \| "-" \| [0-9] \| [#00B7] \| [#0300-#036F] \| [#203F-#2040]`
[168s]	<`PN_PREFIX`>	::=	`PN_CHARS_BASE ( (PN_CHARS \| ".")* PN_CHARS )?`
[169s]	<`PN_LOCAL`>	::=	`(PN_CHARS_U \| ":" \| [0-9] \| PLX) ( (PN_CHARS \| "." \| ":" \| PLX)* (PN_CHARS \| ":" \| PLX) )?`
[170s]	<`PLX`>	::=	`PERCENT \| PN_LOCAL_ESC`
[171s]	<`PERCENT`>	::=	`"%" HEX HEX`
[172s]	<`HEX`>	::=	`[0-9] \| [A-F] \| [a-f]`
[173s]	<`PN_LOCAL_ESC`>	::=	`"\\" ( "_" \| "~" \| "." \| "-" \| "!" \| "$" \| "&" \| "'" \| "(" \| ")" \| "*" \| "+" \| "," \| ";" \| "=" \| "/" \| "?" \| "#" \| "@" \| "%" )`
	`PASSED TOKENS`	::=	`[ \t\r\n]+ \| "#" [^\r\n]*`

A. References

A.1 Normative references

[RFC2119]: Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[rdf11-mt]: RDF 1.1 Semantics. Patrick Hayes; Peter Patel-Schneider. W3C. 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/rdf11-mt/

A.2 Informative references

[rdf11-concepts]: RDF 1.1 Concepts and Abstract Syntax. Richard Cyganiak; David Wood; Markus Lanthaler. W3C. 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/rdf11-concepts/
[shex-semantics]: Shape Expression Language. Gregg Kellogg.URL: http://shex.io/semantics
[sparql11-query]: SPARQL 1.1 Query Language. Steven Harris; Andy Seaborne. W3C. 21 March 2013. W3C Recommendation. URL: https://www.w3.org/TR/sparql11-query/