Rewrite the SHACL Rules introduction, incorporating all the topics we have discussed so far and that we want the spec to cover #722

liviorobaldo · 2026-01-14T14:40:34Z

See this document rendered online here

liviorobaldo · 2026-01-14T14:44:28Z

My first PR ☺️

Some comments:

I wrote “for deriving new content” rather than “for deriving new RDF triples” because rules can also add new RDF resources and RDF literals.
I removed “beyond validation” because, as discussed in the last PR for SHACL Core, we should avoid over-emphasising validation and instead present it as one task among others. The same applies to the phrase “While SHACL Core focuses on constraint validation”.
Regarding “SHACL Rules only add content to the knowledge graph”, rules do not remove content. See the discussion here: allowing rules to remove content, although potentially useful, could introduce several issues, particularly with respect to guaranteeing termination of rule execution. For this reason, I think we should avoid this.
For the discussion on infer() and query(), see discussion here.
Concerning the statement “Well-formedness conditions in SHACL Rules prevent infinite loops”, see discussion here . However, I am not sure whether stratification also plays a role in preventing infinite loops; if so, we could consider stating this explicitly in the abstract as well.

afs · 2026-01-14T19:24:13Z

“Well-formedness conditions in SHACL Rules prevent infinite loops"

The well-formedness conditions are not about loops. They are "set variable before use" where use is needing the variable setting - a filter or a head - or for stopping re-assignment.
https://raw.githack.com/w3c/data-shapes/SHACL-rules-introduction/shacl12-rules/index.html#wellformed

Infinite loops: There is an open issue here related to term introduction where stratification may be part of the solution.

liviorobaldo · 2026-01-15T15:05:55Z

Hi Andy, okay. My understanding is that this should still be implemented as part of the Rule Set Evaluation (§5). Perhaps the abstract should not go into these details, but I think it is important to at least state that correct implementations of SHACL Rules prevent infinite loops and non-deterministic behaviour.

By the way, I have just noticed that what I called the "initial knowledge graph" in the current version of the abstract is referred to as the "base graph" in §5. I am going to update index.html in this branch to keep the terminology consistent with §5.

afs · 2026-01-20T14:36:42Z

Perhaps the abstract should not go into these details, but I think it is important to at least state that correct implementations of SHACL Rules prevent infinite loops and non-deterministic behaviour.

Introduction - the abstract is a more general and shorter section in the standard W3C spec template.

I think the introduction is a scene-setting general outline. It is for the first-time reader. It does not have to have every detail.

The rest of section 2, the description/tutorial, can cover items at a deeper level. Mentioning deep details in the introduction does not do the details justice nor is the first-time reader yet in a position to pick up on these details.

afs · 2026-01-20T14:01:18Z

shacl12-rules/index.html

+        These rules extend SHACL's capabilities by enabling reasoning and data enrichment. The document complements other SHACL 1.2 specifications, 
+        such as SHACL Core, by defining the syntax and semantics of rule-based inference. The SHACL Rules specification provides a standardized way 
+        to express and evaluate rules that generate new data.</p>
+      <p>SHACL Rules only <i>add</i> content to the knowledge graph to which they are applied, referred to as the 'base graph', producing a new graph 


Rules produce an inference graph - they don't add to the input graph. You say this later but this text contradicts that.

A user may choose to add the inferences but that is not a requirement of SHACL Rules.

I think it is important to make clear that the inferred graph includes all triples from the base graph, i.e., that these triples are preserved and not removed (see issue #728).

Other readers might wonder whether SHACL Rules only add triples to the base graph or whether they can also remove them.

It can not remove them.

shacl12-rules/index.html

afs · 2026-01-20T14:05:37Z

shacl12-rules/index.html

+        called the 'inferred graph'. In particular, rules may add new RDF triples but they may also <i>create</i> and add new RDF resources and literals 
+        that were not present in the base graph. While most rule operators are monotonic, the grammar also includes two non-monotonic operators: 


I don't think an introduction needs to say "monotonic" which has a very precise meaning.

I think we should instead mention monotonic vs non-monotonic operators in the Introduction. The intended audience for SHACL Rules consists of people with a basic background in logic, for whom the term "monotone" is already part of the standard vocabulary. In other words, this term is not "too technical" for them.

Readers approaching this document will naturally start wondering how SHACL Rules differ from OWL, SWRL, N3, RuleML, and similar formalisms. In light of this, in my view readers should be informed from the outset that SHACL Rules allow for NAF, aggregates, and the creation of new RDF resources and literals, while controlling their effects, e.g., through stratification.

What do you mean by "monotonic" in this context?

Readers approaching this document will naturally start wondering how SHACL Rules differ from OWL, SWRL, N3, RuleML, and similar formalisms.

Would you care to draft a comparison?

This does not need go in the spec itself (they become out of date or incomplete).

It is good material for the "What's new in SHACL 1.2" document.

What do you mean by "monotonic" in this context?

By (non-)monotonic, I mean whether previously derived conclusions can be retracted. What is retracted may depend on the execution order of the rules. This corresponds to the standard and well-known definition. A canonical example is:

Bird(x) → CanFly(x)
Penguin(x) → ¬CanFly(x)
Bird(x) → Penguin(x)

If Tweety is a bird, under one execution order it may first be inferred that Tweety can fly and only later that it cannot (so the first conclusion is retracted); under another execution order, the opposite occurs.

That said, this notion is quite standard and should be familiar to anyone with a background in logic... including you. So perhaps I have misunderstood your question?

My point is that, since the term "monotonic" is well known to the potential readership of SHACL rules, I do not consider it overly specific or too technical for the introduction. This was in response to your initial claim:

I don't think an introduction needs to say "monotonic", which has a very precise meaning.

To answer your question:

Would you care to draft a comparison?

Yes, I think comparisons with existing solutions are of clear interest. We discussed this ourselves during the TF meeting, for example comparisons with N3. Indeed, the very first question a colleague of mine asked was what is new in SHACL rules compared to RuleML.

I fully agree that these discussions should be incorporated into the "What’s New in SHACL 1.2" document. However, I still think it is useful to mention (non-)monotonicity and stratification in the introduction, as these refer to general categories and can help clarify the direction of our work from the outset. The "What’s New in SHACL 1.2" document can then provide the detailed comparisons.

afs · 2026-01-20T14:10:23Z

shacl12-rules/index.html

+        <i>negation as failure</i> and <i>aggregates</i> (e.g., `SUM`, `COUNT`). Negation as failure allows testing whether certain triples are absent 
+        from the base graph, whereas aggregates generate new literals that can be subsequently added to the inferred graph.</p>


People are reading the working draft. This is good!

There is still significant work time needed just to get the specification to one that covers negation, which IMO is more important.

While it is unfortunate not to go further, a worse outcome is to rush and put something in which turns out to be wrong or not the bast design. There is opportunity to add features later; removing features is very painful for the spec and for users.

So I'm uncomfortable with putting anything about aggregation in the introduction at this time.

Although I agree that NAF is more important than aggregates (in the sense that there are many more use cases requiring NAF than those requiring aggregates) I still think that both are necessary.

I was planning to open a new PR on aggregates, including them in the grammar and describing them in the relevant section (they are currently mentioned in §3). Let’s discuss negation and aggregates further in the forthcoming TF meetings.

I still think that both are necessary.

Why? One specualtive use case is not enough to justify choosing an approach.

We need to scope the possibilities (there are several) and survey the state of the art. Until that ground work is done, any changes are at significant risk of being wrong and have to be removed.

For a standard, a document that should be stable for years, removing or materially changing a feature is a massive problem.

New features, as they are proven, can come along later if they are also new syntax as this would be.

Do the core feature well - and that is a lot more work than just paragraphs in a document.

Ok, I totally agree that we need to scope the possibilities. Let’s discuss this at the TF meetings. My understanding from the current version of the spec was that NAF, aggregates, and the creation of new RDF resources and literals were included in the scope.

shacl12-rules/index.html

afs · 2026-01-20T14:13:03Z

shacl12-rules/index.html

+        that were not present in the base graph. While most rule operators are monotonic, the grammar also includes two non-monotonic operators: 
+        <i>negation as failure</i> and <i>aggregates</i> (e.g., `SUM`, `COUNT`). Negation as failure allows testing whether certain triples are absent 
+        from the base graph, whereas aggregates generate new literals that can be subsequently added to the inferred graph.</p>
+      <p>Well-formedness conditions in SHACL Rules prevent infinite loops that could arise from the creation of new RDF resources and literals, while 


This first part of this paragraph is getting into more detail than an introduction needs to.

To me, an introduction sets the scene - the common use. Error conditions etc are details for later.

Fair enough. Instead of explicitly mentioning well-formedness conditions, stratification, and similar technical details, we could just state more generally that: "implementations are expected to prevent infinite loops arising from the creation of new RDF resources and literals, as well as non-deterministic behaviour introduced by non-monotonic operators (see §3)."

However, as I mentioned above, I believe it is important to make clear from the outset that non-monotonic operators are part of the design and that their potential "collateral effects" have been considered.

implementations are expected to prevent infinite loops arising

If you leave it to implementations, there will be inconsistency on the web.

Ok, that's also a good point. Let’s then avoid to say “are expected”. What do you (and everyone else) think of the following instead:

"The evaluation of the rules prevents infinite loops arising from the creation of new RDF resources and literals, as well as non-deterministic behaviour introduced by non-monotonic operators (see §5)."

shacl12-rules/index.html

afs · 2026-01-20T14:18:27Z

shacl12-rules/index.html

+        from the base graph, whereas aggregates generate new literals that can be subsequently added to the inferred graph.</p>
+      <p>Well-formedness conditions in SHACL Rules prevent infinite loops that could arise from the creation of new RDF resources and literals, while 
+        non-deterministic behavior introduced by non-monotonic operators is avoided through the well-known technique of <i>stratification</i>, which must
+          be applied within implementations. Implementations of the rules must also support two operations: <i>infer()</i>, which applies rules using 


Suggested change

be applied within implementations. Implementations of the rules must also support two operations: infer(), which applies rules using

be applied within implementations.



Implementations of the rules provide two possible operations: infer(), which applies rules using

The "Implementations .. provide" text is important for an introduction - move it up.

Avoid, where possible, may/should/must language because, even if written as plain text, they suggest RFC 2119 meaning. Sometimes it is natural to use the words (lowercase) but if possible, reword.

afs · 2026-01-20T14:20:08Z

shacl12-rules/index.html

+        non-deterministic behavior introduced by non-monotonic operators is avoided through the well-known technique of <i>stratification</i>, which must
+          be applied within implementations. Implementations of the rules must also support two operations: <i>infer()</i>, which applies rules using 
+        forward chaining, so that for all rules whose bodies match the base graph, the content in their heads is added to the inferred graph, 
+        and <i>query()</i>, which applies rules using backward chaining, determining whether a given goal pattern can be inferred from 


I don't think the introduction needs to mention "backward-chaining"/"forward-chaining". They are implementation strategies.

Text later can get into the details and say either can be used - and the spec defines outcomes using one possible forward-chaining approach.

I agree. Unless anyone else disagrees (let’s wait a couple of days for comments), I’ll update the text accordingly.

liviorobaldo · 2026-01-20T14:40:59Z

Yes, sorry, here we are dealing with the "introduction", not the "abstract". Every time I wrote "abstract" above I meant "introduction". Totally agree about "I think the introduction is a scene-setting general outline. It is for the first-time reader". I will have a look at all your revisions asap.

Co-authored-by: Andy Seaborne <andy@apache.org>

recalcitrantsupplant · 2026-01-26T12:15:45Z

As a general comment I also think there is too much detail for an introduction, but the content could go elsewhere. Paraphrasing the addition around base/inference graphs we could add something like "SHACL Rules are evaluated over a base graph to produce an inference graph."

Update index.html

4e8f22b

Update index.html

c3e7eb7

liviorobaldo added 2 commits January 15, 2026 14:42

Update index.html

d83d4f5

Update index.html

68a7b69

liviorobaldo added 2 commits January 15, 2026 15:08

Update index.html

33e8822

Update index.html

50eb59e

liviorobaldo mentioned this pull request Jan 20, 2026

Does output include base graph triples #728

Closed

afs requested review from afs, osavkovic, recalcitrantsupplant, robert-david and simonstey January 20, 2026 14:34

afs requested changes Jan 20, 2026

View reviewed changes

liviorobaldo and others added 3 commits January 21, 2026 11:25

Apply suggestion from @afs

32d1c2a

Co-authored-by: Andy Seaborne <andy@apache.org>

Apply suggestion from @afs

6967546

Co-authored-by: Andy Seaborne <andy@apache.org>

Apply suggestion from @afs

6efee28

Co-authored-by: Andy Seaborne <andy@apache.org>

afs added the Rules For SHACL 1.2 Rules spec. label Jan 24, 2026

Update index.html

c7f0fa1

		called the 'inferred graph'. In particular, rules may add new RDF triples but they may also <i>create</i> and add new RDF resources and literals
		that were not present in the base graph. While most rule operators are monotonic, the grammar also includes two non-monotonic operators:

		<i>negation as failure</i> and <i>aggregates</i> (e.g., `SUM`, `COUNT`). Negation as failure allows testing whether certain triples are absent
		from the base graph, whereas aggregates generate new literals that can be subsequently added to the inferred graph.</p>

Rewrite the SHACL Rules introduction, incorporating all the topics we have discussed so far and that we want the spec to cover #722

Are you sure you want to change the base?

Rewrite the SHACL Rules introduction, incorporating all the topics we have discussed so far and that we want the spec to cover #722

Uh oh!

Conversation

liviorobaldo commented Jan 14, 2026

Uh oh!

liviorobaldo commented Jan 14, 2026

Uh oh!

afs commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

liviorobaldo commented Jan 15, 2026

Uh oh!

afs commented Jan 20, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

liviorobaldo Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

liviorobaldo commented Jan 20, 2026

Uh oh!

recalcitrantsupplant commented Jan 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

afs commented Jan 14, 2026 •

edited

Loading

liviorobaldo Jan 26, 2026 •

edited

Loading