This is a defined term.

This is a mention of a defined term.

The diagrams in this document are informal, but should be understood in the following way:

• Arrows with open heads indicate subclass relationships—pointing to the superclass
• Dotted arrows indicate type relationships—pointing to the class
• Other arrows indicate domain and possibly range restrictions to properties—pointing from the domain (arrow source) to the range (arrow target):
  • A regular arrowhead indicates a regular domain and range restriction
  • A diamond arrowhead indicates that the range is a list of the target class
  • An empty blue target indicates that the range is unspecified

The classes of the vocabulary are listed in Table 1. Each row represents a owl:Class with optional superclass relationship (using rdfs:subClassOf), textual definition (skos:definition) and optional note (skos:note).

The properties of the vocabulary are listed in Table 2. Each row represents an owl:AnnotationProperty with optional domain (rdfs:domain) and optional range (rdfs:range), textual definition (skos:definition) and optional node (skos:note).

The reasons for using owl:AnnotationProperty to represent the properties (and not owl:ObjectProperty and owl:DatatypeProperty) is that

• many of the properties take RDF lists as values, which places the vocabulary outside the OWL 2 DL fragment anyway, and
• some of the properties, ottr:value, ottr:default and ottr:parameter, need to take both literals and IRIs as values, which disqualifies the use of owl:ObjectProperty or owl:DatatypeProperty.

The domains and ranges for ottr:modifier are not translated into the ontology. This is because these should be represented as a "locally scoped" domain and range, but complex axioms on annotation properties are not supported in OWL.

The individuals of the vocabulary are listed in Table 3. Each row represents a owl:Thing with type relationship to a class (rdf:type), textual definition (skos:definition) and optional note (skos:note).

It is optional to explicitly type the resources used to specify an instance, e.g., it is not required to explicitly add the statement that an instance has the type ottr:Instance or ottr:Argument.

An ottr:Instance must be associated with the (single) ottr:Signature, ottr:Template and ottr:BaseTemplate it is an instance of using the ottr:of property. (Note that ottr:Template or ottr:BaseTemplate are disjoint subclasses of ottr:Signature.)

An ottr:Instance may have one ottr:modifier which is an ottr:ExpansionModifier. An ottr:ExpansionModifier is either ottr:cross, ottr:zipMax or ottr:zipMin.

An ottr:Instance must specify a list of arguments. This can be done in two ways: the canonical or the compact way. The canonical way is to state that an ottr:Instance has ottr:arguments which is an RDF list of ottr:Argument-s. The compact way is to directly state that an ottr:Instance has (attribute-) ottr:values which is an RDF list of RDF resources. However, as explained in the next paragraph, the reduced expressivity of the compact way does not cover all cases. The canonical way covers all cases.

ottr:InstanceShape a sh:NodeShape ;
  sh:targetSubjectsOf ottr:of , ottr:arguments , ottr:values ;
  sh:targetObjectsOf ottr:pattern, ottr:annotation ;
  sh:property 
    [ sh:path ottr:of ;
      sh:minCount 1 ;
      sh:maxCount 1 ;
      sh:nodeKind sh:IRI ;
      sh:name "Instance's reference to signature" ;
      sh:message "An instance must have exactly one reference to a signature, which must be an IRI."
    ] ,
    [ sh:path ottr:modifier ;
      sh:maxCount 1 ;
      sh:node _:instanceModifierInList ;
      sh:name "Instance modifier" ;
      sh:message "An instance can only have one modifier, which must be either ottr:cross, ottr:zipMin or ottr:zipMax."
    ];
  sh:xone 
    (
      [ sh:property
        [ sh:path ottr:arguments ;
          sh:minCount 1 ;
          sh:maxCount 1 ;
          sh:node shsh:ListShape ;
          sh:property [
            sh:path ( [ sh:zeroOrMorePath rdf:rest ] rdf:first ) ;
            sh:node ottr:ArgumentShape ;
          ] ;
          sh:name "Instance argument list" ;
          sh:message "An instance must have exactly (possibly empty) one argument list or argument value list. The argument list must contain arguments---and not argument values."
        ]  
      ]
      [ sh:property 
        [ sh:path ottr:values ;
          sh:minCount 1;
          sh:maxCount 1 ;
          sh:node shsh:ListShape
        ] ;
        sh:name "Instance argument value list" ;
        sh:message "An instance must have exactly one (possibly empty) argument list or argument value list."
      ]
    ) ;
  ## instance has listExpander if and only if exists argument with modifier.
  ## modelled as (( not A or B ) and ( not B or A))
  sh:and (
    [ sh:or ( [ sh:not _:hasPropertyInstanceModifier ] _:hasPropertyArgumentWithListExpander ) ]
    [ sh:or ( [ sh:not _:hasPropertyArgumentWithListExpander ] _:hasPropertyInstanceModifier ) ]
  )
.

### Some shapes represented by named blank nodes to avoid repetition:

# legal instance modifiers:
_:instanceModifierInList sh:in ( ottr:cross ottr:zipMin ottr:zipMax ) .

# instance has a modifier:
_:hasPropertyInstanceModifier 
  sh:property [ 
    sh:path ottr:modifier ;
    sh:minCount 1 ;
    sh:node _:instanceModifierInList ] .

# instance has an argument with a modifier:
_:hasPropertyArgumentWithListExpander 
  sh:property [
    sh:path ( ottr:arguments [ sh:zeroOrMorePath rdf:rest ] rdf:first ottr:modifier ) ;
    sh:minCount 1 ;
    sh:hasValue ottr:listExpand ] .

An ottr:Argument must have one ottr:value which is any RDF resource. The resource ottr:none can be used to explicitly specify that an ottr:Argument has no value.

An ottr:Argument may have a ottr:modifier which is an ottr:ArgumentModifier. The only ottr:ArgumentModifier is ottr:listExpand. An ottr:Argument which has a ottr:listExpand modifier, must have a ottr:value which is compatible with a list type.

Canonical vs. Compact arguments

Since the compact way of specifying an instance's arguments does not include any ottr:Argument-s, it cannot be used if it is necessary to associate information on any of the ottr:Argument-s, for instance marking an ottr:Argument with an ottr:ArgumentModifier.

The use of ottr:none is required when stating "no value" in the compact way. This is due to how lists are represented in RDF Turtle.

ottr:ArgumentShape a sh:NodeShape ;
  sh:targetSubjectsOf ottr:value ;
  ## sh:nodeKind sh:BlankNode ; ## only in strict mode?
  sh:property 
    [ sh:path ottr:modifier ;
      sh:maxCount 1;
      sh:node [ sh:in ( ottr:listExpand ) ] ;
      sh:name "Argument modifier" ;
      sh:message "An argument can only have the modifier ottr:listExpand."
    ] ,
    [ sh:path ottr:value ;
      sh:minCount 1;
      sh:maxCount 1;
      sh:name "Argument value" ;
      sh:message "An argument can only have one value."
    ] ;
  ## if listExpander, then must be blanknode/list
  ## modelled as not A or B.
  sh:or (
    [ sh:not [ sh:path ottr:modifier ; sh:hasValue ottr:listExpand ] ]
    [ sh:path ottr:value ; 
      sh:nodeKind sh:BlankNode ;
      sh:message "An argument with a ottr:listExpand modifier must have a blanknode (possibly representing a list) as value.";
    ]
  ) 
.

# 1. instance, canonical arguments
[] ottr:of ex:template ;
   ottr:arguments (
      [ ottr:value _:A ]
      [ ottr:value ottr:none ]
      [ ottr:value _:C ]
      [ ottr:value _:D ] ) .

# 2. instance, compact argument values
[] ottr:of ex:template ;
   ottr:values ( _:A  ottr:none  _:C  _:D ) .

[] ottr:of ex:template ;
   ottr:modifier ottr:cross ;
   ottr:arguments (
      [ ottr:value ( 1 2 3 4 ) ; ottr:modifier ottr:listExpand ]
      [ ottr:value ( ex:a ex:b ex:c ) ]
      [ ottr:value "string" ] 
      [ ottr:value ottr:none ]
      [ ottr:value rdfs:subClassOf ] ) .

The ottr:Signature class has two subclasses, ottr:Template and ottr:BaseTemplate, which are disjoint. We require that instances of these classes are explicitly typed with at least the most specific class.

A ottr:Signature must be identifiable by a concrete IRI (and not a blank node).

A ottr:Signature must have ottr:parameters which is a (possibly empty) RDF list of ottr:Parameter-s.

A ottr:Signature may have any number of ottr:annotation-s which are ottr:Instance-s.

ottr:SignatureShape a sh:NodeShape ;
  sh:targetClass ottr:Signature ;
  sh:targetSubjectsOf ottr:parameters, ottr:annotation ;
  sh:class ottr:Signature ;
  sh:nodeKind sh:IRI ;
  sh:message "A signature must have the type ottr:Signature or one of its subclasses, and be identified by an IRI." ;
  sh:property 
    [ sh:path ottr:parameters ;
      sh:minCount 1 ;
      sh:maxCount 1 ;
      sh:node shsh:ListShape ;
      sh:property [
        sh:path ( [ sh:zeroOrMorePath rdf:rest ] rdf:first ) ;
        sh:node ottr:ParameterShape ;
      ] ;
      sh:name "Signature parameter list" ;
      sh:message "A signature must declare exactly one parameter list, which must contain parameters."
    ]
.

ex:signature a ottr:Signature ;
  ottr:parameters ( );
  ottr:annotation 
   [ ottr:of ex:templateA ; ottr:values ( ex:signature "this an annotation" ) ] ,
   [ ottr:of ex:templateB ; ottr:values ( ex:signature "this is also an annotation" ) ] .

A ottr:Parameter must have a ottr:variable which is a RDF resource. The RDF resource representing the variable can be any resource type, i.e., IRI, blank node or literal, but we recommend using a blank node as their semantics lie close to the intention of a variable.

A ottr:Parameter can have a ottr:name which is an xsd:token.

A ottr:Parameter can have a ottr:type. How types are specified is described below.

A ottr:Parameter can have a ottr:default value which is an RDF resource.

A ottr:Parameter can have several ottr:modifier-s which are ottr:ParameterModifier-s. A ottr:ParameterModifier is either ottr:optional or ottr:nonBlank.

ottr:ParameterShape a sh:NodeShape ;
  sh:targetSubjectsOf ottr:variable, ottr:type, ottr:default ;
  ## sh:nodeKind sh:BlankNode ;  ## only in strict mode?
  sh:property 
    [ sh:path ottr:variable ;
      ##REMOVED sh:nodeKind sh:BlankNode ;  ## only in strict mode?
      sh:minCount 1 ;
      sh:maxCount 1 ;
      sh:name "Parameter variable" ;
      sh:message "A parameter must have exactly one variable.";
    ] ,
    [ sh:path ottr:type ;
      sh:node ottr:TypeListShape ;
      sh:maxCount 1 ;
      sh:name "Parameter type" ;
      sh:message "A parameter can only have one type, which must be a permissible type value."
    ] ,
    [ sh:path ottr:name ;
      sh:maxCount 1 ;
      sh:name "Parameter name" ;
      sh:datatype xsd:token ;
      sh:message "A parameter can only have one name."
    ] ,
    [ sh:path ottr:default ;
      sh:maxCount 1 ;
      sh:name "Parameter default value" ;
      sh:message "A parameter can only have one default value."
    ] ,
    [ sh:path ottr:modifier ;
      sh:node [ sh:in ( ottr:optional ottr:nonBlank ) ] ;
      sh:name "Parameter modifier" ;
      sh:message "A parameter can only have the modifiers ottr:optional or ottr:nonBlank."
    ] 
.

ottr:ModifierShape a sh:NodeShape ;
  sh:targetObjectsOf ottr:modifier ;
  sh:xone 
    ( 
      [ sh:path [ sh:inversePath ottr:modifier ] ;
        sh:node ottr:InstanceShape 
      ]
      [ sh:path [ sh:inversePath ottr:modifier ] ;
        sh:node ottr:ArgumentShape 
      ]
      [ sh:path [ sh:inversePath ottr:modifier ] ;
        sh:node ottr:ParameterShape 
      ]
) .

ex:signature a ottr:Signature ;
  ottr:parameters ( 
    [ ottr:variable _:class ]
    [ ottr:variable _:property; ottr:modifier ottr:nonBlank ]
    [ ottr:variable _:string; ottr:modifier ottr:optional ]
  ) .

Parameter types are specified using an RDF list, where the last element in the list must be a basic type, the least upper bound type ottr:LUB can only occur as the next to last element (which may also be the first), and the list types identifiers rdf:List or ottr:NEList can not be the last element.

This RDF list (written in RDF Turtle syntax): ( rdf:List ottr:NEList ottt:LUB xsd:string ) represents the type List<NEList<LUB<xsd:string>>>. If the type of a ottr:Parameter is a basic type, it can be specified using (just) the type IRI (and not a singleton RDF list containing the type).

ottr:TypeListShape a sh:NodeShape ;
   sh:targetObjectsOf ottr:type ;
   sh:xone 
     (
       [ sh:node shsh:ListShape ;
         sh:property 
           [ sh:path ( [ sh:zeroOrMorePath rdf:rest ] rdf:first ) ;
             sh:node ottr:TypeShape ;
             sh:minCount 1;
           ] ;
         sh:name "Complex parameter type" ;
         sh:message """Unrecognised complex type. A type is specified either as a list of types, 
         where the last item in the list must be a basic type, the second last can be a 'least upper bound' 
         type, and the types preceeding it can be list types."""
       ] 
       [ sh:node ottr:BasicTypeShape ;
         sh:name "Basic parameter type" ;
         sh:message "Unrecognised basic type. A type is specified either as an RDF list of types or a single basic type."
       ]
     )
.

# A list of xsd:int-s -- List<xsd:int>
(rdf:List xsd:int) 

# A non-empty list of xsd:int-s -- NEList<xsd:int>: 
(ottr:NEList xsd:int) 

# A list of list of owl:Class-es -- List<List<owl:Class>>:
(rdf:List rdf:List owl:Class) 

# The least upper bound of owl:ObjectProperty -- LUB<owl:ObjectProperty>:
(ottr:LUB owl:ObjectProperty)

# A list of least upper bounds of owl:ObjectProperty -- List<LUB<owl:ObjectProperty>>:
(rdf:List ottr:LUB owl:ObjectProperty)

The class ottr:Template is a subclass of ottr:Signature. A ottr:Template must therefore also follow the shape specification for ottr:Signature-s.

A ottr:Template may have a ottr:patten which is composed by any number of ottr:Instance-s.

ottr:TemplateShape a sh:NodeShape ;
  sh:targetClass ottr:Template ;
  sh:targetSubjectsOf ottr:pattern ;
  sh:class ottr:Template .

ex:template a ottr:Template ;
  ottr:parameters (
    [ ottr:variable _:thing ]
    [ ottr:variable _:label;   ottr:type xsd:string; ottr:modifier ottr:optional ]
    [ ottr:variable _:comment; ottr:type xsd:string; ottr:modifier ottr:optional ] 
  ) ;
  ottr:pattern 
    [ ottr:of ottr:Triple; ottr:values ( _:thing rdfs:label _:label ) ] ,
    [ ottr:of ottr:Triple; ottr:values ( _:thing rdfs:comment _:comment ) ] 
  .

The class ottr:BaseTemplate is a subclass of ottr:Signature. A ottr:BaseTemplate must therefore also follow the shape specification for ottr:Signature-s.

A ottr:BaseTemplate cannot have a ottr:pattern.

ottr:BaseTemplateShape a sh:NodeShape ;
  sh:targetClass ottr:BaseTemplate ;
  sh:class ottr:BaseTemplate ;
  sh:property 
    [ sh:path ottr:pattern ;
      sh:maxCount 0 ;
      sh:message "A base template cannot have a pattern."
    ] .

ottr:Triple a ottr:BaseTemplate ;
  ottr:parameters (
    [ ottr:type ottr:IRI; ottr:variable _:subject ]
    [ ottr:type ottr:IRI; ottr:variable _:predicate; ottr:modifier ottr:nonBlank ]
    [ ottr:type rdfs:Resource; ottr:variable _:object ] ) .

"Basic" tests are not specific to the wOTTR specification.

# INCORRECT: rdf:asdf in an incorrect IRI.
[] rdf:asdf [] .

# INCORRECT: rdfs:asdf in an incorrect IRI.
[] rdfs:asdf [] .

# INCORRECT: owl:asdf in an incorrect IRI.
[] owl:asdf [] .

# INCORRECT: sh:asdf in an incorrect IRI.
[] sh:asdf [] .

# INCORRECT: ottr:asdf in an incorrect IRI.
[] ottr:asdf [] .

# INCORRECT: An RDF list cannot have two firsts.
[ rdf:first 1 ;
  rdf:first 2 ;
  rdf:rest rdf:nil ]

# INCORRECT: An RDF list cannot have two rests.
[ rdf:first 1 ;
  rdf:rest 2, rdf:nil ]

# INCORRECT: An RDF list cannot be a loop.
_:A rdf:first 1 ;
    rdf:rest [ rdf:first 2 ; rdf:rest _:A ] .

Validate SHACL shapes against the SHACL-SHACL http://www.w3.org/ns/shacl-shacl shape description.

Validate vocabulary shapes against vocabulary token SHACL descriptions and the wOTTR SHACL description.

Validate incorrect basic unit tests shapes against vocabulary token SHACL descriptions and the wOTTR SHACL description.

Validate correct unit tests shapes against vocabulary token SHACL descriptions and the wOTTR SHACL description.

Validate correct unit tests shapes against vocabulary token SHACL descriptions and the wOTTR SHACL description.

Validate incorrect unit tests shapes against vocabulary token SHACL descriptions and the wOTTR SHACL description.

This is the implementation used for checking the correctness of the examples and the unit tests.

import java.io.IOException;
import java.io.StringWriter;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Arrays;
import java.util.stream.Collectors;

import org.apache.jena.rdf.model.Model;
import org.apache.jena.rdf.model.ModelFactory;
import org.apache.jena.riot.Lang;
import org.apache.jena.riot.RDFDataMgr;
import org.apache.jena.shacl.ShaclValidator;
import org.apache.jena.shacl.Shapes;
import org.apache.jena.shacl.ValidationReport;
import org.apache.jena.shacl.lib.ShLib;

public class RDFUtils {

  public static String readFile(String filePath) {
    try {
      return Files.readString(Path.of(filePath));
    } catch (IOException ex) {
      return filePath;
    }
  }

  public static String removePrefixes(String ttlString) {
    return Arrays.stream(ttlString.split(System.lineSeparator()))
            .filter(s -> !s.startsWith("@prefix "))
            .collect(Collectors.joining(System.lineSeparator()))
      .trim();
  }

  public static Model loadModel(String... urls) {
    Model model = ModelFactory.createDefaultModel();
    for (String url : urls) {
      RDFDataMgr.read(model, url);
    }
    return model;
  }

  public static String writeModel(Model model) {
    StringWriter writer = new StringWriter();
    RDFDataMgr.write(writer, model, Lang.TTL);
    return writer.toString();
  }

  public static ValidationReport getValidationReport(Model shape, Model data) {
    Shapes shaclShapes = Shapes.parse(shape.getGraph());  
    ValidationReport report = ShaclValidator.get().validate(shaclShapes, data.getGraph());
    return report;
  }
}

import static j2html.TagCreator.*;
import j2html.tags.DomContent;
import picocli.CommandLine;
import picocli.CommandLine.*;

import java.util.concurrent.Callable;
import java.util.Arrays;

// Inspired by https://picocli.info/#_example_application
public class Tester implements Callable<Integer> {

  @Option(names = {"-s", "--shape"}, required = true, description = "SHACL shape file/URL")
  private String[] shapeFile;

  @Option(names = {"-v", "--vocab"}, required = false, description = "Vocabulary RDF file/URL")
  private String[] vocabFiles = {};

  @Parameters(description = "RDF data files/URL")
  private String[] dataFiles = {};

  @Override
  public Integer call() throws Exception {

    var shapeModel = RDFUtils.loadModel(shapeFile);
    var vocabModel = RDFUtils.loadModel(vocabFiles);

    var container = div();

    for (String dataFile :  dataFiles) {
      var dataModel = RDFUtils.loadModel(dataFile);
      var dataModelString = RDFUtils.removePrefixes(RDFUtils.readFile(dataFile));

      dataModel.add(vocabModel);
      var report = RDFUtils.getValidationReport(shapeModel, dataModel);
      var conforms = Boolean.toString(report.conforms());

      var reportContainer = li();
      container.with(reportContainer);
      reportContainer.with(span(conforms + ": " + dataFile).withClass(conforms),
                 details(summary("Data"), pre(dataModelString)),
                 details(summary("Validation report"), pre(RDFUtils.removePrefixes(RDFUtils.writeModel(report.getModel()))))
                 );
    }
    System.out.println(container.render());
    return 0;
  }

  public static void main(String... args) {
    int exitCode = new CommandLine(new Tester()).execute(args);
    System.exit(exitCode);
  }
}