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

[liviorobaldo]

• See this document rendered online here

[liviorobaldo]

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]

“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]

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]

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]

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.

[liviorobaldo]

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.

[afs]

It can not remove them.

[afs]

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

[liviorobaldo]

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.

[afs]

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.

[liviorobaldo]

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.

[afs]

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.

[liviorobaldo]

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.

[afs]

Suggested change

	be applied within implementations. Implementations of the rules must also support two operations: <i>infer()</i>, which applies rules using
	be applied within implementations.
	</p>
	<p>Implementations of the rules provide two possible operations: <i>infer()</i>, 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]

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.

[liviorobaldo]

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

[liviorobaldo]

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.