Give specifications names to make their reprs easier to decipher.

Author: Julian

referencing/_core.py

@@ -22,6 +22,9 @@ class Specification(Generic[D]):
     behavior across JSON Schema specification versions, etc.
     """
 
+    #: A short human-readable name for the specification, used for debugging.
+    name: str
+
     #: Find the ID of a given document.
     id_of: Callable[[D], URI | None]
 
@@ -33,6 +36,9 @@ class Specification(Generic[D]):
     #: nor internal identifiers.
     OPAQUE: ClassVar[Specification[Any]]
 
+    def __repr__(self):
+        return f"<Specification name={self.name!r}>"
+
     def create_resource(self, contents: D) -> Resource[D]:
         """
         Create a resource which is interpreted using this specification.
@@ -41,6 +47,7 @@ def create_resource(self, contents: D) -> Resource[D]:
 
 
 Specification.OPAQUE = Specification(
+    name="opaque",
     id_of=lambda contents: None,
     subresources_of=lambda contents: [],
 )

referencing/jsonschema.py

@@ -56,26 +56,32 @@ def subresources_of(resource: ObjectSchema) -> Iterable[ObjectSchema]:
 
 
 DRAFT202012 = Specification(
+    name="draft2020-12",
     id_of=_dollar_id,
     subresources_of=lambda contents: [],
 )
 DRAFT201909 = Specification(
+    name="draft2019-09",
     id_of=_dollar_id,
     subresources_of=lambda contents: [],
 )
 DRAFT7 = Specification(
+    name="draft-07",
     id_of=_dollar_id,
     subresources_of=_subresources_of(values={"if", "then", "else"}),
 )
 DRAFT6 = Specification(
+    name="draft-06",
     id_of=_dollar_id,
     subresources_of=lambda contents: [],
 )
 DRAFT4 = Specification(
+    name="draft-04",
     id_of=_legacy_id,
     subresources_of=lambda contents: [],
 )
 DRAFT3 = Specification(
+    name="draft-03",
     id_of=_legacy_id,
     subresources_of=lambda contents: [],
 )

referencing/tests/test_core.py

@@ -4,6 +4,7 @@
 from referencing.jsonschema import DRAFT202012
 
 ID_AND_CHILDREN = Specification(
+    name="id-and-children",
     id_of=lambda contents: contents.get("ID"),
     subresources_of=lambda contents: contents.get("children", []),
 )
@@ -274,6 +275,7 @@ def test_from_contents_with_fallback(self):
 
     def test_id_delegates_to_specification(self):
         specification = Specification(
+            name="",
             id_of=lambda contents: "urn:fixedID",
             subresources_of=lambda contents: [],
         )
@@ -367,6 +369,7 @@ def test_lookup_non_existent_pointer_to_array_index(self):
 class TestSpecification:
     def test_create_resource(self):
         specification = Specification(
+            name="",
             id_of=lambda contents: "urn:fixedID",
             subresources_of=lambda contents: [],
         )
@@ -377,6 +380,11 @@ def test_create_resource(self):
         )
         assert resource.id() == "urn:fixedID"
 
+    def test_repr(self):
+        assert (
+            repr(ID_AND_CHILDREN) == "<Specification name='id-and-children'>"
+        )
+
 
 class TestOpaqueSpecification: