Core should have a Getting Started section

[HolgerKnublauch]

There is currently an example in section 1.4 that could serve as starting point, but even that is probably too formal for beginners.

I think it should be lifted into its own section 2 "Getting Started with SHACL Core" and be expanded to be more comprehensive, explaining concepts in lay terms.

The goal of this is to reduce the need for further tutorials and allow people to better learn SHACL from the spec itself.

[YoucTagh]

@HolgerKnublauch, does something like the following fit what you wanted? If so, I can create a PR.

2. Getting Started with SHACL Core

In this section, we'll walk you through a simple example that introduces the basics of SHACL Core. You'll see how to describe what your data should look like, and how SHACL checks if your data meets that description.

2.1 Simple Example:

Imagine you have a set of people—Alice, Bob, Calvin—and you want to make sure:

1. Every Person has at most one Social Security Number (SSN), and that SSN needs to be a properly formatted text (like 123-45-6789).
2. A Person can work for one or more companies—but those companies must be typed as a ex:Company in your data.
3. No other properties are allowed for a Person, other than the SSN (ex:ssn), the work affiliation (ex:worksFor), and the mandatory typing (rdf:type).

That's what our shape (think "rulebook") will enforce on the data.

---

2.2 Our Sample Data (Data Graph)

Here's the data we want to check:

ex:Alice a ex:Person ;
    ex:ssn "987-65-432A" .          # SSN has a typo or bad format

ex:Bob a ex:Person ;
    ex:ssn "123-45-6789", "124-35-6789" .  # Two SSNs (too many)

ex:Calvin a ex:Person ;
    ex:birthDate "1971-07-07"^^xsd:date ;  # Extra birthDate
    ex:worksFor ex:UntypedCompany .        # Untyped company

What's wrong here?

• Alice has an SSN—but it doesn't match the correct pattern.
• Bob has two SSNs, but we only allow one.
• Calvin works for something called ex:UntypedCompany, but that item isn't labeled as a ex:Company; plus, Calvin has a ex:birthDate, which we don't allow.

---

2.3 Writing the Shape (Shapes Graph)

Here's how we say it clearly using SHACL's Turtle syntax:

ex:PersonShape a sh:NodeShape ;
    sh:targetClass ex:Person ;         # This shape applies to all Persons

    sh:property [
        sh:path ex:ssn ;
        sh:maxCount 1 ;                # At most one SSN
        sh:datatype xsd:string ;               # Must be a string 
        sh:pattern "^\\d{3}-\\d{2}-\\d{4}$" ;  # and look like 123-45-6789
    ] ;

    sh:property [
        sh:path ex:worksFor ;
        sh:nodeKind sh:IRI ;            # Must be an IRI
        sh:class ex:Company ;           # and point to a typed Company
    ] ;

    sh:closed true ;                     # No other properties are allowed
    sh:ignoredProperties ( rdf:type ) .  # except for rdf:type

Let's break that down:

• sh:targetClass ex:Person means “apply this rule to all people.”
• The first sh:property block ensures:
  • SSNs are strings (sh:datatype xsd:string),
  • Only one is allowed (sh:maxCount 1),
  • And it must follow the typical U.S. SSN format (sh:pattern "^\d{3}-\d{2}-\d{4}$").
• The second sh:property block says:
  • If someone has a ex:worksFor property, its value must be an IRI and point to something that's a ex:Company.
• sh:closed true means no properties beyond those listed are allowed (except ones explicitly ignored).
• sh:ignoredProperties ( rdf:type ) lets rdf:type slip through even though it's not in the allowed property list.

---

2.4 Running the Validation (Validation Report)

When we run SHACL validation on our data graph using our shapes graph, the validator checks each Person against the rules we wrote.

In plain English, here’s what it finds:

• Alice: SSN doesn’t match the expected pattern (987-65-432A has a letter where a digit should be).
• Bob: Has more than one SSN (two values found, but sh:maxCount says only one is allowed).
• Calvin:
  • Works for something (ex:UntypedCompany) that isn’t declared as a ex:Company.
  • Has an extra property ex:birthDate that isn’t allowed by the shape.

Example Validation Report in Turtle

Here’s what a SHACL validation report for this example might look like (simplified for readability):

[	a sh:ValidationReport ;
	sh:conforms false ;
	sh:result
	[	a sh:ValidationResult ;
		sh:resultSeverity sh:Violation ;
		sh:focusNode ex:Alice ;
		sh:resultPath ex:ssn ;
		sh:value "987-65-432A" ;
		sh:sourceConstraintComponent sh:PatternConstraintComponent ;
		sh:sourceShape _:b1 ; # ... blank node _:b1 on ex:ssn above ...
    sh:resultMessage "Value does not match pattern "^\d{3}-\d{2}-\d{4}$"" ;
	] ,
	[	a sh:ValidationResult ;
		sh:resultSeverity sh:Violation ;
		sh:focusNode ex:Bob ;
		sh:resultPath ex:ssn ;
		sh:sourceConstraintComponent sh:MaxCountConstraintComponent ;
		sh:sourceShape _:b1 ; # ... blank node _:b1 on ex:ssn above ...
    sh:resultMessage "More than 1 values" ;
	] ,
	[	a sh:ValidationResult ;
		sh:resultSeverity sh:Violation ;
		sh:focusNode ex:Calvin ;
		sh:resultPath ex:worksFor ;
		sh:value ex:UntypedCompany ;
		sh:sourceConstraintComponent sh:ClassConstraintComponent ;
		sh:sourceShape _:b2 ; # ... blank node _:b2 on ex:worksFor above ...
    sh:resultMessage "Value does not have class ex:Company" ;
	] ,
	[	a sh:ValidationResult ;
		sh:resultSeverity sh:Violation ;
		sh:focusNode ex:Calvin ;
		sh:resultPath ex:birthDate ;
		sh:value "1971-07-07"^^xsd:date ;
		sh:sourceConstraintComponent sh:ClosedConstraintComponent ;
		sh:sourceShape sh:PersonShape ;
    sh:resultMessage "Predicate is not allowed (closed shape)" ;
	] 
] .

How to read the report:

• sh:ValidationReport is the overall report, with sh:conforms false meaning at least one rule failed.
• Each sh:ValidationResult is one problem found:
  • sh:resultSeverity — tells you how serious the problem is. In this example, all issues are sh:Violation (the highest and default severity).
  • sh:focusNode — the data node that failed.
  • sh:resultPath — the property involved.
  • sh:value — the actual value that triggered the failure.
  • sh:sourceConstraintComponent — which kind of rule was broken (max count, pattern, class, etc.).
  • sh:sourceShape — the shape that defined the rule.
  • sh:resultMessage — a human-readable explanation.

[HolgerKnublauch]

This is a very good start, so if you can, please create a branch and we can iterator on that. I would have a few change suggestions, e.g. I think we should start using named URIs for property shapes instead of blank nodes, because people will copy and paste this a lot.

[TallTed]

I like this. I especially like the alignment of the comments in the sample data. I encourage similar alignment of subjects, predicates, and objects, wherever such whitespace is permitted. In my exprience, doing this aids and speeds comprehension enormously, even for readers who are accustomed to reading similar data with little-to-no optional whitespace.