diff --git a/README.rst b/README.rst index ff03015..60ebffe 100644 --- a/README.rst +++ b/README.rst @@ -60,6 +60,8 @@ 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. +Common forwarded keyword arguments include ``registry`` (reference context) +and ``format_checker`` (format validation behavior). To validate an OpenAPI schema: diff --git a/docs/references.rst b/docs/references.rst index c6bc1f8..f446bda 100644 --- a/docs/references.rst +++ b/docs/references.rst @@ -1,7 +1,9 @@ References ========== -You can resolve JSON Schema references by passing registry +You can resolve JSON Schema references by passing registry. +The ``validate(instance, schema, ...)`` shortcut resolves local references +(``#/...``) against the provided ``schema`` mapping. .. code-block:: python diff --git a/docs/validation.rst b/docs/validation.rst index 5470407..f30c61e 100644 --- a/docs/validation.rst +++ b/docs/validation.rst @@ -16,6 +16,10 @@ 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. +Common forwarded keyword arguments include: + +- ``registry`` for reference resolution context +- ``format_checker`` to control format validation behavior To validate an OpenAPI schema: @@ -74,9 +78,13 @@ Common pitfalls ``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` +- ``validate`` treats the provided ``schema`` as the reference root; local + references like ``#/components/...`` must exist within that mapping +- when a schema uses external references (for example ``urn:...``), provide + reference context via ``registry=...`` as shown in :doc:`references` +- for schema fragments containing local references (for example, + ``paths/.../responses/.../schema``), use a validator built from the full + schema root and then validate the fragment via ``validator.evolve(...)`` Validators ---------- diff --git a/openapi_schema_validator/shortcuts.py b/openapi_schema_validator/shortcuts.py index 9d796b4..3ab498f 100644 --- a/openapi_schema_validator/shortcuts.py +++ b/openapi_schema_validator/shortcuts.py @@ -29,10 +29,12 @@ def validate( Args: instance: Value to validate against ``schema``. - schema: OpenAPI schema mapping used for validation. + schema: OpenAPI schema mapping used for validation. Local references + (``#/...``) are resolved against this mapping. cls: Validator class to use. Defaults to ``OAS32Validator``. *args: Positional arguments forwarded to ``cls`` constructor. - **kwargs: Keyword arguments forwarded to ``cls`` constructor. + **kwargs: Keyword arguments forwarded to ``cls`` constructor + (for example ``registry`` and ``format_checker``). Raises: jsonschema.exceptions.SchemaError: If ``schema`` is invalid.