sysfce2 · pull · Feb 26, 2026 · Feb 26, 2026 · Feb 26, 2026 · Feb 26, 2026
diff --git a/.github/workflows/python-tests.yml b/.github/workflows/python-tests.yml
@@ -62,6 +62,46 @@ jobs:
       - name: Upload coverage
         uses: codecov/codecov-action@v5
 
+  tests_no_extras:
+    name: "py3.14 no extras"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python 3.14
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+
+      - name: Get full Python version
+        id: full-python-version
+        run: echo ::set-output name=version::$(python -c "import sys; print('-'.join(str(v) for v in sys.version_info))")
+
+      - name: Set up poetry
+        uses: Gr1N/setup-poetry@v9
+
+      - name: Configure poetry
+        run: poetry config virtualenvs.in-project true
+
+      - name: Set up cache
+        uses: actions/cache@v5
+        id: cache
+        with:
+          path: .venv
+          key: venv-no-extras-${{ steps.full-python-version.outputs.version }}-${{ hashFiles('**/poetry.lock') }}
+
+      - name: Ensure cache is healthy
+        if: steps.cache.outputs.cache-hit == 'true'
+        run: timeout 10s poetry run pip --version || rm -rf .venv
+
+      - name: Install dependencies
+        run: poetry install
+
+      - name: Test fallback regex behavior
+        env:
+          PYTEST_ADDOPTS: "--color=yes"
+        run: poetry run pytest tests/integration/test_validators.py -k pattern
+
   static_checks:
     name: "Static checks"
     runs-on: ubuntu-latest

diff --git a/README.rst b/README.rst
@@ -50,7 +50,24 @@ 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, allow_remote_references=False, **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.
+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
+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.
+
+To validate an OpenAPI schema:
 
 .. code-block:: python
 
@@ -100,6 +117,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
@@ -127,53 +147,79 @@ unresolved-metaschema fallback warnings.
    assert validator_for(schema) is OAS31Validator
    assert validator_for(schema32) is OAS32Validator
 
+Binary Data Semantics
+=====================
+
+The handling of binary-like payloads differs between OpenAPI versions.
 
-Strict vs Pragmatic Validators
-==============================
+OpenAPI 3.0
+-----------
 
-OpenAPI 3.0 has two validator variants with different behaviors for binary format:
+OpenAPI 3.0 keeps historical ``format: binary`` / ``format: byte`` usage on
+``type: string``.
 
-**OAS30Validator (default - pragmatic)**
-   - Accepts Python ``bytes`` for ``type: string`` with ``format: binary``
-   - More lenient for Python use cases where binary data is common
-   - Use when validating Python objects directly
+**OAS30Validator (default - compatibility behavior)**
+   - ``type: string`` accepts ``str``
+   - ``type: string, format: binary`` accepts Python ``bytes`` and strings
+   - useful when validating Python-native runtime data
 
 **OAS30StrictValidator**
-   - Follows OAS spec strictly: only accepts ``str`` for ``type: string``
-   - For ``format: binary``, only accepts base64-encoded strings
-   - Use when strict spec compliance is required
+   - ``type: string`` accepts ``str`` only
+   - ``type: string, format: binary`` uses strict format validation
+   - use when you want strict, spec-oriented behavior for 3.0 schemas
+
+OpenAPI 3.1+
+------------
+
+OpenAPI 3.1+ follows JSON Schema semantics for string typing in this library.
+
+- ``type: string`` accepts ``str`` only (not ``bytes``)
+- ``format: binary`` and ``format: byte`` are not treated as built-in formats
+- for base64-in-JSON, model with ``contentEncoding: base64`` (optionally
+  ``contentMediaType``)
+- for raw binary payloads, model via media type (for example
+  ``application/octet-stream``) rather than schema string formats
 
-Comparison Matrix
------------------
+Quick Reference
+---------------
 
 .. list-table::
    :header-rows: 1
-   :widths: 35 20 22 23
-
-   * - Schema
-     - Value
-     - OAS30Validator (default)
-     - OAS30StrictValidator
-   * - ``type: string``
-     - ``"test"`` (str)
-     - Pass
-     - Pass
-   * - ``type: string``
-     - ``b"test"`` (bytes)
-     - **Fail**
-     - **Fail**
-   * - ``type: string, format: binary``
-     - ``b"test"`` (bytes)
+   :widths: 28 24 24 24
+
+   * - Context
+     - ``"text"`` (str)
+     - ``b"text"`` (bytes)
+     - Notes
+   * - OAS 3.0 + ``OAS30Validator``
      - Pass
-     - **Fail**
-   * - ``type: string, format: binary``
-     - ``"dGVzdA=="`` (base64)
+     - 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
-   * - ``type: string, format: binary``
-     - ``"test"`` (plain str)
+     - Fail
+     - Use ``contentEncoding``/``contentMediaType`` and media types
+   * - OAS 3.2 + ``OAS32Validator``
      - Pass
-     - **Fail**
+     - Fail
+     - Same semantics as OAS 3.1
+
+
+Regex Behavior
+==============
+
+By default, ``pattern`` handling follows host Python regex behavior.
+For ECMAScript-oriented regex validation and matching (via ``regress``),
+install the optional extra:
+
+.. code-block:: console
+
+   pip install "openapi-schema-validator[ecma-regex]"
+
 
 For more details read about `Validation <https://openapi-schema-validator.readthedocs.io/en/latest/validation.html>`__.
 

diff --git a/SECURITY.md b/SECURITY.md
@@ -6,7 +6,9 @@ If you believe you have found a security vulnerability in the repository, please
 
 **Please do not report security vulnerabilities through public GitHub issues.**
 
-Instead, please report them directly to the repository maintainer.
+Instead, please report them directly to the repository maintainers or use GitHub's private vulnerability reporting flow
+(``Security Advisories``) to report security issues privately:
+https://docs.github.com/en/code-security/how-tos/report-and-fix-vulnerabilities/report-a-vulnerability/privately-reporting-a-security-vulnerability
 
 Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue:
 

diff --git a/docs/references.rst b/docs/references.rst
@@ -1,7 +1,13 @@
 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.
+By default, the shortcut uses a local-only empty registry and does not
+implicitly retrieve remote references.
+If needed, ``allow_remote_references=True`` enables jsonschema's default
+remote retrieval behavior.
 
 .. code-block:: python