From f67c4ddf2694c1bbe738ab5d5379902eba450187 Mon Sep 17 00:00:00 2001
From: tpluscode <tpluscode@users.noreply.github.com>
Date: Sun, 15 Sep 2024 22:55:47 +0200
Subject: [PATCH] docs

---
 README.md | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/README.md b/README.md
index 8bfa108..459d524 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,36 @@
 # SHACL-test
 
+Runs SHACL shapes against a set of positive and negative test cases (data graphs).
+
+Positive test cases are a simple fail/pass.
+Negative test cases are expected to fail and the validation report is compared against the
+expectation using [approvals](https://npm.im/approvals).
+
+In case of failures, a [SHACL Playground](https://shacl-playground.zazuko.com) 
+link is provided for further investigation.
+
+## Usage
+
+```sh
+npx shacl-test \
+  --shapes=${SHAPES} \
+  --valid-cases="${VALID_CASES_GLOB}" \
+  --invalid-cases="${INVALID_CASES_GLOB}" \
+  --approve \
+  --debug \
+  --prefixes=${PREFIXES}
+```
+
+Only the `--shapes` option is required. The rest are optional.
+
+`--valid-cases` and `--invalid-cases` are globs that match the test cases. 
+Make sure to put them in quotes to avoid shell expansion.
+
+`--approve` will approve the validation reports for the negative test cases instead of failing.
+
+`--debug` will print the validation report for each test case.
+
+`--prefixes` is a comma-separated list of prefix declarations to be used in the SHACL shapes.
+For example, `--prefixes=schema,qudt,cube=https://cube.link/`, will declare the prefixes
+`schema`, `qudt` and `cube` with the respective URIs. In the case of `schema` and `qudt`, their
+URIs are taken from the list provided by the [`@zazuko/prefixes`](https://github.com/zazuko/rdf-vocabularies/blob/master/packages/prefixes/prefixes.ts) package (and, by extension, the [Zazuko prefix server](https://prefix.zazuko.com)).