feat: Implement sequence processing improvements for SHACL Node Expressions (Issue #484)

[simonstey]

This pull request implements comprehensive changes to address Issue #484 regarding sequence processing naming inconsistencies in SHACL Node Expressions. The changes align the vocabulary and documentation with the sequence-based nature of node expression processing while maintaining backward compatibility through deprecation notices.

Problem Statement

SHACL Node Expressions are fundamentally sequence-based but were using set-style operation names, creating confusion:

• Operations like union and minus suggested set semantics despite working on ordered sequences
• The generic path property conflicted conceptually with constraint sh:path
• Missing advanced sequence operations limited processing capabilities

Solution

1. Vocabulary Renaming for Sequence Semantics

Renamed Operations:

• shnex:union → shnex:join - Emphasizes sequence concatenation with order preservation
• shnex:minus → shnex:remove - Clearer operation name for sequence subtraction
• shnex:path → shnex:pathValues - Distinguishes from constraint sh:path (needs to align with Rename shnex:path to shnex:pathValues and change its shnex:nodes to shnex:focusNode #514 )

Deprecation Strategy:

• Updated shacl.ttl with deprecation notices for sh:union and sh:minus
• Maintained backward compatibility while guiding migration to new terms

2. Advanced Sequence Operations

New Operations Added:

• shnex:flatMap - Applies expression to each input node and flattens results
• shnex:findFirst - Returns first node conforming to a given shape
• shnex:matchAll - Returns true if all nodes conform to a given shape

Files Modified

Vocabulary Files

• shacl12-vocabularies/shnex.ttl

  • Added complete RDF definitions for FlatMap, FindFirst, and MatchAll expressions
  • Updated existing definitions with sequence-appropriate naming
  • Enhanced property comments for clarity

• shacl12-vocabularies/shacl.ttl

  • Added deprecation notices for sh:union and sh:minus
  • Clear migration guidance to new sequence-based terms

Documentation

• shacl12-node-expr/index.html
  • Renamed sections: UnionExpression → JoinExpression, MinusExpression → RemoveExpression

New Advanced Operations:

# Find first senior employee
sh:values [
    shnex:findFirst [
        shnex:nodes [ shnex:pathValues ex:employee ] ;
        shnex:findFirst ex:SeniorEmployeeShape ;
    ] ;
] .

# Check if all employees are active
sh:values [
    shnex:matchAll [
        shnex:nodes [ shnex:pathValues ex:employee ] ;
        shnex:matchAll ex:ActiveEmployeeShape ;
    ] ;
] .

---

Closes #484

• See this document rendered online here

[TallTed]

Small stuff

[TallTed]

Suggested change

	<li><code>sh:path</code> is used in <strong>property shapes</strong> to specify which property path should be constrained during validation. It defines what property or path the shape's constraints apply to.</li>
	<li><code>sh:path</code> is used in <strong>property shapes</strong> to specify the property path that will be constrained during validation. It defines the property or path to which the shape's constraints apply.</li>

[TallTed]

Suggested change

	<li><code>shnex:pathValues</code> is used in <strong>node expressions</strong> to specify which property path should be traversed to generate a sequence of values. It produces the actual values found by following the path.</li>
	<li><code>shnex:pathValues</code> is used in <strong>node expressions</strong> to specify the property path that will be traversed to generate a sequence of values. It produces the actual values found by following the path.</li>

[TallTed]

Suggested change

	Nodes must be equal using <a>term equality</a>, i.e. <code>"01"^^xsd:integer</code> is distinct from <code>"1"^^xsd:integer</code>.
	Nodes must be equal using <a>term equality</a>, i.e., <code>"01"^^xsd:integer</code> is distinct from <code>"1"^^xsd:integer</code>.