TechArticle

SHACL

Infobox

description
Shapes Constraint Language for validating RDF graphs.

The Shapes Constraint Language (SHACL) is a W3C recommendation for validating RDF graphs against a set of conditions. These conditions are provided as shapes and other constructs expressed in the form of an RDF graph itself.

In this wiki, SHACL is used to enforce structure via the wiki validation engine.

Defining custom SHACL shapes (validation)

SHACL shapes load from the wiki graph. Add a dedicated shapes/ tree to Wiki Configuration wiki.input so shape documents stay separate from prose pages:

wiki:
  input:
    - wiki
    - shapes

Markdown and data files under shapes/ compile into the same wiki graph as wiki articles; wiki check extracts sh:NodeShape triples and validates every document against them with rdf-validate-shacl.

The validator applies rdfs:subClassOf when it resolves sh:targetClass, so a shape on a class also targets instances of its subclasses. It does not run a full RDFS inference pass first, which the pre-0.2.0 Python engine (PySHACL with inference="rdfs") did. A constraint whose meaning depends on inferred triples, such as sh:class over an inferred type or sh:path over an rdfs:subPropertyOf, only sees triples the wiki states explicitly. This repository keeps shapes alongside articles under wiki/ instead (Software Application Shape); both layouts work.

To constrain a class (for example schema:Project), create shapes/Project_Shape.md using a Style Guide Wikipedia-style filename and frontmatter like Software Application Shape:

---
type: sh:NodeShape
rdfs:label: Project Shape
sh:targetClass: schema:Project
sh:property:
  - sh:path: schema:name
    sh:minCount: 1
    sh:maxCount: 1
    sh:datatype: xsd:string
    sh:message: Project must have exactly one name string.
  - sh:path: schema:startDate
    sh:minCount: 1
    sh:maxCount: 1
    sh:datatype: xsd:date
    sh:message: Project must have a startDate in YYYY-MM-DD format.
---

When you run wiki check, any page with type: Project is automatically validated against these constraints.

Lists and property paths

A YAML list in frontmatter usually means one triple per item. The SHACL parameters whose value the SHACL specification defines as a list compile to an RDF list instead, at any depth: sh:in, sh:languageIn, sh:ignoredProperties, sh:and, sh:or, sh:xone, and sh:alternativePath. Under sh:path (and sh:inversePath, sh:zeroOrMorePath, sh:oneOrMorePath, sh:zeroOrOnePath), a list of two or more items is a sequence path, and a one-item list is the same as the bare item:

---
type: sh:NodeShape
sh:targetClass: schema:Project
sh:property:
  - sh:path: schema:status
    sh:in:
      - schema:ActiveActionStatus
      - schema:CompletedActionStatus
  - sh:path: [schema:author, schema:name]
    sh:minCount: 1
  - sh:path:
      sh:alternativePath: [schema:alternateName, [schema:author, schema:name]]
    sh:minCount: 1
---

Here the second property checks the author's name (a sequence path), and the third accepts either an alternateName or an author's name.

Shape page checks

wiki check lints every shape page before it validates anything with it (check.shape_definition, default error). It follows the SHACL Core rules for well-formed shapes:

  • Vocabulary. Every sh: key must be a property the SHACL vocabulary defines, and every sh: type or value must be one of its terms. sh:patern or type: sh:NodeShap fails instead of silently doing nothing.
  • Property shapes need exactly one sh:path (SHACL §2.3), whether they are a page typed sh:PropertyShape or an item under sh:property. A node shape, including a value of sh:node, cannot have one (§2.2, §4.7.1).
  • Paths must be well-formed (§2.3.1): an IRI, a list of paths (a sequence), or a mapping with exactly one of sh:inversePath, sh:alternativePath, sh:zeroOrMorePath, sh:oneOrMorePath, or sh:zeroOrOnePath. sh:alternativePath needs at least two paths. A CURIE whose prefix the wiki does not declare compiles to a plain string, not an IRI, so it is rejected.
  • IRI-valued parameters (sh:targetClass, sh:targetSubjectsOf, sh:targetObjectsOf, sh:class, sh:datatype, sh:equals, sh:disjoint, sh:lessThan, sh:lessThanOrEquals, and each member of sh:ignoredProperties) must be IRIs, and sh:nodeKind must be one of its six kinds (§4.1.3).

While any of these fail as errors, wiki check skips SHACL validation and says so with a shacl_skipped warning: a broken shape makes the SHACL verdict meaningless, so fix the shapes first.

Separately, check.shape_unused (default warning) flags a node shape page that validates nothing: it has no target, is not also a class, and no other shape reaches it through sh:node, sh:property, sh:qualifiedValueShape, sh:not, sh:and, sh:or, or sh:xone (§2.1). SHACL allows such a shape, so this is a warning rather than an error; set it to error to enforce it or off to silence it.

Shapes written in RDF get the same checks over their triples: fenced turtle blocks, and RDF data files under wiki.input (.ttl, .trig, .nt, .nq, .rdf, .xml, .jsonld). With no frontmatter key to point at, a finding names the source and the shape instead: an IRI, or the triples that reach a blank node from one, for example In shapes/Person.ttl: ex:PersonShape sh:property [ ] sh:minCont: … or In Person_Shape (turtle block 1): …. A prefix declared only inside the Turtle prints as a full IRI. Shapes from installed sources are not linted; their own wiki's wiki check covers them.

JSON Schema (optional)

On the same shape document, add wazoo:jsonSchema beside sh:targetClass to validate frontmatter with JSON Schema in parallel with SHACL:

---
type: sh:NodeShape
sh:targetClass: schema:Project
wazoo:jsonSchema: schemas/project.json
sh:property:
  - sh:path: schema:name
    sh:minCount: 1
---

wiki init scaffolds an empty wiki/ folder — add your own shape documents (e.g. a sh:NodeShape frontmatter page for your domain) when you need SHACL validation. Optionally bind JSON Schema on shape documents with wazoo:jsonSchema beside sh:targetClass, or append per-page schemas with their own wazoo:jsonSchema key (string or list). Shape binding documents are not validated as instances — only their schema refs are checked for loadability.

See Tech Article Shape in this wiki for a dogfooded example.

Pure .ttl or .trig files in shapes/ also load when that directory is listed in wiki.input; markdown frontmatter is the default authoring style in this wiki.

References

Backlinks