fix: hint at pathlib.Path when load_schema gets a non-JSON str

load_schema parses a str as JSON text, so passing a file path as a str
failed with a bare "Expecting value" decode error. The error is now still
a JSONDecodeError, chained from the original, and says to pass a
pathlib.Path to read a file.

Closes #23

Co-Authored-By: Claude Opus 5.5 <[email protected]>

Author: jnsdls

src/zero_server/schema.py

@@ -58,11 +58,16 @@ class Schema(_SchemaModel):
 
 
 def load_schema(source: str | Path | Mapping[str, Any]) -> Schema:
-    """A schema from `JSON.stringify(schema)`: the JSON text, a path to it, or the parsed object."""
+    """A schema from `JSON.stringify(schema)`: the JSON text as a `str`, a `Path` to it, or the parsed object."""
     if isinstance(source, Path):
-        source = source.read_text()
-    if isinstance(source, str):
-        source = json.loads(source)
+        source = json.loads(source.read_text())
+    elif isinstance(source, str):
+        try:
+            source = json.loads(source)
+        except json.JSONDecodeError as e:
+            raise json.JSONDecodeError(
+                f"{e.msg} (a str is JSON text; pass a pathlib.Path to read a file)", e.doc, e.pos
+            ) from e
     return Schema.model_validate(source)
 
 

tests/unit/test_api.py

@@ -43,6 +43,12 @@ def test_load_schema_from_text_path_or_object(tmp_path: Path) -> None:
     assert load_schema(path) == load_schema(json.dumps(SCHEMA)) == load_schema(SCHEMA)
 
 
+def test_load_schema_str_that_is_not_json_hints_at_path() -> None:
+    with pytest.raises(json.JSONDecodeError, match=r"pathlib\.Path") as raised:
+        load_schema("schema.json")
+    assert isinstance(raised.value.__cause__, json.JSONDecodeError)
+
+
 def test_name_mapper() -> None:
     schema = load_schema(SCHEMA)
     mapper = server_to_client(schema.tables)