Skip to content
Sarj Sarj Sarj Standards

prefer-pydantic-json-value

Recursive JSON value alias duplicates pydantic.JsonValue.

SARJ454 Rule source Tests Catalog JSON

Why

Pydantic's canonical JSON value type avoids divergent recursive static domains in packages that already support it. Runtime schema coercion is a separate contract and must be preserved deliberately.

Fix

For private static contracts, import pydantic.JsonValue under the existing alias name. Preserve public alias ownership and runtime coercion/validation contracts; equivalent static JSON domains do not guarantee equivalent TypeAdapter behavior.

Examples

Before — flagged Use Pydantic's canonical recursive JSON value
pyproject.toml
[project]
name = "app"
version = "0.1.0"
dependencies = ["pydantic>=2.5"]
src/app/types.py
type _JsonValue = (
    str | int | float | bool | None | list[_JsonValue] | dict[str, _JsonValue]
)




def _accept(value: _JsonValue) -> None:
    pass
After — preferred The Pydantic alias is already canonical
src/app/types.py
from pydantic import JsonValue


value: JsonValue
Before — flagged Native Unicode alias names preserve the recursive JSON domain
pyproject.toml
[project]
name = "app"
version = "0.1.0"
dependencies = ["pydantic>=2.5"]
src/app/types.py
type _数据 = str | int | float | bool | None | list[_数据] | dict[str, _数据]




def _accept(value: _数据) -> None:
    pass
After — preferred Import the canonical JSON value using a native Unicode binding
pyproject.toml
[project]
name = "app"
version = "0.1.0"
dependencies = ["pydantic>=2"]
src/app/types.py
from pydantic import JsonValue as 数据


value: 数据