shacl2cypher
A short book

Shapes for Property Graphs

SHACL, taught from the ground up for people who work with Neo4j, LadybugDB and other labeled property graphs. Nine short chapters, one running example, and shapes you can compile and run at every step.

Start reading Example files

Who this is for

You know what a node, a label, a property and a relationship are. You may never have written RDF. You want the rules your graph must follow written down in one place, in a standard language, and checked automatically rather than rediscovered in production.

SHACL was designed for RDF, so most tutorials start with triples and IRIs. This one starts with your graph. Every idea is shown twice: as SHACL, and as what it means for labels, properties and relationships.

The running example

Every chapter uses one small HR graph:

(:Person {id, name, email, age, status, skills: [..]})
   -[:WORKS_FOR]->(:Company {id, name, markets: [..]})-[:LOCATED_IN]->(:City)
(:Person)-[:MANAGES]->(:Person)
(:Person)-[:KNOWS {since}]->(:Person)
(:Person)-[:LIVES_AT]->(:Address {street, zip})
(:Team)-[:MEMBER]->(:Person)

All shapes live in the ex: namespace, http://example.org/hr#.

How to follow along

Install shacl2cypher (see Get started) and clone the repository. Each chapter's shapes are in doc/examples/book/, and every one of them compiles. To see the Cypher a chapter's shapes turn into:

shacl2cypher compile doc/examples/book/02-first-shape.ttl --dialect neo4j --node-key id -o out/
less out/queries.cypher

To run them against a database, swap compile for validate and add --connect bolt://… or --ladybug file.lbug.

Chapters

Chapter 1
Why shapes for a property graph
What SHACL is, why a standard from the RDF world fits property graphs, and the handful of terms the rest of the book uses.
Chapter 2
Turtle and your first shape
Enough Turtle syntax to read and write shapes, a first node shape, and the queries it compiles into.
Chapter 3
Targets and focus nodes
Which nodes and relationships a shape applies to: class targets, hierarchies, subjects-of and relationship targets.
Chapter 4
Property shapes and cardinality
Required, optional, single- and multi-valued properties, and how nulls, lists and absent values are counted.
Chapter 5
Constraining values
Datatypes, ranges, lengths, patterns and allowed values, and why a wrong type is always a violation.
Chapter 6
Relationships and paths
Endpoint classes, incoming relationships, multi-hop sequences, alternatives and transitive paths.
Chapter 7
Comparing properties and closing shapes
Rules across two properties, such as start before end, and shapes that forbid anything undeclared.
Chapter 8
Composing shapes
Reusable shapes, and / or / not / exactly-one, and qualified counts such as "at least one manager".
Chapter 9
Severity, messages and CI
Warnings versus violations, readable messages, stable rule names, and a validation gate in your pipeline.