Merge remote-tracking branch 'origin/master' into issue_10

README.md

@@ -57,6 +57,29 @@ This is consistent with the queries defined in the RDF data cube specification.
 
 SPARQL SELECT queries are considered to have failed if they return any matching solutions. Like ASK queries they should return bindings describing invalid resources.
 
+### Query variables
+
+Validation queries can be parameterised with query variables which must be provided when the test suite is run. Query variables have the format `{{variable-name}}`
+within a query file. For example to validate no statements exist with a specified predicate, the following query could be defined:
+
+*bad_predicate.sparql*
+```sparql
+SELECT ?this WHERE {
+  ?this <{{bad-predicate}}>> ?o .
+}
+```
+
+when running this test case, the value of `bad-predicate` must be provided. This is done by providing an EDN file containing variable
+bindings. The EDN document should contain a map from keywords to the corresponding string values e.g.
+
+*variables.edn*
+```clojure
+{ :bad-predicate "http://to-be-avoided"
+  :other-variable "http://other" }
+```
+
+the file of variable bindings is specified when running the test case(s) using the `--variables` parameter e.g.
+
 ## Defining test suites
 
 A test suite defines a group of tests to be run. A test suite can be created from a single test file or a directory containing test files as shown in the
@@ -151,6 +174,8 @@ to the command-line invocation e.g.
 
 This will execute the tests defined within `suite2` and `suite3` within `tests.edn`.
 
+    $ java -jar rdf-validator-standalone.jar --endpoint data.ttl --suite bad_predicate.sparql --variables variables.edn
+
 ## License
 
 Copyright © 2018 Swirrl IT Ltd.