Dedupe by having one concrete implementation of Specification.

Author: Julian

docs/api.rst

@@ -10,6 +10,10 @@ API Reference
    :members:
    :undoc-members:
 
+.. autoclass:: referencing._core.Specification
+   :members:
+   :undoc-members:
+
 
 Submodules
 ----------

docs/conf.py

@@ -42,9 +42,11 @@
 html_static_path = []
 
 # See sphinx-doc/sphinx#10785
-_TYPE_ALIASES = {
-    "Schema",
-}
+_TYPE_ALIASES = dict(
+    AnchorType=("class", "Anchor"),
+    ObjectSchema=("data", "ObjectSchema"),
+    Schema=("data", "Schema"),
+)
 
 
 def _resolve_broken_refs(app, env, node, contnode):
@@ -62,13 +64,15 @@ def _resolve_broken_refs(app, env, node, contnode):
         return resolve_reference_in_inventory(
             env, "pyrsistent", node, contnode
         )
-    elif node["reftarget"] in _TYPE_ALIASES:
+
+    kind, target = _TYPE_ALIASES.get(node["reftarget"], (None, None))
+    if kind is not None:
         return app.env.get_domain("py").resolve_xref(
             env,
             node["refdoc"],
             app.builder,
-            "data",
-            node["reftarget"],
+            kind,
+            target,
             node,
             contnode,
         )

referencing/__init__.py

@@ -1,7 +1,5 @@
 from referencing._core import (  # noqa: F401
+    OPAQUE_SPECIFICATION,
     IdentifiedResource,
-    OpaqueSpecification as _Opaque,
     Registry,
 )
-
-OPAQUE_SPECIFICATION = _Opaque()

referencing/_core.py

@@ -1,14 +1,14 @@
 from __future__ import annotations
 
-from collections.abc import Iterable, Sequence
+from collections.abc import Callable, Iterable, Sequence
 from urllib.parse import unquote, urldefrag, urljoin
 
 from attrs import evolve, field
 from pyrsistent import m, plist, s
 from pyrsistent.typing import PList, PMap, PSet
 
 from referencing._attrs import define, frozen
-from referencing.typing import Anchor as AnchorType, Schema, Specification
+from referencing.typing import Anchor as AnchorType, ObjectSchema, Schema
 
 
 class UnidentifiedResource(Exception):
@@ -67,21 +67,29 @@ def resolve(self, resolver, uri):
         return self.resource, uri
 
 
-class OpaqueSpecification:
+@frozen
+class Specification:
     """
-    A non-specification `Specification` which treats resources opaquely.
+    A referencing-defining specification.
 
-    In particular, they have no subresources.
+    See `referencing.jsonschema` for JSON Schema-specific instances.
     """
 
-    def id_of(self, resource):
-        return
+    id_of: Callable[[Schema], str | None]
+    subresources_of: Callable[[ObjectSchema], Iterable[Schema]]
+    _anchors_in: Callable[[ObjectSchema, Specification], Iterable[AnchorType]]
+
+    def anchors_in(self, resource: ObjectSchema) -> Iterable[AnchorType]:
+        return self._anchors_in(resource, self)
 
-    def anchors_in(self, resource):
-        return ()
 
-    def subresources_of(self, resource):
-        return ()
+#: A 'null' specification, where resources are opaque
+#: (e.g. have no subresources or IDs).
+OPAQUE_SPECIFICATION = Specification(
+    id_of=lambda resource: None,
+    anchors_in=lambda resource, specification: (),
+    subresources_of=lambda resource: (),
+)
 
 
 @frozen