First draft of report extension for infos on matched nodes by robert-david · Pull Request #1239 · w3c/data-shapes

robert-david · 2026-09-08T14:43:42Z

This pull request provides a first draft to extend the validation report with infos on targeted nodes.
The extensions are designed to not break backwards compatibility with SHACL 1.0.
It provides the following extensions:

Node Assignment Count (sh:nodeAssignmentCount) - total number of pairs of targeted nodes and shapes
Assignment (sh:assignment) - a property to link a concrete assignment (instance of sh:ShapeAssignment)
Validation Details (sh:ShapeAssignment) - the actual assignment reporting on focus node, shape and optionally on conformance

Closes #1221

See this document rendered online here

ajnelson-nist · 2026-09-08T18:40:12Z

+						<p>
+							A valdiation report MAY contain one value for the property <code>sh:nodeAssignmentCount</code>.
+							The value MUST be equal to the total number of shape assignments of a <a>focus node</a> to a <a>shape</a>.
+							It MUST include focus nodes of target declarations other than <a href="#targetNode"><code>sh:targetNode</code></a>, which are determined by grounding the target nodes based on the specific target declaration.


"other than" feels wrong here.

If I write a shape targeting a node but typo the node IRI, I want the report to hint to me 0 matches.

But, when a shapes graph has many targeting shapes, that 0-count will be obscured information.

This leans me to thinking sh:nodeAssignmentCount would go into some kind of reporting node about a shape. Now, node shape, or property shape, or both?

My day to day shapes usage includes graphs that lean on blank nodes for inlining property shapes, many of which appear redundant and impossible to distinguish if separated from their parent node. So, maybe sh:nodeAssignmentCount would only reported on shapes using some kind of targeting predicate.

And this leads me to thinking there's a verbosity-scale for this optional feature. Maybe I want sh:nodeAssignmentCount for all shapes that had an assignment; and in a next-level verbosity, I want sh:nodeAssignmentCount for all shapes that could have an assignment (i.e., having a targeting predicate).

Does this help design considerations?

@ajnelson-nist I tried to clarify the description. I think it is aligned with your view, but was misleading.

Ok, after reading the revision, I'm seeing: sh:nodeAssignmentCount is on the validation report, and is not specific to any one shape. It's counting all (shape, node targeted by shape) pairs?

HolgerKnublauch · 2026-09-09T02:09:41Z

Would you mind adding the definitions of the new terms in the shacl.ttl to make it even more specific? I am for example curious how the assignment concept relates to sh:Result/AbstractResult

…o the shacl-core descriptions

ajnelson-nist · 2026-09-09T16:35:56Z

+sh:ShapeAssignment
+	a rdfs:Class ;
+	rdfs:label "Shape assignment"@en ;
+	rdfs:comment "The class of assignments of shapes to nodes."@en ;
+	rdfs:subClassOf sh:AbstractResult ;


What is the relationship between this class and its sibling sh:ValidationResult? Is a ValidationResult implicitly a ShapeAssignment?

Or, never (i.e., classes are disjoint, to be encoded in SHACL-SHACL)?

Rather never, i guess.

Added disjointness statement to the shacl.ttl.

Ah, except shacl.ttl purposefully doesn't use most owl: concepts. Better to leave a firm statement in the rdfs:comment, and update shacl-shacl.ttl as part of this PR's changes.

…ult and sh:ShapeAssignment

afs

LGTM

ajnelson-nist · 2026-10-01T14:23:14Z

+					<section id="nodeAssignmentCount"><!-- ISSUE-1221 -->
+						<h5>Node Assignment Count (sh:nodeAssignmentCount)</h5>
+						<p>
+							A valdiation report MAY contain one value for the property <code>sh:nodeAssignmentCount</code>.


Suggested change

A valdiation report MAY contain one value for the property <code>sh:nodeAssignmentCount</code>.

A validation report MAY contain one value for the property <code>sh:nodeAssignmentCount</code>.

ajnelson-nist · 2026-10-01T14:31:37Z

+							The value MUST be equal to the total number of shape assignments of a <a>shape</a> to a <a>focus node</a>.
+							<code>sh:nodeAssignmentCount</code> only counts shapes and focus nodes defined in a target declaration. 
+							The specific focus nodes are determined by grounding all target nodes of all target declarations. 
+							For example, target declarations of <a href="#targetNode"><code>sh:targetNode</code></a> directly specify the target nodes, 


Possible editorial nit: Isn't "For example"-style text put after a "The remainder of this section is informative" divider?

ajnelson-nist · 2026-10-01T14:32:01Z

+					<section id="assignment"><!-- ISSUE-1221 -->
+						<h5>Assignment (sh:assignment)</h5>
+						<p>
+							A valdiation report MAY containt values for the property <code>sh:assignment</code>.


Suggested change

A valdiation report MAY containt values for the property <code>sh:assignment</code>.

A validation report MAY contain values for the property <code>sh:assignment</code>.

ajnelson-nist · 2026-10-01T14:39:43Z

+						SHACL defines <code>sh:ShapeAssignment</code> to report individual assigmments of a <a>focus node</a> to a <a>shape</a>.
+						Each instance of <code>sh:ShapeAssignment</code> MUST have exactly one value for the property <code>sh:focusNode</code>
+						and exactly one value for the property <code>sh:sourceShape</code>. 
+						It MAY provide exactly one value for the property <code>sh:conforms</code> to indicate an individual conformance of a <a>focus node</a> to a <a>shape</a>. 


This is a significant extension of sh:conforms, and I happen to know it would break some of my tests.

sh:conforms already has rdfs:domain sh:ValidationReport.

This suggested usage of sh:conforms also introduces redundancy, and hence ambiguous discovery, of whether a node passed validation. I think this competency is better left imputed by joining between sh:ShapeAssignment nodes and sh:ValidationResult nodes.

I recommend cutting this line.

Worse, on ambiguous discovery: This is also an opportunity for inconsistent data. Say the assignment reports conformance, but the validation result reports a violation. This would be irreconcilable.

I'm going to mark Request Changes for at least this matter. I haven't gotten back to my prior bigger thread yet.

ajnelson-nist

I feel firmly that the updated application of sh:conforms needs to be removed.

ajnelson-nist · 2026-10-01T14:41:41Z

+						SHACL defines <code>sh:ShapeAssignment</code> to report individual assigmments of a <a>focus node</a> to a <a>shape</a>.
+						Each instance of <code>sh:ShapeAssignment</code> MUST have exactly one value for the property <code>sh:focusNode</code>
+						and exactly one value for the property <code>sh:sourceShape</code>. 
+						It MAY provide exactly one value for the property <code>sh:conforms</code> to indicate an individual conformance of a <a>focus node</a> to a <a>shape</a>. 


Worse, on ambiguous discovery: This is also an opportunity for inconsistent data. Say the assignment reports conformance, but the validation result reports a violation. This would be irreconcilable.

I'm going to mark Request Changes for at least this matter. I haven't gotten back to my prior bigger thread yet.

ajnelson-nist · 2026-10-01T14:51:53Z

+							If it does, it MUST provide one value for every pair of <a>shape</a> and <a>focus node</a>. 
+							If the target declaration is other than <a href="#targetNode"><code>sh:targetNode</code></a>, the pairs are determined by grounding the target nodes based on the specific target declaration.
+							Each value of <code>sh:assignment</code> is a SHACL instance of the class <code>sh:ShapeAssignment</code>. 
+							<span class="todo">TODO: provide a concrete definition of grounding.</span>


I think this TODO needs to be addressed before merging. Do you need the word "grounding?" The word makes it sound like some enigmatic process is about to befall target nodes.

I think some example graph already in the document could be pointed at to count pairs, and that could be a sufficient illustration of counting complexities. Or, maybe the "trick" of a SPARQL SELECT constraint attached to a shape targeting itself, and the SELECT finding multiple nodes, could list a node assignment count of 1.

This shapes graph ...

ex:SelectTrickShape a sh:NodeShape ; sh:targetNode ex:SelectTrickShape ; sh:sparql [ sh:select """ SELECT $this ?value WHERE { ?value ex:flaggingProperty ?x . } """ ] .

... and this data graph...

ex:node1 ex:flaggingProperty "Flagged" . ex:node2 ex:flaggingProperty "Also flagged" .

would beget this validation results graph:

[ a sh:ValidationReport ; sh:nodeAssignmentCount 1 ; # 2 validation results would follow, # ex:node1 and ex:node2 as value nodes. ]

First draft of report extension for infos on matched nodes

0c927e9

robert-david requested review from HolgerKnublauch, afs, ajnelson-nist and osavkovic September 8, 2026 14:43

robert-david self-assigned this Sep 8, 2026

afs added the Core For SHACL 1.2 Core spec label Sep 8, 2026

ajnelson-nist reviewed Sep 8, 2026

View reviewed changes

Added shacl.ttl for shape assignment vocabulary + minor adjustments t…

0a17757

…o the shacl-core descriptions

ajnelson-nist reviewed Sep 9, 2026

View reviewed changes

Clarified the node grounding + added disjointness of sh:ValidationRes…

5da5464

…ult and sh:ShapeAssignment

robert-david requested a review from ajnelson-nist October 1, 2026 13:58

Merge branch 'gh-pages' into issue-1221-report-extension

8bf0cec

afs approved these changes Oct 1, 2026

View reviewed changes

ajnelson-nist reviewed Oct 1, 2026

View reviewed changes

ajnelson-nist requested changes Oct 1, 2026

View reviewed changes

ajnelson-nist reviewed Oct 1, 2026

View reviewed changes

	A valdiation report MAY contain one value for the property <code>sh:nodeAssignmentCount</code>.
	A validation report MAY contain one value for the property <code>sh:nodeAssignmentCount</code>.

	A valdiation report MAY containt values for the property <code>sh:assignment</code>.
	A validation report MAY contain values for the property <code>sh:assignment</code>.

Conversation

robert-david commented Sep 8, 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!

HolgerKnublauch commented Sep 9, 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

afs left a comment

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!

ajnelson-nist Oct 1, 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!

ajnelson-nist left a comment

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!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ajnelson-nist Oct 1, 2026 •

edited

Loading