feat: Add migration guide and patterns for transitioning from SHACL-AF to SHACL 1.2

[simonstey]

• Introduced a comprehensive migration guide detailing architectural differences, vocabulary mapping, syntax migration, and new capabilities in SHACL 1.2.
• Created a migration patterns cookbook with specific examples for rewriting SHACL-AF rules into SHACL 1.2, covering various common patterns and their transformations.

• See this document rendered online here

[afs]

Just checking - this PR has two MD files :

migration-guide.md

migration-patterns.md

and does not itself change index.html?

[afs]

Something else that has been suggested is adding sh:SHACLRule so that an updated SHACL-AF can execute one rule, with $this being provided to a rule execution.

sh:rule [ 
   rdf:type sh:SHACLRule ;
   srl:rule "...."
]

[afs]

What about SPARQL NOT EXISTS?

[TallTed]

see line 327?

[afs]

Relates to issue #776

[afs]

shnex: and sparql:

[TallTed]

This comment is unclear to me. I cannot say whether @simonstey understands it better.

[afs]

BIND -> SET

[TallTed]

i.e.,

Suggested change

	BIND (?width * ?height AS ?area) .
	SET (?area := ?width * ?height ) .

?

[simonstey]

yes, but not for the "old" SHACL-AF rules -->

have to change it here though:

**SHACL 1.2 SRL:**
```
PREFIX ex: <http://example.com/ns#>

RULE { ?this ex:area ?area }
WHERE {
    ?this a ex:Rectangle .
    ?this ex:width ?width .
    ?this ex:height ?height .
    SET (?area := ?width * ?height ) .
}
```

[afs]

Excellent!

Do you think this should be a WG NOTE, or https://github.com/w3c/shacl-resources, or some other place?

[TallTed]

Given all the BIND -> SET comments elsewhere, shouldn't the same be applied here?

[simonstey]

yes, you are totally right

[afs]

@simonstey Would it be possible to update this PR so that it only has the markdown files?

[simonstey]

@simonstey Would it be possible to update this PR so that it only has the markdown files?

done

---

fwiw, since I had to look up on how to do this without too much hassle myself, I might as well share it->

move branch base onto latest gh-pages ->

git reset --hard origin/gh-pages

pull the two files from the old tip ->

git checkout 8bfb87f3 -- shacl12-rules/migration-guide.md shacl12-rules/migration-patterns.md

commit and push ->

git commit -m "feat: Add SHACL-AF to SHACL 1.2 migration guide and patterns"
git push --force-with-lease

[afs]

git rebase should have worked.

[TallTed]

Suggested change

	dependency cycle contains a closed dependency; if it does, the spec leaves the
	outcome undefined. This guarantees a single well-defined, finite outcome.
	dependency cycle contain a closed dependency; if any do, this specification
	leaves the outcome undefined. This guarantees a single, well-defined, finite
	outcome.

[TallTed]

Suggested change

	an assignment, or a blank-node-producing head is what introduces a hard stratum
	boundary.
	an assignment, or a blank-node-producing head introduces a hard stratum boundary.

[TallTed]

Suggested change

	| — | `srl:assignValue` | New; the value/expression of an `srl:assign` |
	| — | `srl:assignValue` | New; the value or expression of an `srl:assign` |

[TallTed]

Suggested change

	are used both in `srl:head` (triple templates) and in `srl:body`/`srl:data`
	(triple patterns and data triples), not only for the SHACL-AF `sh:subject`/etc.
	mapping shown above.
	are used in `srl:head` (triple templates) as well as `srl:body` and `srl:data`
	(triple patterns and data triples), not only for the SHACL-AF `sh:subject`, etc.,
	mappings shown above.

[TallTed]

Suggested change

	- The assignment makes this rule a **run-once rule** (it has an `srl:assign`)
	- The assignment (`srl:assign`) makes this a **run-once rule**

[TallTed]

Shouldn't this (and similar) reference be made a live link to SHACL 1.2 Node Expressions, if not directly to the definition of the function definition mechanism therein?

Suggested change

	definition mechanism is defined in SHACL 1.2 Node Expressions (separate spec),
	not in the rules spec itself.
	definition mechanism is defined in SHACL 1.2 Node Expressions (a separate
	specification), not in the Rules specification itself.

[TallTed]

Even in an unordered list, there is often a logic to their ordering and their wording. I believe these adjustments make this list more logical and more likely to be followed correctly.

Suggested change

	- Within a stratum, evaluate **run-once rules** (those with assignments or
	blank-node-producing heads) exactly once, then iterate the **general rules**
	to a fixed point
	- Evaluate each stratum completely and in order before proceeding to the next
	- Evaluate each stratum completely and in order before proceeding to the next
	- Within each stratum, evaluate all **run-once rules** (those with assignments
	or blank-node-producing heads) exactly once, then iterate the **general rules**
	to a fixed point

[TallTed]

Suggested change

	and is undefined. Implementations need semi-naive evaluation or equivalent to
	and is undefined. Implementations need semi-naive evaluation or an equivalent to

[TallTed]

Suggested change

	- A *closed* dependency (negation, assignment, or a blank node in the head) is
	what forces the depended-on rule into a strictly earlier stratum. Ordinary
	positive chaining like this does not.
	- A *closed* dependency (negation, assignment, or a blank node in the head)
	forces a depended-on rule into a strictly earlier stratum. Ordinary positive
	chaining like this does not.