Give SHACL findings stable, readable node references

CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 8.4.0 - 2026-07-31
+
+### Added
+
+- SHACL validation issues now carry a `node_pointer` (JSON Pointer to the
+  offending JSON-LD node) alongside `value` and `constraint_component`, so
+  hosts can point at the exact node that failed instead of a graph identifier.
+- `assign_stable_jsonld_ids` and `format_shacl_path` are exported from
+  `wordlift_sdk.validation` for callers rendering their own issue output.
+
+### Changed
+
+- JSON-LD input is given deterministic `@id`s before validation, so report
+  focus nodes stay stable across runs instead of varying with randomly
+  generated blank-node labels.
+- `ValidationIssue.result_path` is now a readable property name (`price`,
+  `address.addressCountry`) rather than a raw IRI, and `focus_node` is `None`
+  for nodes without an `@id` instead of an internal blank-node label.
+
 ## 8.3.8 - 2026-07-15
 
 ### Changed

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "wordlift-sdk"
-version = "8.3.8"
+version = "8.4.0"
 description = "Python toolkit for orchestrating WordLift imports and structured data workflows."
 authors = ["David Riccitelli <david@wordlift.io>"]
 readme = "README.md"

tests/test_schemaorg_domain_validation.py

@@ -47,7 +47,7 @@ def test_schemaorg_domain_rejects_is_part_of_on_service(tmp_path: Path) -> None:
     assert _MESSAGE in result.report_text
     assert issues[0].level == "warning"
     assert issues[0].focus_node == "https://example.org/items/1"
-    assert issues[0].result_path == "http://schema.org/isPartOf"
+    assert issues[0].result_path == "isPartOf"
     assert issues[0].rule_set == "schemaorg-grammar"
     assert issues[0].message == _MESSAGE
 

tests/test_validation_generator_more.py

@@ -479,7 +479,7 @@ def test_generate_schema_shacls_and_schema_main(monkeypatch, tmp_path: Path):
     invalid = shacl.validate_file(invalid_path.as_posix(), shape_specs=[str(out)])
     issues = shacl.extract_validation_issues(invalid)
     assert len(issues) == 1
-    assert issues[0].result_path == "http://schema.org/isPartOf"
+    assert issues[0].result_path == "isPartOf"
     assert issues[0].message.endswith("object of type Service.")
 
     valid_path = tmp_path / "valid.jsonld"