Document validate signature

README.rst

@@ -50,7 +50,18 @@ Alternatively you can download the code and install from the repository:
 Usage
 #####
 
-To validate an OpenAPI v3.1 schema:
+``validate`` call signature is:
+
+.. code-block:: python
+
+   validate(instance, schema, cls=OAS32Validator, **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.
+
+To validate an OpenAPI schema:
 
 .. code-block:: python
 
@@ -100,6 +111,9 @@ To validate an OpenAPI v3.1 schema:
 
 By default, the latest OpenAPI schema syntax is expected.
 
+Default dialect resolution
+--------------------------
+
 The OpenAPI 3.1 and 3.2 base dialect URIs are registered for
 ``jsonschema.validators.validator_for`` resolution.
 Schemas declaring ``"$schema"`` as either

docs/validation.rst

@@ -6,7 +6,18 @@ The simplest way to validate an instance under OAS schema is to use the ``valida
 Validate
 --------
 
-To validate an OpenAPI v3.1 schema:
+``validate`` call signature is:
+
+.. code-block:: python
+
+   validate(instance, schema, cls=OAS32Validator, **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.
+
+To validate an OpenAPI schema:
 
 .. code-block:: python
 
@@ -56,6 +67,17 @@ To validate an OpenAPI v3.1 schema:
 
 By default, the latest OpenAPI schema syntax is expected.
 
+Common pitfalls
+---------------
+
+- argument order matters: call ``validate(instance, schema)``, not
+  ``validate(schema, instance)``
+- ``validate`` does not load files from a path; load your OpenAPI document
+  first and pass the parsed schema mapping
+- when validating a schema fragment that uses ``$ref`` (for example,
+  ``paths/.../responses/.../schema``), provide reference context via
+  ``registry=...`` as shown in :doc:`references`
+
 Validators
 ----------
 
@@ -67,32 +89,6 @@ if you want to disambiguate the expected schema version, import and use ``OAS31V
 
    validate({"name": "John", "age": 23}, schema, cls=OAS31Validator)
 
-The OpenAPI 3.1 and 3.2 base dialect URIs are registered for
-``jsonschema.validators.validator_for`` resolution.
-If your schema declares
-``"$schema": "https://spec.openapis.org/oas/3.1/dialect/base"`` or
-``"$schema": "https://spec.openapis.org/oas/3.2/dialect/2025-09-17"``,
-``validator_for`` resolves directly to ``OAS31Validator`` or
-``OAS32Validator`` without unresolved-metaschema fallback warnings.
-
-.. code-block:: python
-
-   from jsonschema.validators import validator_for
-
-   from openapi_schema_validator import OAS31Validator
-   from openapi_schema_validator import OAS32Validator
-
-   schema = {
-       "$schema": "https://spec.openapis.org/oas/3.1/dialect/base",
-       "type": "object",
-   }
-   schema32 = {
-       "$schema": "https://spec.openapis.org/oas/3.2/dialect/2025-09-17",
-       "type": "object",
-   }
-   assert validator_for(schema) is OAS31Validator
-   assert validator_for(schema32) is OAS32Validator
-
 For OpenAPI 3.2, use ``OAS32Validator``.
 
 In order to validate OpenAPI 3.0 schema, import and use ``OAS30Validator`` instead of ``OAS31Validator``.
@@ -127,6 +123,35 @@ In order to validate OpenAPI 3.0 schema, import and use ``OAS30Validator`` inste
 
    validate({"name": "John", "age": None}, schema, cls=OAS30Validator)
 
+Default dialect resolution
+--------------------------
+
+The OpenAPI 3.1 and 3.2 base dialect URIs are registered for
+``jsonschema.validators.validator_for`` resolution.
+If your schema declares
+``"$schema": "https://spec.openapis.org/oas/3.1/dialect/base"`` or
+``"$schema": "https://spec.openapis.org/oas/3.2/dialect/2025-09-17"``,
+``validator_for`` resolves directly to ``OAS31Validator`` or
+``OAS32Validator`` without unresolved-metaschema fallback warnings.
+
+.. code-block:: python
+
+   from jsonschema.validators import validator_for
+
+   from openapi_schema_validator import OAS31Validator
+   from openapi_schema_validator import OAS32Validator
+
+   schema = {
+       "$schema": "https://spec.openapis.org/oas/3.1/dialect/base",
+       "type": "object",
+   }
+   schema32 = {
+       "$schema": "https://spec.openapis.org/oas/3.2/dialect/2025-09-17",
+       "type": "object",
+   }
+   assert validator_for(schema) is OAS31Validator
+   assert validator_for(schema32) is OAS32Validator
+
 Schema errors vs instance errors
 --------------------------------
 

openapi_schema_validator/shortcuts.py

@@ -26,6 +26,17 @@ def validate(
     checks schema validity first.
     Invalid schemas therefore raise ``SchemaError`` before any instance
     validation occurs.
+
+    Args:
+        instance: Value to validate against ``schema``.
+        schema: OpenAPI schema mapping used for validation.
+        cls: Validator class to use. Defaults to ``OAS32Validator``.
+        *args: Positional arguments forwarded to ``cls`` constructor.
+        **kwargs: Keyword arguments forwarded to ``cls`` constructor.
+
+    Raises:
+        jsonschema.exceptions.SchemaError: If ``schema`` is invalid.
+        jsonschema.exceptions.ValidationError: If ``instance`` is invalid.
     """
     schema_dict = cast(dict[str, Any], schema)