sysfce2 · pull · Feb 28, 2026 · Feb 27, 2026 · Feb 27, 2026 · Feb 28, 2026
diff --git a/Dockerfile b/Dockerfile
@@ -1,4 +1,4 @@
-ARG OPENAPI_SPEC_VALIDATOR_VERSION=0.8.2
+ARG OPENAPI_SPEC_VALIDATOR_VERSION=0.8.3
 
 FROM python:3.14.3-alpine as builder
 

diff --git a/README.rst b/README.rst
@@ -86,7 +86,7 @@ pre-commit hook
 
    repos:
    -   repo: https://github.com/python-openapi/openapi-spec-validator
-       rev: 0.8.2 # The version to use or 'master' for latest
+       rev: 0.8.3 # The version to use or 'master' for latest
        hooks:
        -   id: openapi-spec-validator
 
@@ -116,6 +116,21 @@ Python package
 
 For more details, read about `Python package <https://openapi-spec-validator.readthedocs.io/en/latest/python.html>`__.
 
+Performance tuning
+******************
+
+You can tune resolved-path caching with an environment variable:
+
+.. code-block:: bash
+
+    OPENAPI_SPEC_VALIDATOR_RESOLVED_CACHE_MAXSIZE=2048
+
+Rules:
+
+* Default is ``128``.
+* Set ``0`` to disable the resolved cache.
+* Invalid values (non-integer or negative) fall back to ``128``.
+
 Related projects
 ################
 

diff --git a/docs/cli.rst b/docs/cli.rst
@@ -68,3 +68,8 @@ CLI (Command Line Interface)
 Legacy note:
    ``--errors`` / ``--error`` are deprecated and emit warnings by default.
    Set ``OPENAPI_SPEC_VALIDATOR_WARN_DEPRECATED=0`` to silence warnings.
+
+Performance note:
+   You can tune resolved-path caching with
+   ``OPENAPI_SPEC_VALIDATOR_RESOLVED_CACHE_MAXSIZE``.
+   Default is ``128``; set ``0`` to disable.
diff --git a/docs/hook.rst b/docs/hook.rst
@@ -16,7 +16,7 @@ A full .pre-commit-config.yaml example you can use in your repository:
 
    repos:
    -   repo: https://github.com/python-openapi/openapi-spec-validator
-       rev: 0.8.2 # The version to use or 'master' for latest
+       rev: 0.8.3 # The version to use or 'master' for latest
        hooks:
        -   id: openapi-spec-validator
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -82,7 +82,7 @@ Usage
 
          repos:
          -   repo: https://github.com/python-openapi/openapi-spec-validator
-             rev: 0.8.2 # The version to use or 'master' for latest
+             rev: 0.8.3 # The version to use or 'master' for latest
              hooks:
              -   id: openapi-spec-validator
 

diff --git a/docs/python.rst b/docs/python.rst
@@ -59,3 +59,19 @@ If you want to iterate through validation errors:
     from openapi_spec_validator import OpenAPIV32SpecValidator
 
     errors_iterator = OpenAPIV32SpecValidator(spec).iter_errors()
+
+Resolved path cache
+-------------------
+
+``openapi-spec-validator`` can configure the ``jsonschema-path`` resolved
+path cache through an environment variable:
+
+.. code-block:: bash
+
+   OPENAPI_SPEC_VALIDATOR_RESOLVED_CACHE_MAXSIZE=2048
+
+Rules:
+
+* Default is ``128``.
+* Set ``0`` to disable the resolved cache.
+* Invalid values (non-integer or negative) fall back to ``128``.
diff --git a/openapi_spec_validator/__init__.py b/openapi_spec_validator/__init__.py
@@ -17,7 +17,7 @@
 
 __author__ = "Artur Maciag"
 __email__ = "maciag.artur@gmail.com"
-__version__ = "0.8.2"
+__version__ = "0.8.3"
 __url__ = "https://github.com/python-openapi/openapi-spec-validator"
 __license__ = "Apache License, Version 2.0"
 

diff --git a/openapi_spec_validator/settings.py b/openapi_spec_validator/settings.py
@@ -0,0 +1,43 @@
+from pydantic import field_validator
+from pydantic_settings import BaseSettings
+from pydantic_settings import SettingsConfigDict
+
+ENV_PREFIX = "OPENAPI_SPEC_VALIDATOR_"
+RESOLVED_CACHE_MAXSIZE_DEFAULT = 128
+
+
+class OpenAPISpecValidatorSettings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix=ENV_PREFIX,
+        extra="ignore",
+    )
+
+    resolved_cache_maxsize: int = RESOLVED_CACHE_MAXSIZE_DEFAULT
+
+    @field_validator("resolved_cache_maxsize", mode="before")
+    @classmethod
+    def normalize_resolved_cache_maxsize(
+        cls, value: int | str | None
+    ) -> int:
+        if value is None:
+            return RESOLVED_CACHE_MAXSIZE_DEFAULT
+
+        if isinstance(value, int):
+            parsed_value = value
+        elif isinstance(value, str):
+            try:
+                parsed_value = int(value)
+            except ValueError:
+                return RESOLVED_CACHE_MAXSIZE_DEFAULT
+        else:
+            return RESOLVED_CACHE_MAXSIZE_DEFAULT
+
+        if parsed_value < 0:
+            return RESOLVED_CACHE_MAXSIZE_DEFAULT
+
+        return parsed_value
+
+
+def get_resolved_cache_maxsize() -> int:
+    settings = OpenAPISpecValidatorSettings()
+    return settings.resolved_cache_maxsize
diff --git a/openapi_spec_validator/shortcuts.py b/openapi_spec_validator/shortcuts.py
@@ -7,6 +7,7 @@
 from jsonschema_path.handlers import all_urls_handler
 from jsonschema_path.typing import Schema
 
+from openapi_spec_validator.settings import OpenAPISpecValidatorSettings
 from openapi_spec_validator.validation import OpenAPIV2SpecValidator
 from openapi_spec_validator.validation import OpenAPIV30SpecValidator
 from openapi_spec_validator.validation import OpenAPIV31SpecValidator
@@ -44,7 +45,12 @@ def validate(
 ) -> None:
     if cls is None:
         cls = get_validator_cls(spec)
-    sp = SchemaPath.from_dict(spec, base_uri=base_uri)
+    settings = OpenAPISpecValidatorSettings()
+    sp = SchemaPath.from_dict(
+        spec,
+        base_uri=base_uri,
+        resolved_cache_maxsize=settings.resolved_cache_maxsize,
+    )
     v = cls(sp)
     return v.validate()
 

diff --git a/openapi_spec_validator/validation/validators.py b/openapi_spec_validator/validation/validators.py
@@ -17,6 +17,7 @@
 from openapi_spec_validator.schemas import openapi_v31_schema_validator
 from openapi_spec_validator.schemas import openapi_v32_schema_validator
 from openapi_spec_validator.schemas.types import AnySchema
+from openapi_spec_validator.settings import OpenAPISpecValidatorSettings
 from openapi_spec_validator.validation import keywords
 from openapi_spec_validator.validation.decorators import unwraps_iter
 from openapi_spec_validator.validation.decorators import wraps_cached_iter
@@ -54,11 +55,13 @@ def __init__(
             self.schema_path = schema
             self.schema = schema.read_value()
         else:
+            settings = OpenAPISpecValidatorSettings()
             self.schema = schema
             self.schema_path = SchemaPath.from_dict(
                 self.schema,
                 base_uri=self.base_uri,
                 handlers=self.resolver_handlers,
+                resolved_cache_maxsize=settings.resolved_cache_maxsize,
             )
 
         self.keyword_validators_registry = KeywordValidatorRegistry(

diff --git a/poetry.lock b/poetry.lock
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "openapi-spec-validator"
-version = "0.8.2"
+version = "0.8.3"
 description = "OpenAPI 2.0 (aka Swagger) and OpenAPI 3 spec validator"
 authors = [
     { name = "Artur Maciag", email = "maciag.artur@gmail.com" },
@@ -26,8 +26,10 @@ classifiers = [
 dependencies = [
     "jsonschema >=4.24.0,<4.25.0",
     "openapi-schema-validator >=0.7.3,<0.9.0",
-    "jsonschema-path >=0.4.2,<0.5.0",
+    "jsonschema-path >=0.4.3,<0.5.0",
     "lazy-object-proxy >=1.7.1,<2.0",
+    "pydantic-settings (>=2.0.0,<3.0.0)",
+    "pydantic (>=2.0.0,<3.0.0)",
 ]
 
 [project.urls]
@@ -118,7 +120,7 @@ message_template = "Version {new_version}"
 tag_template = "{new_version}"
 
 [tool.tbump.version]
-current = "0.8.2"
+current = "0.8.3"
 regex = '''
   (?P<major>\d+)
   \.