diff --git a/src/type_aliases.py b/src/type_aliases.py
index 181a8232..ecb80e75 100644
--- a/src/type_aliases.py
+++ b/src/type_aliases.py
@@ -18,6 +18,9 @@ ToolCall: TypeAlias = Metadata
 
 CommsLogCallback: TypeAlias = Callable[[CommsLogEntry], None]
 
+JsonPrimitive: TypeAlias = str | int | float | bool | None
+JsonValue: TypeAlias = JsonPrimitive | list["JsonValue"] | dict[str, "JsonValue"]
+
 
 class FileItemsDiff(NamedTuple):
  refreshed: FileItems
diff --git a/tests/test_type_aliases.py b/tests/test_type_aliases.py
index 2890100b..245f139f 100644
--- a/tests/test_type_aliases.py
+++ b/tests/test_type_aliases.py
@@ -49,4 +49,36 @@ def test_file_items_diff_named_tuple_has_two_fields() -> None:
 def test_result_with_file_items_alias_composes() -> None:
  r: result_types.Result[type_aliases.FileItems] = result_types.Result(data=[])
  assert r.ok is True
- assert isinstance(r.data, list)
\ No newline at end of file
+ assert isinstance(r.data, list)
+
+
+def test_json_primitive_alias_resolves_to_union() -> None:
+ assert hasattr(type_aliases, "JsonPrimitive")
+ hints = get_type_hints(type_aliases)
+ assert "JsonPrimitive" in hints
+
+
+def test_json_value_alias_resolves_to_recursive_union() -> None:
+ assert hasattr(type_aliases, "JsonValue")
+ hints = get_type_hints(type_aliases)
+ assert "JsonValue" in hints
+ jv = hints["JsonValue"]
+ assert jv is not None
+
+
+def test_json_value_accepts_primitive_dict() -> None:
+ payload: type_aliases.JsonValue = {"key": "value", "count": 42, "active": True, "nothing": None}
+ assert payload["key"] == "value"
+ assert payload["count"] == 42
+ assert payload["active"] is True
+ assert payload["nothing"] is None
+
+
+def test_json_value_accepts_nested_structures() -> None:
+ payload: type_aliases.JsonValue = {
+  "users": [{"name": "alice", "age": 30}, {"name": "bob", "age": 25}],
+  "metadata": {"source": "test", "tags": ["a", "b", "c"]},
+ }
+ assert len(payload["users"]) == 2
+ assert payload["users"][0]["name"] == "alice"
+ assert payload["metadata"]["tags"][1] == "b"
\ No newline at end of file