Initial swipe at specification detection.

Author: Julian

referencing/__init__.py

@@ -1,6 +1,16 @@
 """
 Cross-specification, implementation-agnostic JSON referencing.
 """
-from referencing._core import Registry, Resource, Specification
+from referencing._core import (
+    CannotDetermineSpecification,
+    Registry,
+    Resource,
+    Specification,
+)
 
-__all__ = ["Registry", "Resource", "Specification"]
+__all__ = [
+    "CannotDetermineSpecification",
+    "Registry",
+    "Resource",
+    "Specification",
+]

referencing/_core.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
-from collections.abc import Iterable
-from typing import Callable, ClassVar, Generic
+from collections.abc import Iterable, Mapping
+from typing import Any, Callable, ClassVar, Generic
 
 from attrs import evolve
 from pyrsistent import pmap
@@ -11,6 +11,18 @@
 from referencing.typing import URI, D
 
 
+@frozen
+class CannotDetermineSpecification(Exception):
+    """
+    Attempting to detect the appropriate `Specification` failed.
+
+    This happens if no discernible information is found in the contents of the
+    new resource which would help identify it.
+    """
+
+    contents: Any
+
+
 @frozen
 class Specification:
     """
@@ -45,11 +57,25 @@ class Resource(Generic[D]):
     _specification: Specification
 
     @classmethod
-    def from_contents(cls, contents: D) -> Resource[D]:
+    def from_contents(
+        cls,
+        contents: D,
+        default_specification: Specification = ...,  # type: ignore[assignment]
+    ) -> Resource[D]:
         """
         Attempt to discern which specification applies to the given contents.
         """
-        return cls(contents=contents, specification=Specification.OPAQUE)
+        specification = default_specification
+        if isinstance(contents, Mapping):
+            jsonschema_dialect_identifier = contents.get("$schema")
+            if jsonschema_dialect_identifier is not None:
+                from referencing import jsonschema
+
+                specification = jsonschema.BY_ID[jsonschema_dialect_identifier]
+
+        if specification is ...:  # type: ignore[comparison-overlap]
+            raise CannotDetermineSpecification(contents)
+        return cls(contents=contents, specification=specification)
 
     def id(self) -> str | None:
         """

referencing/jsonschema.py

@@ -3,3 +3,22 @@
 """
 
 from __future__ import annotations
+
+from referencing import Specification
+
+DRAFT202012 = Specification(id_of=lambda contents: None)
+DRAFT201909 = Specification(id_of=lambda contents: None)
+DRAFT7 = Specification(id_of=lambda contents: None)
+DRAFT6 = Specification(id_of=lambda contents: None)
+DRAFT4 = Specification(id_of=lambda contents: None)
+DRAFT3 = Specification(id_of=lambda contents: None)
+
+
+BY_ID = {
+    "https://json-schema.org/draft/2020-12/schema": DRAFT202012,
+    "https://json-schema.org/draft/2019-09/schema": DRAFT201909,
+    "http://json-schema.org/draft-07/schema#": DRAFT7,
+    "http://json-schema.org/draft-06/schema#": DRAFT6,
+    "http://json-schema.org/draft-04/schema#": DRAFT4,
+    "http://json-schema.org/draft-03/schema#": DRAFT3,
+}

referencing/tests/test_core.py

@@ -1,4 +1,11 @@
-from referencing import Registry, Resource, Specification
+import pytest
+
+from referencing import (
+    CannotDetermineSpecification,
+    Registry,
+    Resource,
+    Specification,
+)
 
 
 def test_registry_with_resource():
@@ -25,14 +32,56 @@ def test_registry_crawl_still_has_top_level_resource():
     assert registry[uri] is resource
 
 
-def test_resource_from_contents_with_no_discernable_information():
+def test_resource_from_contents_with_no_discernible_information():
     """
-    Creating a resource with no discernable way to see what specification it
-    belongs to (e.g. no $schema keyword for JSON Schema) creates one with an
-    opaque specification.
+    Creating a resource with no discernible way to see what specification it
+    belongs to (e.g. no $schema keyword for JSON Schema) raises an error.
     """
 
-    resource = Resource.from_contents({"foo": "bar"})
+    with pytest.raises(CannotDetermineSpecification):
+        Resource.from_contents({"foo": "bar"})
+
+
+def test_resource_from_contents_with_no_discernible_information_and_default():
+    resource = Resource.from_contents(
+        {"foo": "bar"},
+        default_specification=Specification.OPAQUE,
+    )
+    assert resource == Resource(
+        contents={"foo": "bar"},
+        specification=Specification.OPAQUE,
+    )
+
+
+def test_resource_from_contents_unneeded_default():
+    from referencing.jsonschema import DRAFT202012
+
+    resource = Resource.from_contents(
+        {"$schema": "https://json-schema.org/draft/2020-12/schema"},
+        default_specification=Specification.OPAQUE,
+    )
+    assert resource == Resource(
+        contents={"$schema": "https://json-schema.org/draft/2020-12/schema"},
+        specification=DRAFT202012,
+    )
+
+
+def test_non_mapping_resource_from_contents_with_no_discernible_information():
+    resource = Resource.from_contents(
+        True,
+        default_specification=Specification.OPAQUE,
+    )
+    assert resource == Resource(
+        contents=True,
+        specification=Specification.OPAQUE,
+    )
+
+
+def test_resource_from_contents_with_fallback():
+    resource = Resource.from_contents(
+        {"foo": "bar"},
+        default_specification=Specification.OPAQUE,
+    )
     assert resource == Resource(
         contents={"foo": "bar"},
         specification=Specification.OPAQUE,

referencing/tests/test_jsonschema.py

@@ -0,0 +1,42 @@
+import pytest
+
+from referencing import Resource
+import referencing.jsonschema
+
+
+@pytest.mark.parametrize(
+    "uri, expected",
+    [
+        (
+            "https://json-schema.org/draft/2020-12/schema",
+            referencing.jsonschema.DRAFT202012,
+        ),
+        (
+            "https://json-schema.org/draft/2019-09/schema",
+            referencing.jsonschema.DRAFT201909,
+        ),
+        (
+            "http://json-schema.org/draft-07/schema#",
+            referencing.jsonschema.DRAFT7,
+        ),
+        (
+            "http://json-schema.org/draft-06/schema#",
+            referencing.jsonschema.DRAFT6,
+        ),
+        (
+            "http://json-schema.org/draft-04/schema#",
+            referencing.jsonschema.DRAFT4,
+        ),
+        (
+            "http://json-schema.org/draft-03/schema#",
+            referencing.jsonschema.DRAFT3,
+        ),
+    ],
+)
+def test_schemas_with_explicit_schema_keywords_are_detected(uri, expected):
+    """
+    The $schema keyword in JSON Schema is a dialect identifier.
+    """
+    contents = {"$schema": uri}
+    resource = Resource.from_contents(contents)
+    assert resource == Resource(contents=contents, specification=expected)