schemmy 0.1.0__tar.gz

schemmy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ruslan Glotov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

schemmy-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: schemmy
+Version: 0.1.0
+Summary: Validate data with plain type annotations. No dependencies.
+Keywords: validation,schema,type-hints,annotations,typing
+Author: Ruslan Glotov
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/rusih100/schemmy
+Project-URL: Issues, https://github.com/rusih100/schemmy/issues
+Description-Content-Type: text/markdown
+
+# schemmy
+
+Validate data with plain type annotations. No dependencies.
+
+```bash
+pip install schemmy
+# or
+uv add schemmy
+```
+
+Requires Python 3.12+.
+
+## Example
+
+```python
+from typing import Annotated
+
+from schemmy import Schema, ValidationError
+
+
+def positive(value: int) -> int:
+    if value <= 0:
+        raise ValueError("must be greater than zero")
+    return value
+
+
+class Item(Schema):
+    sku: str
+    qty: Annotated[int, positive]
+
+
+class Order(Schema):
+    id: int
+    items: list[Item]
+
+
+order = Order.validate({"id": 1, "items": [{"sku": "A1", "qty": 2}]})
+order.items[0].qty  # 2
+```
+
+All errors are collected at once, not just the first one. Each error carries the path to the field:
+
+```python
+try:
+    Order.validate({"id": "1", "items": [{"sku": "A1", "qty": 0}, {"qty": 3}], "note": "x"})
+except ValidationError as exc:
+    for error in exc.exceptions:
+        print(error.location, error.message)
+```
+
+```text
+['note'] Unknown field
+['id'] Expected int, got str
+['items', 0, 'qty'] Validator positive failed: must be greater than zero
+['items', 1, 'sku'] Field required
+```
+
+Errors come in a stable order: missing and unknown fields first, then value errors in field declaration order.
+
+`ValidationError` is an `ExceptionGroup`, so `except*` works too.
+
+## What is supported
+
+| Annotation | Behavior |
+|---|---|
+| `int`, `str`, `float`, `bool`, any class | `isinstance` check, no type coercion. `bool` is rejected for `int` fields |
+| `float` | Also accepts an `int` that `float` represents exactly and converts it, since JSON sends `1` for `1.0` |
+| `Any` | Value is accepted as is |
+| `list[T]` | Each item is checked against `T`; the item index is added to the error path |
+| `tuple[T, ...]`, `tuple[T1, T2]` | Accepts a tuple or a list and stores a tuple, since JSON has no tuples. A fixed tuple requires the exact length |
+| `dict[K, V]` | Each key is checked against `K` and each value against `V`; the key is added to the error path |
+| `Literal[...]` | The value must equal one of the literals and have the same type, so `True` does not match `Literal[1]` |
+| `X \| Y`, `Optional[X]` | Members are tried in order, the first match wins. For `X \| None`, errors of `X` are reported as is |
+| `Schema` subclass | Accepts a schema instance or a `dict` |
+| `Annotated[T, *validators]` | `T` is checked first, then validators run in order |
+
+A validator is a callable that takes a value and returns it, possibly changed. To report an error, a validator raises an exception. The returned value is stored in the schema, so validators can normalize data, for example bring a phone number to a single format.
+
+Unknown fields and missing required fields are validation errors as well.
+
+A field with a default value is optional. If the field is not passed, the schema gets a copy of the default. The default value itself is not validated.
+
+`ClassVar` annotations are not fields.
+
+## Working with instances
+
+```python
+order.to_dict()
+# {'id': 1, 'items': [{'sku': 'A1', 'qty': 2}]}
+
+order
+# Order(id=1, items=[Item(sku='A1', qty=2)])
+
+Order.validate(order.to_dict()) == order
+# True
+```
+
+`to_dict` converts nested schemas recursively and keeps field declaration order. Schemas compare by class and field values. Schemas are mutable and therefore unhashable.
+
+## Type checking
+
+Type checkers derive the constructor signature from the annotations, so wrong types, unknown and missing fields are reported before runtime:
+
+```python
+Item(sku=1, qty=2)  # error: expected str
+Item(sku="A1", qyt=2)  # error: unknown argument
+```
+
+The constructor is typed for already typed values. Use `Schema.validate` for raw data such as parsed JSON, where nested schemas arrive as dicts.
+
+## Limitations
+
+`set`, `frozenset`, `TypedDict` and other annotations not listed above are not supported yet. A field with such an annotation produces an "unsupported type" error.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+uv run ty check
+```
+
+## License
+
+MIT

schemmy-0.1.0/README.md

@@ -0,0 +1,126 @@
+# schemmy
+
+Validate data with plain type annotations. No dependencies.
+
+```bash
+pip install schemmy
+# or
+uv add schemmy
+```
+
+Requires Python 3.12+.
+
+## Example
+
+```python
+from typing import Annotated
+
+from schemmy import Schema, ValidationError
+
+
+def positive(value: int) -> int:
+    if value <= 0:
+        raise ValueError("must be greater than zero")
+    return value
+
+
+class Item(Schema):
+    sku: str
+    qty: Annotated[int, positive]
+
+
+class Order(Schema):
+    id: int
+    items: list[Item]
+
+
+order = Order.validate({"id": 1, "items": [{"sku": "A1", "qty": 2}]})
+order.items[0].qty  # 2
+```
+
+All errors are collected at once, not just the first one. Each error carries the path to the field:
+
+```python
+try:
+    Order.validate({"id": "1", "items": [{"sku": "A1", "qty": 0}, {"qty": 3}], "note": "x"})
+except ValidationError as exc:
+    for error in exc.exceptions:
+        print(error.location, error.message)
+```
+
+```text
+['note'] Unknown field
+['id'] Expected int, got str
+['items', 0, 'qty'] Validator positive failed: must be greater than zero
+['items', 1, 'sku'] Field required
+```
+
+Errors come in a stable order: missing and unknown fields first, then value errors in field declaration order.
+
+`ValidationError` is an `ExceptionGroup`, so `except*` works too.
+
+## What is supported
+
+| Annotation | Behavior |
+|---|---|
+| `int`, `str`, `float`, `bool`, any class | `isinstance` check, no type coercion. `bool` is rejected for `int` fields |
+| `float` | Also accepts an `int` that `float` represents exactly and converts it, since JSON sends `1` for `1.0` |
+| `Any` | Value is accepted as is |
+| `list[T]` | Each item is checked against `T`; the item index is added to the error path |
+| `tuple[T, ...]`, `tuple[T1, T2]` | Accepts a tuple or a list and stores a tuple, since JSON has no tuples. A fixed tuple requires the exact length |
+| `dict[K, V]` | Each key is checked against `K` and each value against `V`; the key is added to the error path |
+| `Literal[...]` | The value must equal one of the literals and have the same type, so `True` does not match `Literal[1]` |
+| `X \| Y`, `Optional[X]` | Members are tried in order, the first match wins. For `X \| None`, errors of `X` are reported as is |
+| `Schema` subclass | Accepts a schema instance or a `dict` |
+| `Annotated[T, *validators]` | `T` is checked first, then validators run in order |
+
+A validator is a callable that takes a value and returns it, possibly changed. To report an error, a validator raises an exception. The returned value is stored in the schema, so validators can normalize data, for example bring a phone number to a single format.
+
+Unknown fields and missing required fields are validation errors as well.
+
+A field with a default value is optional. If the field is not passed, the schema gets a copy of the default. The default value itself is not validated.
+
+`ClassVar` annotations are not fields.
+
+## Working with instances
+
+```python
+order.to_dict()
+# {'id': 1, 'items': [{'sku': 'A1', 'qty': 2}]}
+
+order
+# Order(id=1, items=[Item(sku='A1', qty=2)])
+
+Order.validate(order.to_dict()) == order
+# True
+```
+
+`to_dict` converts nested schemas recursively and keeps field declaration order. Schemas compare by class and field values. Schemas are mutable and therefore unhashable.
+
+## Type checking
+
+Type checkers derive the constructor signature from the annotations, so wrong types, unknown and missing fields are reported before runtime:
+
+```python
+Item(sku=1, qty=2)  # error: expected str
+Item(sku="A1", qyt=2)  # error: unknown argument
+```
+
+The constructor is typed for already typed values. Use `Schema.validate` for raw data such as parsed JSON, where nested schemas arrive as dicts.
+
+## Limitations
+
+`set`, `frozenset`, `TypedDict` and other annotations not listed above are not supported yet. A field with such an annotation produces an "unsupported type" error.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+uv run ty check
+```
+
+## License
+
+MIT

schemmy-0.1.0/pyproject.toml

@@ -0,0 +1,105 @@
+[project]
+name = "schemmy"
+version = "0.1.0"
+description = "Validate data with plain type annotations. No dependencies."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = []
+keywords = [
+    "validation",
+    "schema",
+    "type-hints",
+    "annotations",
+    "typing",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+
+[[project.authors]]
+name = "Ruslan Glotov"
+
+[project.urls]
+Repository = "https://github.com/rusih100/schemmy"
+Issues = "https://github.com/rusih100/schemmy/issues"
+
+[build-system]
+requires = ["uv_build>=0.13.1,<0.14"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.7.0",
+    "pytest>=9.1.1",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.17.1",
+    "ty>=0.0.88",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "W",
+    "F",
+    "I",
+    "Q",
+    "UP",
+    "C",
+    "B",
+    "S",
+    "ISC",
+    "T20",
+    "ANN",
+    "TC",
+    "PT",
+    "SIM",
+    "RUF",
+]
+ignore = [
+    "E501",
+    "ANN401",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = [
+    "--strict-markers",
+    "--strict-config",
+]
+
+[tool.coverage.run]
+branch = true
+source = ["schemmy"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+
+[tool.ty.terminal]
+error-on-warning = true
+
+[[tool.ty.overrides]]
+include = ["tests/**"]
+
+[tool.ty.overrides.rules]
+invalid-argument-type = "ignore"
+missing-argument = "ignore"
+unknown-argument = "ignore"

schemmy-0.1.0/pyproject.toml.orig

@@ -0,0 +1,95 @@
+[project]
+name = "schemmy"
+version = "0.1.0"
+description = "Validate data with plain type annotations. No dependencies."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Ruslan Glotov" }]
+requires-python = ">=3.12"
+dependencies = []
+keywords = ["validation", "schema", "type-hints", "annotations", "typing"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Repository = "https://github.com/rusih100/schemmy"
+Issues = "https://github.com/rusih100/schemmy/issues"
+
+[build-system]
+requires = ["uv_build>=0.13.1,<0.14"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.7.0",
+    "pytest>=9.1.1",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.17.1",
+    "ty>=0.0.88",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "Q",   # flake8-quotes
+    "UP",  # pyupgrade
+    "C",   # flake8-comprehensions + mccabe
+    "B",   # flake8-bugbear
+    "S",   # flake8-bandit
+    "ISC", # flake8-implicit-str-concat
+    "T20", # print and pprint
+    "ANN", # flake8-annotations
+    "TC",  # flake8-type-checking
+    "PT",  # flake8-pytest-style
+    "SIM", # flake8-simplify
+    "RUF", # ruff-specific rules
+]
+ignore = [
+    "E501",   # line length is handled by ruff format
+    "ANN401", # Any is allowed: schemas accept arbitrary values
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = ["--strict-markers", "--strict-config"]
+
+[tool.coverage.run]
+branch = true
+source = ["schemmy"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+
+[tool.ty.terminal]
+error-on-warning = true
+
+# Tests pass invalid data on purpose.
+[[tool.ty.overrides]]
+include = ["tests/**"]
+
+[tool.ty.overrides.rules]
+invalid-argument-type = "ignore"
+missing-argument = "ignore"
+unknown-argument = "ignore"

schemmy-0.1.0/src/schemmy/__init__.py

@@ -0,0 +1,4 @@
+from schemmy.exceptions import FieldValidationError, ValidationError
+from schemmy.schema import Schema
+
+__all__ = ["FieldValidationError", "Schema", "ValidationError"]

schemmy-0.1.0/src/schemmy/exceptions.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import cast
+
+
+class FieldValidationError(Exception):
+    """
+    Validation error of a single schema field.
+    """
+
+    def __init__(self, *, field: str, message: str, location: list[str | int]) -> None:
+        self.field: str = field
+        self.message: str = message
+        self.location: list[str | int] = location
+
+    def __str__(self) -> str:
+        return f"({self.field}: {self.message}. {self.location})"
+
+
+class ValidationError(ExceptionGroup[FieldValidationError]):
+    """
+    Group of schema validation errors.
+    """
+
+    @property
+    def exceptions(self) -> tuple[FieldValidationError, ...]:
+        """
+        Field validation errors.
+        Contains no nested groups.
+        """
+
+        return cast("tuple[FieldValidationError, ...]", super().exceptions)

schemmy-0.1.0/src/schemmy/schema.py

@@ -0,0 +1,651 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from types import NoneType, UnionType
+from typing import (
+    TYPE_CHECKING,
+    Annotated,
+    Any,
+    ClassVar,
+    Literal,
+    Union,
+    dataclass_transform,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
+
+from schemmy.exceptions import FieldValidationError, ValidationError
+
+if TYPE_CHECKING:
+    from types import EllipsisType
+    from typing import Self
+
+
+type FieldName = str
+type FieldValue = Any
+
+type FieldsMapping = dict[FieldName, FieldValue]
+type TypeHintsMapping = dict[FieldName, Any]
+
+
+def _type_repr(annotation: Any) -> str:
+    """
+    Returns a readable name of an annotation for error messages.
+    Unions are written as X | Y.
+    Annotated metadata is omitted.
+    """
+
+    if annotation is NoneType:
+        return "None"
+
+    if annotation is Ellipsis:
+        return "..."
+
+    origin = get_origin(annotation)
+    args = get_args(annotation)
+
+    if origin is Union or origin is UnionType:
+        return " | ".join(_type_repr(arg) for arg in args)
+
+    if origin is Annotated:
+        return _type_repr(args[0])
+
+    if origin is not None:
+        return f"{_type_repr(origin)}[{', '.join(_type_repr(arg) for arg in args)}]"
+
+    if isinstance(annotation, type):
+        return annotation.__name__
+
+    return repr(annotation).removeprefix("typing.")
+
+
+def _dump(value: Any) -> Any:
+    """
+    Converts schemas inside a value to dicts.
+    Lists, tuples and dicts are traversed recursively.
+    Other values are returned unchanged.
+    """
+
+    if isinstance(value, Schema):
+        return value.to_dict()
+
+    if isinstance(value, list):
+        return [_dump(item) for item in value]
+
+    if isinstance(value, tuple):
+        return tuple(_dump(item) for item in value)
+
+    if isinstance(value, dict):
+        return {key: _dump(item) for key, item in value.items()}
+
+    return value
+
+
+@dataclass_transform(kw_only_default=True)
+class Schema:
+    """
+    Base class for data schemas described with type annotations.
+    Validates and normalizes input data on instantiation.
+    Type checkers derive the constructor signature from the field annotations.
+    """
+
+    _schemmy_fields: ClassVar[tuple[TypeHintsMapping, FieldsMapping]]
+    _origin_resolvers: ClassVar[dict[Any, str]] = {
+        Annotated: "_resolve_validators",
+        Union: "_resolve_union_type",
+        UnionType: "_resolve_union_type",
+        Literal: "_resolve_literal_type",
+        list: "_resolve_list_type",
+        tuple: "_resolve_tuple_type",
+        dict: "_resolve_dict_type",
+    }
+
+    def __init__(self, **fields: FieldValue) -> None:
+        """
+        Validates the fields and sets them as instance attributes.
+
+        :raise ValidationError: Schema validation failed.
+        """
+
+        values, errors = type(self)._run_validation(fields)
+
+        for k, v in values.items():
+            setattr(self, k, v)
+
+        if errors:
+            raise ValidationError(f"{type(self).__name__}: validation failed", errors)
+
+    def __repr__(self) -> str:
+        type_hints, _ = type(self)._get_fields()
+        fields = ", ".join(f"{name}={getattr(self, name)!r}" for name in type_hints)
+        return f"{type(self).__name__}({fields})"
+
+    def __eq__(self, other: object) -> bool:
+        if type(other) is not type(self):
+            return NotImplemented
+        type_hints, _ = type(self)._get_fields()
+        return all(getattr(self, name) == getattr(other, name) for name in type_hints)
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Returns field values as a dict in field declaration order.
+        Nested schemas are converted to dicts.
+        Lists, tuples and dicts are traversed recursively.
+        """
+
+        type_hints, _ = type(self)._get_fields()
+        return {name: _dump(getattr(self, name)) for name in type_hints}
+
+    @classmethod
+    def validate(cls, fields: FieldsMapping) -> Self:
+        """
+        Validates a mapping and returns a schema instance.
+
+        :raise ValidationError: Schema validation failed.
+        """
+
+        non_str_keys = [key for key in fields if not isinstance(key, str)]
+        if non_str_keys:
+            raise ValidationError(
+                f"{cls.__name__}: validation failed",
+                [
+                    FieldValidationError(
+                        field=repr(key),
+                        message="Field name must be a string",
+                        location=[repr(key)],
+                    )
+                    for key in non_str_keys
+                ],
+            )
+
+        return cls(**fields)
+
+    @classmethod
+    def _get_fields(cls) -> tuple[TypeHintsMapping, FieldsMapping]:
+        """
+        Returns field annotations and field default values.
+        ClassVar annotations are not fields.
+        The result is cached on the schema class.
+
+        :returns: Field annotations, default values
+        """
+
+        cached = cls.__dict__.get("_schemmy_fields")
+        if cached is not None:
+            return cached
+
+        type_hints: TypeHintsMapping = {
+            name: hint
+            for name, hint in get_type_hints(cls, include_extras=True).items()
+            if hint is not ClassVar and get_origin(hint) is not ClassVar
+        }
+
+        defaults: FieldsMapping = {}
+        for klass in reversed(cls.__mro__):
+            if klass is Schema or not issubclass(klass, Schema):
+                continue
+            for name in type_hints:
+                if name in klass.__dict__:
+                    defaults[name] = klass.__dict__[name]
+
+        cls._schemmy_fields = (type_hints, defaults)
+        return cls._schemmy_fields
+
+    @classmethod
+    def _run_validation(cls, fields: FieldsMapping) -> tuple[FieldsMapping, list[FieldValidationError]]:
+        """
+        Validates and normalizes input data against the schema annotations.
+        Missing and unknown fields are reported first.
+        Value errors follow in field declaration order.
+
+        :returns: Normalized values, validation errors
+        """
+
+        errors: list[FieldValidationError] = []
+        type_hints, defaults = cls._get_fields()
+
+        errors += cls._validate_missing_fields(fields, type_hints, defaults)
+        errors += cls._validate_disallowed_fields(fields, type_hints)
+
+        validated_fields, fields_errors = cls._validate_allowed_fields(fields, type_hints)
+        errors += fields_errors
+
+        for field, default in defaults.items():
+            if field not in fields:
+                validated_fields[field] = deepcopy(default)
+
+        return validated_fields, errors
+
+    @staticmethod
+    def _validate_missing_fields(
+        fields: FieldsMapping, type_hints: TypeHintsMapping, defaults: FieldsMapping
+    ) -> list[FieldValidationError]:
+        """
+        Reports required fields absent from the input.
+        A field with a default value is not required.
+
+        :returns: Validation errors
+        """
+
+        return [
+            FieldValidationError(
+                field=field,
+                message="Field required",
+                location=[field],
+            )
+            for field in type_hints
+            if field not in fields and field not in defaults
+        ]
+
+    @staticmethod
+    def _validate_disallowed_fields(fields: FieldsMapping, type_hints: TypeHintsMapping) -> list[FieldValidationError]:
+        """
+        Reports input fields not declared in the schema.
+
+        :returns: Validation errors
+        """
+
+        return [
+            FieldValidationError(
+                field=field,
+                message="Unknown field",
+                location=[field],
+            )
+            for field in fields
+            if field not in type_hints
+        ]
+
+    @classmethod
+    def _validate_allowed_fields(
+        cls, fields: FieldsMapping, type_hints: TypeHintsMapping
+    ) -> tuple[FieldsMapping, list[FieldValidationError]]:
+        """
+        Validates the values of declared fields present in the input.
+
+        :returns: Normalized values, validation errors
+        """
+
+        errors: list[FieldValidationError] = []
+        allowed_fields = [field for field in type_hints if field in fields]
+        validated_fields: FieldsMapping = {}
+
+        for field in allowed_fields:
+            value = fields[field]
+            expected_type = type_hints[field]
+
+            validated_value, validation_errors = cls._check_field_type(field, value, expected_type)
+
+            validated_fields[field] = validated_value
+            errors += validation_errors
+
+        return validated_fields, errors
+
+    @classmethod
+    def _check_field_type(
+        cls, field: FieldName, value: FieldValue, expected_type: Any
+    ) -> tuple[FieldValue | EllipsisType, list[FieldValidationError]]:
+        """
+        Dispatches a value to the resolver for its annotation.
+        Supported annotations are Any, Annotated, unions, Literal, list, tuple, dict, Schema subclasses and plain classes.
+        A value that fails validation is replaced with ellipsis.
+
+        :returns: Normalized value, validation errors
+        """
+
+        origin = get_origin(expected_type)
+
+        if expected_type is Any:
+            return cls._resolve_any_type(field, value, expected_type)
+
+        resolver_name = cls._origin_resolvers.get(origin)
+        if resolver_name is not None:
+            return getattr(cls, resolver_name)(field, value, expected_type)
+
+        if origin is not None or not isinstance(expected_type, type):
+            return cls._resolve_unsupported_type(field, value, expected_type)
+
+        if issubclass(expected_type, Schema):
+            return cls._resolve_schema_type(field, value, expected_type)
+
+        if expected_type is float and type(value) is int:
+            return cls._resolve_int_as_float(field, value)
+
+        # bool is a subclass of int but is rejected for int fields.
+        if not isinstance(value, expected_type) or (expected_type is int and isinstance(value, bool)):
+            return cls._resolve_scalar_type(field, value, expected_type)
+
+        return value, []
+
+    @classmethod
+    def _resolve_any_type(
+        cls, field: FieldName, value: FieldValue, expected_type: Any
+    ) -> tuple[FieldValue | EllipsisType, list[FieldValidationError]]:
+        """
+        Resolver for Any.
+        The value is returned unchanged.
+        No errors are produced.
+
+        :returns: Normalized value, validation errors
+        """
+
+        return value, []
+
+    @classmethod
+    def _resolve_int_as_float(
+        cls, field: FieldName, value: int
+    ) -> tuple[FieldValue | EllipsisType, list[FieldValidationError]]:
+        """
+        Resolver for an int passed to a float field.
+        JSON numbers without a fractional part arrive as int.
+        The int is converted only when float represents it exactly.
+        bool is not converted.
+
+        :returns: Normalized value, validation errors
+        """
+
+        try:
+            converted = float(value)
+        except OverflowError:
+            converted = None
+
+        if converted is None or converted != value:
+            return ..., [
+                FieldValidationError(
+                    field=field,
+                    message=f"Expected float, got int {value} that float cannot represent exactly",
+                    location=[field],
+                )
+            ]
+
+        return converted, []
+
+    @classmethod
+    def _resolve_union_type(
+        cls, field: FieldName, value: FieldValue, expected_type: Any
+    ) -> tuple[FieldValue | EllipsisType, list[FieldValidationError]]:
+        """
+        Resolver for unions such as X | Y and Optional[X].
+        None members are skipped for a value other than None.
+        A single remaining member validates the value directly and reports its own errors.
+        Otherwise members are tried in declaration order and the first match wins.
+
+        :returns: Normalized value, validation errors
+        """
+
+        members = [member for member in get_args(expected_type) if value is None or member is not NoneType]
+
+        if len(members) == 1:
+            return cls._check_field_type(field, value, members[0])
+
+        for member in members:
+            validated_value, errors = cls._check_field_type(field, value, member)
+            if not errors:
+                return validated_value, []
+
+        return ..., [
+            FieldValidationError(
+                field=field,
+                message=f"Expected {_type_repr(expected_type)}, got {type(value).__name__}",
+                location=[field],
+            )
+        ]
+
+    @classmethod
+    def _resolve_literal_type(
+        cls, field: FieldName, value: FieldValue, expected_type: Any
+    ) -> tuple[FieldValue | EllipsisType, list[FieldValidationError]]:
+        """
+        Resolver for Literal[...].
+        The value must equal one of the literals and have the same type.
+        The type check keeps True from matching Literal[1].
+
+        :returns: Normalized value, validation errors
+        """
+
+        for literal in get_args(expected_type):
+            if type(value) is type(literal) and value == literal:
+                return value, []
+
+        return ..., [
+            FieldValidationError(
+                field=field,
+                message=f"Expected {_type_repr(expected_type)}, got {value!r}",
+                location=[field],
+            )
+        ]
+
+    @classmethod
+    def _resolve_list_type(
+        cls, field: FieldName, value: FieldValue, expected_type: Any
+    ) -> tuple[FieldValue | EllipsisType, list[FieldValidationError]]:
+        """
+        Resolver for list[T].
+        The value must be a list.
+        Each item is validated against T.
+
+        :returns: Normalized value, validation errors
+        """
+
+        if not isinstance(value, list):
+            return cls._resolve_scalar_type(field, value, expected_type)
+
+        item_type = get_args(expected_type)[0]
+        return cls._validate_items(field, value, [item_type] * len(value))
+
+    @classmethod
+    def _resolve_tuple_type(
+        cls, field: FieldName, value: FieldValue, expected_type: Any
+    ) -> tuple[FieldValue | EllipsisType, list[FieldValidationError]]:
+        """
+        Resolver for tuple[T, ...] and tuple[T1, T2, ...].
+        The value must be a tuple or a list.
+        A list is converted to a tuple, because JSON has no tuples.
+        tuple[T, ...] validates each item against T.
+        tuple[T1, T2, ...] requires the exact number of items.
+
+        :returns: Normalized value, validation errors
+        """
+
+        if not isinstance(value, tuple | list):
+            return cls._resolve_scalar_type(field, value, expected_type)
+
+        args = get_args(expected_type)
+
+        if len(args) == 2 and args[1] is Ellipsis:
+            item_types = [args[0]] * len(value)
+        elif len(args) == len(value):
+            item_types = list(args)
+        else:
+            return ..., [
+                FieldValidationError(
+                    field=field,
+                    message=f"Expected {_type_repr(expected_type)} with {len(args)} items, got {len(value)}",
+                    location=[field],
+                )
+            ]
+
+        validated_items, errors = cls._validate_items(field, value, item_types)
+        if errors:
+            return ..., errors
+
+        return tuple(validated_items), []
+
+    @classmethod
+    def _resolve_dict_type(
+        cls, field: FieldName, value: FieldValue, expected_type: Any
+    ) -> tuple[FieldValue | EllipsisType, list[FieldValidationError]]:
+        """
+        Resolver for dict[K, V].
+        The value must be a dict.
+        Each key is validated against K and each value against V.
+        The key is added to the location of key and value errors.
+        Key error messages start with "Invalid key".
+
+        :returns: Normalized value, validation errors
+        """
+
+        if not isinstance(value, dict):
+            return cls._resolve_scalar_type(field, value, expected_type)
+
+        key_type, value_type = get_args(expected_type)
+        validated_dict: dict[Any, Any] = {}
+        errors: list[FieldValidationError] = []
+
+        for key, item in value.items():
+            location_key = key if isinstance(key, str | int) else repr(key)
+
+            validated_key, key_errors = cls._check_field_type(field, key, key_type)
+            for error in key_errors:
+                error.message = f"Invalid key: {error.message}"
+                error.location.insert(1, location_key)
+            errors.extend(key_errors)
+
+            validated_item, item_errors = cls._check_field_type(field, item, value_type)
+            for error in item_errors:
+                error.location.insert(1, location_key)
+            errors.extend(item_errors)
+
+            if not key_errors and not item_errors:
+                validated_dict[validated_key] = validated_item
+
+        if errors:
+            return ..., errors
+
+        return validated_dict, []
+
+    @classmethod
+    def _validate_items(
+        cls, field: FieldName, items: list[Any] | tuple[Any, ...], item_types: list[Any]
+    ) -> tuple[list[Any], list[FieldValidationError]]:
+        """
+        Validates items of a sequence against their types.
+        The item index is added to the location of item errors.
+        A failed item is replaced with ellipsis.
+
+        :returns: Normalized items, validation errors
+        """
+
+        validated_items: list[Any] = []
+        errors: list[FieldValidationError] = []
+
+        for index, (item, item_type) in enumerate(zip(items, item_types, strict=True)):
+            validated_item, item_errors = cls._check_field_type(field, item, item_type)
+            for error in item_errors:
+                error.location.insert(1, index)
+            errors.extend(item_errors)
+            validated_items.append(... if item_errors else validated_item)
+
+        return validated_items, errors
+
+    @classmethod
+    def _resolve_unsupported_type(
+        cls, field: FieldName, value: FieldValue, expected_type: Any
+    ) -> tuple[FieldValue | EllipsisType, list[FieldValidationError]]:
+        """
+        Resolver for annotations without support, such as set and TypedDict.
+        Always produces a single error.
+
+        :returns: Normalized value, validation errors
+        """
+
+        return ..., [
+            FieldValidationError(
+                field=field,
+                message=f"Unsupported type: {_type_repr(expected_type)}",
+                location=[field],
+            )
+        ]
+
+    @classmethod
+    def _resolve_schema_type(
+        cls, field: FieldName, value: FieldValue, expected_type: Any
+    ) -> tuple[FieldValue | EllipsisType, list[FieldValidationError]]:
+        """
+        Resolver for nested Schema subclasses.
+        An instance of the expected schema is returned unchanged.
+        A dict is validated through expected_type.validate.
+        The current field is prepended to the location of nested errors.
+
+        :returns: Normalized value, validation errors
+        """
+
+        if isinstance(value, expected_type):
+            return value, []
+
+        if isinstance(value, dict):
+            try:
+                return expected_type.validate(value), []
+            except ValidationError as exc:
+                return ..., [
+                    FieldValidationError(
+                        field=error.field,
+                        message=error.message,
+                        location=[field, *error.location],
+                    )
+                    for error in exc.exceptions
+                ]
+
+        return ..., [
+            FieldValidationError(
+                field=field,
+                message=f"Expected dict or {expected_type.__name__}, got {type(value).__name__}",
+                location=[field],
+            )
+        ]
+
+    @classmethod
+    def _resolve_scalar_type(
+        cls, field: FieldName, value: FieldValue, expected_type: Any
+    ) -> tuple[FieldValue | EllipsisType, list[FieldValidationError]]:
+        """
+        Resolver for a value that does not match a plain class annotation.
+        Always produces a single error with the expected and actual types.
+
+        :returns: Normalized value, validation errors
+        """
+
+        return ..., [
+            FieldValidationError(
+                field=field,
+                message=f"Expected {_type_repr(expected_type)}, got {type(value).__name__}",
+                location=[field],
+            )
+        ]
+
+    @classmethod
+    def _resolve_validators(
+        cls, field: FieldName, value: FieldValue, expected_type: Any
+    ) -> tuple[FieldValue | EllipsisType, list[FieldValidationError]]:
+        """
+        Resolver for Annotated[T, *validators].
+        The value is checked against T first.
+        Validators run in order, each receives the result of the previous one.
+
+        :returns: Normalized value, validation errors
+        """
+
+        base_type, *validators = get_args(expected_type)
+        value, errors = cls._check_field_type(field, value, base_type)
+
+        if errors:
+            return ..., errors
+
+        validator_errors: list[FieldValidationError] = []
+        for validator in validators:
+            try:
+                value = validator(value)
+            except Exception as exc:
+                validator_name = getattr(validator, "__name__", type(validator).__name__)
+                validator_errors.append(
+                    FieldValidationError(
+                        field=field,
+                        message=f"Validator {validator_name} failed: {exc}",
+                        location=[field],
+                    )
+                )
+
+        if validator_errors:
+            return ..., validator_errors
+
+        return value, []