sysfce2 · pull · Feb 26, 2026 · Feb 26, 2026 · Feb 26, 2026 · Feb 26, 2026
diff --git a/.github/workflows/docs-build.yml b/.github/workflows/docs-build.yml
@@ -23,6 +23,8 @@ jobs:
 
       - name: Set up poetry
         uses: Gr1N/setup-poetry@v9
+        with:
+          poetry-version: "2.1.1"
 
       - name: Configure poetry
         run: poetry config virtualenvs.in-project true

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -6,12 +6,13 @@ sphinx:
 formats: all
 
 build:
-  os: ubuntu-20.04
+  os: ubuntu-24.04
   tools:
     python: "3.10"
   jobs:
     post_create_environment:
-      - pip install poetry
+      - pip install "poetry==2.1.1"
       - poetry config virtualenvs.create false
     post_install:
-      - poetry install --with docs
+      - poetry install --with docs --no-interaction --no-ansi
+      - python -m pip install --no-cache-dir "sphinx-immaterial>=0.11,<0.14"
diff --git a/README.rst b/README.rst
@@ -3,22 +3,22 @@ openapi-schema-validator
 ************************
 
 .. image:: https://img.shields.io/pypi/v/openapi-schema-validator.svg
-     :target: https://pypi.python.org/pypi/openapi-schema-validator
+     :target: https://pypi.org/project/openapi-schema-validator/
 .. image:: https://github.com/python-openapi/openapi-schema-validator/actions/workflows/python-tests.yml/badge.svg
      :target: https://github.com/python-openapi/openapi-schema-validator/actions
 .. image:: https://img.shields.io/codecov/c/github/python-openapi/openapi-schema-validator/master.svg?style=flat
      :target: https://codecov.io/github/python-openapi/openapi-schema-validator?branch=master
 .. image:: https://img.shields.io/pypi/pyversions/openapi-schema-validator.svg
-     :target: https://pypi.python.org/pypi/openapi-schema-validator
+     :target: https://pypi.org/project/openapi-schema-validator/
 .. image:: https://img.shields.io/pypi/format/openapi-schema-validator.svg
-     :target: https://pypi.python.org/pypi/openapi-schema-validator
+     :target: https://pypi.org/project/openapi-schema-validator/
 .. image:: https://img.shields.io/pypi/status/openapi-schema-validator.svg
-     :target: https://pypi.python.org/pypi/openapi-schema-validator
+     :target: https://pypi.org/project/openapi-schema-validator/
 
 About
 #####
 
-Openapi-schema-validator is a Python library that validates schema against:
+openapi-schema-validator is a Python library that validates schemas against:
 
 * `OpenAPI Schema Specification v3.0 <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schemaObject>`__ which is an extended subset of the `JSON Schema Specification Wright Draft 00 <http://json-schema.org/>`__.
 * `OpenAPI Schema Specification v3.1 <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#schemaObject>`__ which is an extended superset of the `JSON Schema Specification Draft 2020-12 <http://json-schema.org/>`__.
@@ -44,7 +44,7 @@ Alternatively you can download the code and install from the repository:
 
 .. code-block:: console
 
-   pip install -e git+https://github.com/python-openapi/openapi-schema-validator.git#egg=openapi_schema_validator
+   pip install "git+https://github.com/python-openapi/openapi-schema-validator.git"
 
 
 Usage
@@ -60,6 +60,22 @@ 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.
+
+.. code-block:: python
+
+   from openapi_schema_validator import OAS30Validator
+   from openapi_schema_validator import OAS31Validator
+   from openapi_schema_validator import validate
+
+   # OpenAPI 3.0 behavior
+   validate(instance, schema, cls=OAS30Validator)
+
+   # OpenAPI 3.1 behavior
+   validate(instance, schema, cls=OAS31Validator)
+
+   # OpenAPI 3.2 behavior (default)
+   validate(instance, schema)
+
 Common forwarded keyword arguments include ``registry`` (reference context)
 and ``format_checker`` (format validation behavior).
 By default, ``validate`` uses a local-only empty registry to avoid implicit
@@ -111,6 +127,10 @@ To validate an OpenAPI schema:
 
    validate({"name": "John", "city": "London"}, schema)
 
+Expected failure output:
+
+.. code-block:: text
+
    Traceback (most recent call last):
        ...
    ValidationError: Additional properties are not allowed ('city' was unexpected)
@@ -180,35 +200,6 @@ OpenAPI 3.1+ follows JSON Schema semantics for string typing in this library.
 - for raw binary payloads, model via media type (for example
   ``application/octet-stream``) rather than schema string formats
 
-Quick Reference
----------------
-
-.. list-table::
-   :header-rows: 1
-   :widths: 28 24 24 24
-
-   * - Context
-     - ``"text"`` (str)
-     - ``b"text"`` (bytes)
-     - Notes
-   * - OAS 3.0 + ``OAS30Validator``
-     - Pass
-     - Pass for ``format: binary``
-     - Compatibility behavior for Python runtime payloads
-   * - OAS 3.0 + ``OAS30StrictValidator``
-     - Pass
-     - Fail
-     - Strict 3.0 validation mode
-   * - OAS 3.1 + ``OAS31Validator``
-     - Pass
-     - Fail
-     - Use ``contentEncoding``/``contentMediaType`` and media types
-   * - OAS 3.2 + ``OAS32Validator``
-     - Pass
-     - Fail
-     - Same semantics as OAS 3.1
-
-
 Regex Behavior
 ==============
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -1,10 +1,29 @@
-import openapi_schema_validator
+import re
+import sys
+from pathlib import Path
+
+ROOT_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT_DIR))
+
+
+def _read_project_version() -> str:
+    pyproject_path = ROOT_DIR / "pyproject.toml"
+    pyproject_content = pyproject_path.read_text(encoding="utf-8")
+    match = re.search(
+        r"\[tool\.poetry\][\s\S]*?^version\s*=\s*\"([^\"]+)\"",
+        pyproject_content,
+        re.MULTILINE,
+    )
+    if match is None:
+        return "unknown"
+    return match.group(1)
+
 
 project = "openapi-schema-validator"
 copyright = "2023, Artur Maciag"
 author = "Artur Maciag"
 
-release = openapi_schema_validator.__version__
+release = _read_project_version()
 
 extensions = [
     "sphinx.ext.autodoc",

diff --git a/openapi_schema_validator/__init__.py b/openapi_schema_validator/__init__.py
@@ -14,7 +14,7 @@
 
 __author__ = "Artur Maciag"
 __email__ = "maciag.artur@gmail.com"
-__version__ = "0.7.3"
+__version__ = "0.8.0"
 __url__ = "https://github.com/python-openapi/openapi-schema-validator"
 __license__ = "3-clause BSD License"
 

diff --git a/pyproject.toml b/pyproject.toml
@@ -36,7 +36,7 @@ ignore_missing_imports = true
 github_url = "https://github.com/python-openapi/openapi-schema-validator"
 
 [tool.tbump.version]
-current = "0.7.3"
+current = "0.8.0"
 regex = '''
   (?P<major>\d+)
   \.
@@ -57,7 +57,7 @@ src = "pyproject.toml"
 
 [tool.poetry]
 name = "openapi-schema-validator"
-version = "0.7.3"
+version = "0.8.0"
 description = "OpenAPI schema validation for Python"
 authors = ["Artur Maciag <maciag.artur@gmail.com>"]
 license = "BSD-3-Clause"