Document condifuration

Author: p1c2u

README.rst

@@ -54,7 +54,14 @@ Usage
 
 .. code-block:: python
 
-   validate(instance, schema, cls=OAS32Validator, allow_remote_references=False, **kwargs)
+   validate(
+       instance,
+       schema,
+       cls=OAS32Validator,
+       allow_remote_references=False,
+       check_schema=True,
+       **kwargs,
+   )
 
 The first argument is always the value you want to validate.
 The second argument is always the OpenAPI schema object.
@@ -83,6 +90,15 @@ remote ``$ref`` retrieval. To resolve external references, pass an explicit
 ``registry``. Set ``allow_remote_references=True`` only if you explicitly
 accept jsonschema's default remote retrieval behavior.
 
+``check_schema`` defaults to ``True`` and validates the schema before
+validating an instance. For trusted pre-validated schemas in hot paths, set
+``check_schema=False`` to skip schema checking.
+
+The ``validate`` helper keeps an internal compiled-validator cache. You can
+control cache size using the
+``OPENAPI_SCHEMA_VALIDATOR_VALIDATE_CACHE_MAX_SIZE`` environment variable
+(default: ``128``).
+
 To validate an OpenAPI schema:
 
 .. code-block:: python

docs/index.rst

@@ -84,6 +84,17 @@ Usage
 
 Read more about the :doc:`validation`.
 
+Configuration
+-------------
+
+Environment variables:
+
+* ``OPENAPI_SCHEMA_VALIDATOR_VALIDATE_CACHE_MAX_SIZE``
+  Maximum number of compiled validators kept by the ``validate`` shortcut
+  cache. Default: ``128``.
+
+See :doc:`validation` for runtime behavior details.
+
 Related projects
 ----------------
 

docs/validation.rst

@@ -10,14 +10,22 @@ Validate
 
 .. code-block:: python
 
-   validate(instance, schema, cls=OAS32Validator, allow_remote_references=False, **kwargs)
+   validate(
+       instance,
+       schema,
+       cls=OAS32Validator,
+       allow_remote_references=False,
+       check_schema=True,
+       **kwargs,
+   )
 
 The first argument is always the value you want to validate.
 The second argument is always the OpenAPI schema object.
 The ``cls`` keyword argument is optional and defaults to ``OAS32Validator``.
 Use ``cls`` when you need a specific validator version/behavior.
 The ``allow_remote_references`` keyword argument is optional and defaults to
 ``False``.
+The ``check_schema`` keyword argument is optional and defaults to ``True``.
 Common forwarded keyword arguments include:
 
 - ``registry`` for explicit external reference resolution context
@@ -28,6 +36,13 @@ remote ``$ref`` retrieval.
 Set ``allow_remote_references=True`` only if you explicitly accept
 jsonschema's default remote retrieval behavior.
 
+For trusted pre-validated schemas in hot paths, set ``check_schema=False`` to
+skip schema checking.
+
+The shortcut keeps an internal compiled-validator cache.
+Use ``OPENAPI_SCHEMA_VALIDATOR_VALIDATE_CACHE_MAX_SIZE`` to control cache
+capacity (default: ``128``).
+
 To validate an OpenAPI schema:
 
 .. code-block:: python
@@ -171,10 +186,14 @@ Schema errors vs instance errors
 --------------------------------
 
 The high-level ``validate(...)`` helper checks schema validity before instance
-validation, following ``jsonschema.validate(...)`` behavior.
+validation by default (``check_schema=True``), following
+``jsonschema.validate(...)`` behavior.
 Malformed schema values (for example an invalid regex in ``pattern``) raise
 ``SchemaError``.
 
+When ``check_schema=False``, schema checking is skipped and malformed schemas
+may instead fail during validation with lower-level errors.
+
 If you instantiate a validator class directly and call ``.validate(...)``,
 schema checking is not performed automatically, matching
 ``jsonschema`` validator-class behavior.