Parameters are no longer validated according to standard type annotations in v4.0.0

[ryu1]

Description

I recently upgraded flask-jsonrpc in my application to v4.0.0.

It appears that runtime validation based on standard Python type annotations is no longer performed starting from v4.0.0.

The same code behaves differently depending on the version:

v3.0.1: works as expected

v4.0.0: parameters are not validated

In the following example, standard type annotations such as str and Literal[0, 1] are specified.
However, in v4.0.0, invalid values are accepted and the method is executed.

@sample.method("sample.create_engineer")
@permission_required(has_permission=has_full_access)
def create_engineer(
    engineer_name: str,
    engineer_flg: Literal[0, 1],
):
    ...

Runtime: python v3.12.10

Observed behavior (v4.0.0)

Passing a value other than 0 or 1 (e.g. 99) to engineer_flg does not result in an error

Passing None to engineer_name does not result in an error

In all cases, the method is executed and HTTP 400 is not returned

Behavior in v3.0.1

In all of the above cases, HTTP 400 is returned and the method is not executed

Expected

As in v3.0.1, parameters should be validated based on standard type annotations

When parameters are invalid, HTTP status code 400 should be returned

The method should not be executed

Actual

In v4.0.0, the method is executed even when invalid parameter values are provided

HTTP 400 is not returned

Question

This behavior changed between v3.0.1 and v4.0.0.

In v3.0.1, parameters were validated based on standard type annotations, and invalid values resulted in HTTP 400.

In v4.0.0, the same invalid values are accepted and the method is executed.

Is this change an intentional specification change, or is it an unintended regression?

[ryu1]

Maybe the issue was caused by the order of the decorators?
I might have specified them in the wrong order.
Do custom decorators need to be placed above JSONRPCBlueprint.method?
(As a result, it seems that the custom decorator is no longer being executed.)

@permission_required(has_permission=has_full_access)
@sample.method("sample.create_engineer")
def create_engineer(
    engineer_name: str,
    engineer_flg: Literal[0, 1],
):
    ...

decorator

def permission_required(
    has_permission: Callable[[User], bool] | None = None,
) -> Callable[[Callable[..., Any | None]], Any]:

    def _permission_required(func: Callable[..., Any | None]) -> Any:
        @wraps(func)
        def wrapped(*args: Any, **kwargs: Any) -> Any:

            ...

            return func(*args, **kwargs)

        return wrapped

    return _permission_required

---

To summarize, it appears that the behavior differs depending on the order of the decorators, as follows.

1. Custom decorator(permission_required) applied before JSONRPCBlueprint.method

@permission_required(has_permission=has_full_access)
@sample.method("sample.create_engineer")
def create_engineer(
    engineer_name: str,
    engineer_flg: Literal[0, 1],
):
    ...

Result

The permission_required decorator is not executed.
When invalid parameters are provided, the request correctly returns HTTP 400.

2. Custom decorator(permission_required) applied after JSONRPCBlueprint.method

@sample.method("sample.create_engineer")
@permission_required(has_permission=has_full_access)
def create_engineer(
    engineer_name: str,
    engineer_flg: Literal[0, 1],
):
    ...

Result

The permission_required decorator is executed, but
when invalid parameters are provided (e.g. a value other than 0 or 1 for engineer_flg),
the request still passes validation and the method is executed.

[ryu1]

flask-jsonrpc/src/flask_jsonrpc/wrappers.py

Lines 206 to 224 in 9ad5674

	def _typechecked_wraps(self: Self, view_func: t.Callable[..., t.Any]) -> t.Callable[..., t.Any]:
	"""Wrap the view function with type checking, preserving wrappers.
	Args:
	view_func (typing.Callable[..., typing.Any]): The view function to wrap.
	Returns:
	typing.Callable[..., typing.Any]: The wrapped view function with type checking.
	"""
	wrapped_view_funcs = self._get_function_and_wrappers(view_func)
	new_view_func = typechecked(wrapped_view_funcs.pop())
	wrapped_view_funcs.append(new_view_func)
	fn_wrapper = fn_wrapped = wrapped_view_funcs.pop()
	while len(wrapped_view_funcs) > 0:
	fn_wrapper = wrapped_view_funcs.pop()
	functools.update_wrapper(fn_wrapper, fn_wrapped)
	fn_wrapped = fn_wrapper
	return fn_wrapper

Will typechecked work correctly when a custom decorator is used?

[ryu1]

Currently, when a function is decorated, type checking appears to be performed against the decorator itself rather than the original function.

In my case, the decorator’s parameters were typed as Any, so even invalid values did not trigger a type validation error, and the function was executed.

This issue seems to originate from typeguard itself and did not occur in v3.12, where a wrapper-based approach was used.
In contrast, recent versions of typeguard adopt an instrumentation-based approach, but when other decorators are present, type checking appears to no longer function correctly.

[nycholas]

Hi @ryu1,

Maybe the issue was caused by the order of the decorators?

The order of the decorators matters, and the decorator must also have the same type-hint signature as the JSON-RPC method. For example:

def jsonrpc_decorator(fn: t.Callable[..., str]) -> t.Callable[..., str]:
    def decorator(string: str) -> str:
        rv = fn(string)
        return f'{rv} from decorator, ;)'

    return decorator


@jsonrpc.method('decorators.decorator')
@jsonrpc_decorator
def decorator(string: str) -> str:
    return f'Hello {string}'

It works as expected:

$ curl -i -X POST    -H "Content-Type: application/json; indent=4"    -d '{
    "jsonrpc": "2.0",
    "method": "decorators.decorator",
    "params": {"string": "Pizza"},
    "id": "1"
}' http://localhost:5000/api
HTTP/1.1 200 OK
Server: Werkzeug/3.1.4 Python/3.13.7
Date: Tue, 20 Jan 2026 20:31:10 GMT
Content-Type: application/json
Content-Length: 82
Connection: close

{
  "id": "1",
  "jsonrpc": "2.0",
  "result": "Hello Pizza from decorator, ;)"
}

If the decorator does not implement the required type hints, it will raise an exception at startup.

def jsonrpc_decorator(fn: t.Callable[..., str]) -> t.Callable[..., str]:
    def decorator(string):
        rv = fn(string)
        return f'{rv} from decorator, ;)'

    return decorator

The Python interpreter:

    @jsonrpc.method('decorators.decorator')
     ~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/nycholas/Temporary/.p/flask-jsonrpc/src/flask_jsonrpc/wrappers.py", line 338, in decorator
    raise ValueError(f'no type annotations present to: {method_name}') from None
ValueError: no type annotations present to: decorators.decorator

If the decorator has a different type hint for the JSON-RPC method, or uses typing.Any, the call will be processed according to the decorator’s type hints.

After upgrading to Typeguard 4.x, some implementations broke due to the instrumentation strategy (as I understand it). There is a limitation with decorators: Typeguard cannot apply instrumentation to multiple nested decorators. As a result, only the first decorator receives the instrumentation, and the remaining ones are not validated.

In your case, you need to use the same type hints in the decorator as well. For example:

def jsonrpc_decorator(fn: t.Callable[..., str]) -> t.Callable[..., str]:
    def decorator(engineer_name: str, engineer_flg: t.Literal[0, 1]) -> str:
        rv = fn(engineer_name, engineer_flg)
        return f'{rv} from decorator, ;)'

    return decorator


@jsonrpc.method('decorators.decorator')
@jsonrpc_decorator
def decorator(engineer_name: str, engineer_flg: t.Literal[0, 1]) -> str:
    return f'Hello {engineer_name}, engineer flag is {engineer_flg}'

Testing:

$ curl -i -X POST    -H "Content-Type: application/json; indent=4"    -d '{
    "jsonrpc": "2.0",
    "method": "decorators.decorator",
    "params": {"engineer_name": "Pizza", "engineer_flg": 1},
    "id": "1"
}' http://localhost:5000/api
HTTP/1.1 200 OK
Server: Werkzeug/3.1.4 Python/3.13.7
Date: Tue, 20 Jan 2026 21:43:22 GMT
Content-Type: application/json
Content-Length: 102
Connection: close

{
  "id": "1",
  "jsonrpc": "2.0",
  "result": "Hello Pizza, engineer flag is 1 from decorator, ;)"
}

Error case:

$ curl -i -X POST \
   -H "Content-Type: application/json; indent=4" \
   -d '{
    "jsonrpc": "2.0",
    "method": "decorators.decorator",
    "params": {"engineer_name": "Pizza", "engineer_flg": 2},
    "id": "1"
}' http://localhost:5000/api
HTTP/1.1 400 BAD REQUEST
Server: Werkzeug/3.1.4 Python/3.13.7
Date: Tue, 20 Jan 2026 21:44:52 GMT
Content-Type: application/json
Content-Length: 2280
Connection: close

{
  "error": {
    "code": -32602,
    "data": {
      "message": "argument \"engineer_flg\" (int) is not any of (0, 1)"
    },
    "message": "Invalid params",
    "name": "InvalidParamsError"
  },
  "id": "1",
  "jsonrpc": "2.0"
}

I need to figure out a way to instrument the entire stack of decorators and ensure that validation is applied to each one. I will let this issue open for this purpose.

Thank you!

[nycholas]

The limitation of typeguard:

typeguard.InstrumentationWarning: @typechecked only supports instrumenting functions wrapped with @classmethod, @staticmethod or @property -- not typechecking shared.features.decorators.wrappedDecorator

[ryu1]

Hi @nycholas, thanks a lot for taking the time to look into this and for verifying the behavior. I really appreciate it.

My decorator is used with functions that have a wide variety of different parameters, and for the sake of generality, the decorator itself is typed using Any.

At the moment, it’s still unclear to me whether the current limitation of typeguard will be resolved on the typeguard side, or how long that might take.

Because of that uncertainty, I’ve been experimenting with an alternative approach: using the checker APIs (check_type) that typeguard currently exposes to see whether it’s possible to restore a wrapper-style typechecked implementation similar to the previous behavior. I’m still in the process of validating this idea, and to be honest it’s not working perfectly yet, but I wanted to share the direction I’m exploring.

As a potential workaround until the typeguard limitation is addressed, this approach might be something worth considering. Below is a rough sketch of what I’m experimenting with:

class JSONRPCDecoratorMixin:
    """Mixin class to add JSON-RPC method and error handler decorators."""


   ....


    def _check_paramater_types(
        self: Self, original: t.Callable[..., t.Any], args: tuple[t.Any, ...], kwargs: dict[str, t.Any]
    ) -> dict[str, t.Any]:
        """Check input types of the function arguments."""
        sig = inspect.signature(original)
        bound = sig.bind(*args, **kwargs)
        bound.apply_defaults()

        type_hints = t.get_type_hints(original)

        for name, value in bound.arguments.items():
            if name in type_hints:
                annotation = type_hints[name]
                if annotation is t.NoReturn or annotation is NeverType:
                    exc = TypeCheckError(f'{function_name(original)}() was declared never to be called but it was')
                    raise exc
                try:
                    check_type(value, type_hints[name])
                except TypeCheckError as exc:
                    qualname = qualified_name(value, add_class_prefix=True)
                    exc.args = (f'argument "{name}" ({qualname}) {exc.args[0]}',)
                    exc._path = deque()
                    raise
        return type_hints

    def _check_return_type(
        self: Self, original: t.Callable[..., t.Any], retval: t.Any, type_hints: dict[str, t.Any]
    ) -> None:
        """Check the return type of the function."""
        if 'return' in type_hints and not inspect.iscoroutinefunction(original):
            try:
                check_type(retval, type_hints['return'])
            except TypeCheckError as exc:
                qualname = qualified_name(retval, add_class_prefix=True)
                exc.append_path_element(f'the return value ({qualname})')
                raise

    def _typechecked_wraps(self: Self, view_func: t.Callable[..., t.Any]) -> t.Callable[..., t.Any]:  # noqa: C901
        """Wrap the view function with type checking, preserving wrappers
        (supports functions with and without functools.wraps).
        """
        original = _find_original(view_func)

        @functools.wraps(view_func)
        def typechecked_sync(*args: t.Any, **kwargs: t.Any) -> t.Any:  # noqa: ANN401
            type_hints = self._check_paramater_types(original, args, kwargs)
            retval = view_func(*args, **kwargs)
            self._check_return_type(original, retval, type_hints)
            return retval

        @functools.wraps(view_func)
        async def typechecked_async(*args: t.Any, **kwargs: t.Any) -> t.Any:  # noqa: ANN401
            type_hints = self._check_paramater_types(original, args, kwargs)
            retval = await view_func(*args, **kwargs)
            self._check_return_type(original, retval, type_hints)
            return retval

        wrapper = typechecked_async if inspect.iscoroutinefunction(original) else typechecked_sync

        if original is not view_func and not hasattr(wrapper, '__wrapped__'):
            wrapper.__wrapped__ = original

        return wrapper

This is not meant as a final solution, but rather as a possible workaround idea while waiting to see how the typeguard limitation evolves.

If you find my idea interesting, I would appreciate it if you would consider it.

[nycholas]

Thank you for your time on this issue. I don’t think TypeGuard will solve it, because the instrumentation does not happen at runtime—it occurs at startup. It replaces the JSON-RPC method with another one using the AST (or something similar). I will analyze your approach carefully.

Apologies, I forgot to share a workaround. My current workaround is to check the wrapped function before executing it. See the example below:

def jsonrpc_decorator(fn: t.Callable[..., str]) -> t.Callable[..., str]:
    @wraps(fn)
    def decorator(*args: t.Any, **kwargs: t.Any) -> str:
        fn_wrapped = typechecked(fn)
        rv = fn_wrapped(*args, **kwargs)
        return f'{rv} from decorator, ;)'

    return decorator


@jsonrpc.method('decorators.decorator')
@jsonrpc_decorator
def decorator(engineer_name: str, engineer_flg: t.Literal[0, 1]) -> str:
    return f'Hello {engineer_name}, engineer flag is {engineer_flg}'

Thank you.

[ryu1]

Thanks, @nycholas — I really appreciate the workaround suggestion. It’s very helpful.
I’d appreciate it if you could continue to consider this issue.

[nycholas]

@ryu1 I didn’t remember the reason for that (sorry for the unclear explanation). Here is the reason: agronholm/typeguard#319

[ryu1]

@nycholas
Thanks for the additional context and discussion.

From my understanding, the current behavior of typechecked introduces a fundamental mismatch with what flask-jsonrpc needs.

When typechecked is applied to instance methods, it may drop or mis-handle self, which already makes integration fragile. More importantly, the current implementation of typechecked no longer focuses only on argument and return type validation, but also performs runtime type checks on local variables inside the function body.

While this makes sense from typeguard’s perspective (stronger runtime type safety), flask-jsonrpc has a different responsibility: validating request and response parameters at the API boundary. It does not require — and likely should not enforce — runtime type checking of internal local variables.

In this context, the previous wrapper-based approach seems to have been a better fit for flask-jsonrpc. It aligned well with boundary validation, avoided deeper interference with function internals, and worked more naturally with instance methods.

So the issue here may not be a bug in either project, but a design mismatch between the expanded scope of typechecked and the narrower validation needs of flask-jsonrpc.

I hope this perspective is useful for the ongoing discussion, and I appreciate any further thoughts on this.

[nycholas]

So the issue here may not be a bug in either project, but a design mismatch between the expanded scope of typechecked and the narrower validation needs of flask-jsonrpc.

@ryu1 I couldn't agree more. I'm in the middle of a crossroads, either go to another library or create a package inside the Flask JSONRPC to do it.

If you have any suggestions, please share them with me.

Thank you.

[ryu1]

Hi @nycholas,

Thank you for the detailed discussion. Based on the analysis above, I'd like to suggest a third option that doesn't require switching libraries or building a full internal validator.

Root cause reframed: The problem is not typeguard itself, but where flask-jsonrpc applies it. Currently, typechecked is applied to the outermost wrapper, which has already lost the original type annotations. The fix is to apply typechecked at the innermost layer — before any user-defined decorators run.

Proposed approach: an explicit @validate decorator

This idea is also an application of the Single Responsibility Principle (SRP). Currently, @method carries two responsibilities: RPC registration and type validation. By explicitly separating these, we can avoid interference from custom decorators.

Introduce an opt-in @validate decorator that users place closest to the original function:

@sample.method("sample.create_engineer")
@permission_required(has_permission=has_full_access)
@sample.validate  # applied before permission_required wraps it
def create_engineer(
    engineer_name: str,
    engineer_flg: Literal[0, 1],
):
    ...

The implementation of validate is minimal — it simply calls typechecked (or any validator) on the function before other decorators obscure its signature:

def validate(self, func):
    return typechecked(func)

At this point in the decorator stack, create_engineer's original annotations (str, Literal[0, 1]) are still fully visible. Once typechecked instruments the function here, the instrumentation survives being wrapped by @permission_required — so validation still runs correctly when the method is called.

Why this avoids the crossroads:

• No library switch needed — typeguard continues to work, just applied at the right layer
• No internal validator to build and maintain
• Zero changes to user code that doesn't use custom decorators (they keep working as before)
• Users with custom decorators get a clear, explicit fix

The main trade-off is that @validate must be added manually, so users who forget it won't get validation. A reasonable mitigation would be for @method to emit a warning if it detects a decorator chain without a typechecked-instrumented inner function.

---

Note: I arrived at this proposal through a discussion with Claude (Anthropic's AI assistant). I found the analysis useful and wanted to share it here — but of course, please treat it as a starting point for discussion rather than a definitive solution.