Fine-grained JSON document structure control

CHANGELOG.rst

@@ -9,6 +9,8 @@ Features:
 * ``JSONPointer`` and ``RelativeJSONPointer`` now have class attributes defining
   the exceptions that they use, which can be overidden in subclasses
 * Cached properties for accessing document and resource root schemas from subschemas
+* JSON.instantiate_{sequence|mapping}() functions allow more
+  fine-grained control of JSON subclass document structure
 
 
 v0.11.0 (2023-06-03)
@@ -45,8 +47,6 @@ Bug Fixes:
 Documentation:
 
 * Spell 'meta-schema' consistently in tutorials and examples
-
-
 v0.10.2 (2023-04-20)
 --------------------
 Experimental:

jschon/json.py

@@ -75,7 +75,13 @@ def __init__(
 
         The `parent`, `key`, `itemclass` and `itemkwargs` parameters should
         typically only be used in the construction of compound :class:`JSON`
-        documents by :class:`JSON` subclasses.
+        documents by :class:`JSON` subclasses.  The use of these parameters
+        can be customized in subclasses by overriding
+        :meth:`instantiate_sequence` and :meth:`instantiate_mapping`, for
+        example if some child elemnts need to be instances of a different
+        class than others.  Child elements instantiated in this way should
+        still be instances of `itemclass` through inheritance, and
+        `itemkwargs` should be respected if at all possible.
 
         :param value: a JSON-compatible Python object
         :param parent: the parent node of the instance
@@ -135,21 +141,43 @@ def __init__(
 
         elif isinstance(value, Sequence):
             self.type = "array"
-            self.data = [
-                self.itemclass(v, parent=self, key=str(i), **self.itemkwargs)
-                for i, v in enumerate(value)
-            ]
+            self.data = self.instantiate_sequence(value)
 
         elif isinstance(value, Mapping):
             self.type = "object"
-            self.data = {
-                k: self.itemclass(v, parent=self, key=k, **self.itemkwargs)
-                for k, v in value.items()
-            }
+            self.data = self.instantiate_mapping(value)
 
         else:
             raise TypeError(f"{value=} is not JSON-compatible")
 
+    def instantiate_sequence(
+        self,
+        value: Sequence[JSONCompatible],
+    ) -> Sequence[JSON]:
+        """Recursively instantiate JSON arrays.
+
+        By default, instantiate elements as :attr:`itemclass` instances,
+        passing :attr:`itemkwargs` in addition to the parent and key.
+        """
+        return [
+            self.itemclass(v, parent=self, key=str(i), **self.itemkwargs)
+            for i, v in enumerate(value)
+        ]
+
+    def instantiate_mapping(
+        self,
+        value: Mapping[JSONCompatible],
+    ) -> Mapping[JSON]:
+        """Recursively instantiate JSON objects.
+
+        By default, instantiate elements as :attr:`itemclass` instances,
+        passing :attr:`itemkwargs` in addition to the parent and key.
+        """
+        return {
+            k: self.itemclass(v, parent=self, key=k, **self.itemkwargs)
+            for k, v in value.items()
+        }
+
     @cached_property
     def path(self) -> JSONPointer:
         """Return the path to the instance from the document root."""