Try to be more helpful when someone forgets a slash in JSON pointers.

Refs: python-jsonschema/jsonschema#1070

Author: Julian

docs/spelling-wordlist.txt

@@ -3,6 +3,7 @@ autodetecting
 boolean
 changelog
 deduplication
+dereferenced
 deserialized
 discoverability
 filesystem

referencing/_core.py

@@ -359,6 +359,16 @@ def anchor(self, uri: URI, name: str):
         value = registry._anchors.get((uri, name))
         if value is not None:
             return Retrieved(value=value, registry=registry)
+        if "/" in name:
+            raise exceptions.InvalidAnchor(
+                ref=uri,
+                resource=self[uri],
+                anchor=name,
+                suggestion=(
+                    f"You may have intended to use '#/{name}'. The slash is "
+                    "required *before each* segment of a JSON Pointer."
+                ),
+            )
         raise exceptions.NoSuchAnchor(ref=uri, resource=self[uri], anchor=name)
 
     def contents(self, uri: URI) -> D:

referencing/exceptions.py

@@ -107,3 +107,27 @@ def __str__(self):
         return (
             f"{self.anchor!r} does not exist within {self.resource.contents!r}"
         )
+
+
+@frozen
+class InvalidAnchor(Unresolvable):
+    """
+    An anchor which could never exist in a resource was dereferenced.
+
+    It is somehow syntactically invalid.
+    """
+
+    resource: Resource[Any]
+    anchor: str
+    _suggestion: str | None = attrs.field(default=None, alias="suggestion")
+
+    def __str__(self):
+        suggestion = (
+            ""
+            if self._suggestion is None
+            else (f" You may have intended to use {self._suggestion}.")
+        )
+        return (
+            f"'#{self.anchor}' is not a valid anchor, neither as a "
+            f"plain name anchor nor as a JSON Pointer.{suggestion}"
+        )

referencing/tests/test_core.py

@@ -738,6 +738,23 @@ def test_lookup_non_existent_anchor(self):
             anchor="noSuchAnchor",
         )
 
+    def test_lookup_invalid_JSON_pointerish_anchor(self):
+        resolver = Registry().resolver_with_root(
+            ID_AND_CHILDREN.create_resource(
+                {
+                    "ID": "http://example.com/",
+                    "foo": {"bar": 12},
+                },
+            ),
+        )
+
+        valid = resolver.lookup("#/foo/bar")
+        assert valid.contents == 12
+
+        with pytest.raises(exceptions.InvalidAnchor) as e:
+            resolver.lookup("#foo/bar")
+        assert " '#/foo/bar'" in str(e.value)
+
     def test_lookup_retrieved_resource(self):
         resource = Resource.opaque(contents={"foo": "baz"})
         resolver = Registry(retrieve=lambda uri: resource).resolver()