diff --git a/docs/explore-and-author/graph-exploration/building-a-customized-user-interface/.pages b/docs/explore-and-author/graph-exploration/building-a-customized-user-interface/.pages index 93e400f76..1140fccc4 100644 --- a/docs/explore-and-author/graph-exploration/building-a-customized-user-interface/.pages +++ b/docs/explore-and-author/graph-exploration/building-a-customized-user-interface/.pages @@ -4,4 +4,5 @@ nav: - Node Shapes: node-shapes - Property Shapes: property-shapes - Datatypes: datatype-reference + - SPARQL Constraints: sparql-constraints diff --git a/docs/explore-and-author/graph-exploration/building-a-customized-user-interface/sparql-constraints/create-node-shape.png b/docs/explore-and-author/graph-exploration/building-a-customized-user-interface/sparql-constraints/create-node-shape.png new file mode 100644 index 000000000..4c237ce75 Binary files /dev/null and b/docs/explore-and-author/graph-exploration/building-a-customized-user-interface/sparql-constraints/create-node-shape.png differ diff --git a/docs/explore-and-author/graph-exploration/building-a-customized-user-interface/sparql-constraints/empty-shapes-graph.png b/docs/explore-and-author/graph-exploration/building-a-customized-user-interface/sparql-constraints/empty-shapes-graph.png new file mode 100644 index 000000000..53c2ca565 Binary files /dev/null and b/docs/explore-and-author/graph-exploration/building-a-customized-user-interface/sparql-constraints/empty-shapes-graph.png differ diff --git a/docs/explore-and-author/graph-exploration/building-a-customized-user-interface/sparql-constraints/index.md b/docs/explore-and-author/graph-exploration/building-a-customized-user-interface/sparql-constraints/index.md new file mode 100644 index 000000000..a001e3cd2 --- /dev/null +++ b/docs/explore-and-author/graph-exploration/building-a-customized-user-interface/sparql-constraints/index.md @@ -0,0 +1,108 @@ +--- +icon: eccenca/application-queries +tags: + - SPARQL + - Validation + - AdvancedTutorial +--- +# Using SPARQL Constraints for Custom Resource Validation + +## Introduction + +SHACL (Shapes Constraint Language) is a language for validating RDF data based on predefined shapes or constraints. +SHACL SPARQL Constraints are a set of rules defined using SPARQL queries within SHACL shapes to express more complex validation logic that cannot be easily represented by other SHACL constructs. + +Key advantages: + +- **Complex logic**: You can implement any logic supported by SPARQL, such as aggregation, advanced pattern matching, or value ranges. + +- **Reusable queries**: SPARQL constraints allow the reuse of sophisticated query logic across different shapes and data types. + +## Setup + +SPARQL Constraints are resources which need to be managed in a Shape Catalog. +This catalog graph needs to be imported (virtually, with `owl:imports`) into the main CMEM Shapes Catalog. +Similar to property shapes, SPARQL Constraints needed to be linked from a Node Shape in order to select the set of shapes which are used for a given selection of resources. + +## Example + +In our running example, we create a Node Shape for `foaf:Person` resources. +Then we add a SPARQL Constrain shape, which ... + +### Install needed Vocabularies + +Go to the **:eccenca-application-vocabularies: [Vocabulary catalog](../../../vocabulary-catalog)** and install the RDF Schema and FOAF Vocabulary. +Your vocabulary catalog should look like this after installation + +![Vocabulary Catalog with Installed Vocabularies](vocabulary-catalog.png){ class="bordered" } + +### Create a Shape Catalog + +Go to **:eccenca-application-explore: [Knowledge graphs](../../../graph-exploration)** and create a **New Shape Catalog**. +Name the graph e.g. *My Shapes*. +After this step, the browser shows you a nearly empty graph which shows SHACL classes such as **SHACL Node Shape** and **SHACL SPARQL Constraint** in the navigation. + +![Empty Shapes Graph](empty-shapes-graph.png){ class="bordered" } + +### Create a SPARQL Constraint + +Select **SHACL SPARQL Constraint** in the Navigation component, then use the **Create a new "SHACL SPARQL Constraint"** button in the top right corner to create a new resource. +Fill in a label and a SPARQL SELECT Query. + +For our example, we use the following values: + +- Label: `The term eccenca is not allowed in a Person label` +- SPARQL Select: + +``` sparql +PREFIX foaf: +PREFIX rdfs: + +SELECT $this (rdfs:label as ?path) (?label as ?value) +WHERE { + $this a foaf:Person ; + rdfs:label ?label . + FILTER( REGEX(STR(?label), "eccenca" )) +} +``` + +Note that the projection variables of SPARQL Constraint queries need to be named according to the [SHACL Specificaton](https://www.w3.org/TR/shacl/#sparql-constraints-example) (`$this`, `?path`, `?value`). +After you clicked on **Create** you should see your new resource in a list. + +![New SPARQL Constraint](new-sparql-constraint.png){ class="bordered" } + +### Create a Node Shape + +Select **SHACL Node Shape** in the Navigation component, then use the **Create a new "SHACL Node Shape"** button in the top right corner to create a new resource. + +Enter the following values: + +- Name: `Person Shape` +- Target class: Select `Person` from the FOAF vocabulary +- SPARQL Constraints: Select your new constraint from the list (your have to use the **:material-plus-circle-outline: Add data** menu to extend the form with this non-default input field) +- Property Shapes: Create a new property shape with + - Name: `Name` + - Show always: `true` + - Path: `rdfs:label` + - Node Kind: `Literal` + +Before you create your new Node Shape (and new Property Shape) your screen should look like this: + +![Create New Node Shape](create-node-shape.png){ class="bordered" } + +### Validate the Shape + +Now we can validate the shape by creating a Person with a label which contains the term `eccenca`. + +- Go to **:eccenca-application-explore: [Knowledge graphs](../../../graph-exploration)** and create a **New Knowledge Graph**. + - Name: `My Person Data` + - Imports: `foaf: Friend of a Friend vocabulary` +- Select **Person** in the Navigation component, then use the **Create a new "Person"** button in the top right corner to create a new resource. + - Name: `The term eccenca is not allowed` + +The validate the resource with the validation button. You will see a screen like this: + +![Invalid Resource](invalid-resource.png){ class="bordered" } + +When you open the validation report, you will see a error message such as: **The value does not conform to SPARQL constraint**. + diff --git a/docs/explore-and-author/graph-exploration/building-a-customized-user-interface/sparql-constraints/invalid-resource.png b/docs/explore-and-author/graph-exploration/building-a-customized-user-interface/sparql-constraints/invalid-resource.png new file mode 100644 index 000000000..801e42f8c Binary files /dev/null and b/docs/explore-and-author/graph-exploration/building-a-customized-user-interface/sparql-constraints/invalid-resource.png differ diff --git a/docs/explore-and-author/graph-exploration/building-a-customized-user-interface/sparql-constraints/new-sparql-constraint.png b/docs/explore-and-author/graph-exploration/building-a-customized-user-interface/sparql-constraints/new-sparql-constraint.png new file mode 100644 index 000000000..2614055a1 Binary files /dev/null and b/docs/explore-and-author/graph-exploration/building-a-customized-user-interface/sparql-constraints/new-sparql-constraint.png differ diff --git a/docs/explore-and-author/graph-exploration/building-a-customized-user-interface/sparql-constraints/vocabulary-catalog.png b/docs/explore-and-author/graph-exploration/building-a-customized-user-interface/sparql-constraints/vocabulary-catalog.png new file mode 100644 index 000000000..98d53d5be Binary files /dev/null and b/docs/explore-and-author/graph-exploration/building-a-customized-user-interface/sparql-constraints/vocabulary-catalog.png differ