sysfce2 · pull · Feb 24, 2026 · Feb 24, 2026 · Feb 24, 2026 · Feb 24, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,148 @@
+# AGENTS.md
+Guidance for coding agents working in `openapi-spec-validator`.
+
+## Project Snapshot
+- Language: Python (3.10-3.14)
+- Tooling: Poetry, pytest, mypy, black, isort, flake8, deptry, pre-commit, tox
+- Main package: `openapi_spec_validator/`
+- Tests: `tests/integration/`, `tests/bench/`
+- Docs: Sphinx in `docs/`
+
+## Setup
+- Keep venv in-project: `poetry config virtualenvs.in-project true`
+- Install dev deps: `poetry install --with dev`
+- Install docs deps: `poetry install --with docs`
+
+## Build Commands
+- Build artifacts: `poetry build`
+- Legacy build path: `make dist-build`
+- Clean build/test artifacts: `make cleanup`
+
+## Test Commands
+- Full tests: `poetry run pytest`
+- Multi-Python matrix locally: `tox`
+- One file: `poetry run pytest tests/integration/test_main.py`
+- One test function: `poetry run pytest tests/integration/test_main.py::test_version`
+- One parametrized case:
+  `poetry run pytest 'tests/integration/validation/test_validators.py::TestLocalOpenAPIv30Validator::test_valid[petstore.yaml]'`
+- By keyword: `poetry run pytest -k "schema_v31"`
+- Exclude network tests: `poetry run pytest -m "not network"`
+- Run only network tests: `poetry run pytest -m network`
+- Fast focused test without default addopts (no coverage/junit):
+  `poetry run pytest -o addopts='' tests/integration/test_main.py::test_version`
+
+## Lint, Format, Type, Dependencies
+- Format: `poetry run black . && poetry run isort .`
+- Format check only: `poetry run black --check . && poetry run isort --check-only .`
+- Lint: `poetry run flake8`
+- Types: `poetry run mypy`
+- Dependency check: `poetry run deptry .`
+- Pre-commit setup: `pre-commit install`
+- Run all hooks: `pre-commit run --all-files`
+
+## Docs
+- CI-equivalent docs build:
+  `poetry run python -m sphinx -T -b html -d docs/_build/doctrees -D language=en docs docs/_build/html -n -W`
+
+## Style Rules (from repo config + code)
+
+### Formatting
+- Black is authoritative formatter.
+- Line length is 79 (`tool.black.line-length = 79`, flake8 79).
+- isort uses `profile = black` and `force_single_line = true`.
+- Keep one imported symbol per line for `from x import y` style blocks.
+
+### Imports
+- Use absolute imports from `openapi_spec_validator...`.
+- Order import groups: stdlib, third-party, first-party.
+- Avoid wildcard imports.
+- Keep imports explicit and deterministic under isort.
+
+### Typing
+- Mypy is strict (`[tool.mypy] strict = true`).
+- Add annotations to all new/modified functions and methods.
+- Prefer built-in generics (`list[str]`, `dict[str, int]`) and `X | None`.
+- Avoid broad `Any`; if unavoidable, keep scope minimal.
+- Existing ignores are for external libs only; do not add broad ignores casually.
+
+### Naming
+- Modules/files: `snake_case`.
+- Variables/functions: `snake_case`.
+- Classes: `PascalCase`.
+- Constants: `UPPER_SNAKE_CASE`.
+- Test functions: `test_*` and behavior-focused names.
+
+### Error Handling
+- Raise specific exceptions in library code.
+- Preserve public exception behavior unless change is intentional and tested.
+- CLI in `openapi_spec_validator/__main__.py` currently uses:
+  - exit code 1 for read/validation failures
+  - exit code 2 for unexpected runtime failures
+- Keep deprecation warnings consistent with current message patterns.
+- Do not discard useful validation context when propagating errors.
+
+### Tests and Markers
+- Use pytest assertions directly (`assert ...`).
+- Reuse helpers in `tests/integration/conftest.py`.
+- Mark network-dependent tests with `@pytest.mark.network`.
+- Prefer integration tests near affected behavior (`validation`, `shortcuts`, `versions`, CLI).
+- If behavior changes, add/adjust tests in the same PR.
+
+## CI Expectations
+- Main CI test workflow runs on Python 3.10-3.14 and ubuntu/windows.
+- Core checks are:
+  1. `poetry run pytest`
+  2. `poetry run mypy`
+  3. `poetry run deptry .`
+- Pre-commit hooks include: pyupgrade (`--py310-plus`), black, isort, flake8.
+- Docs CI installs `--with docs` and runs Sphinx with `-n -W` (warnings are failures).
+
+## Compatibility Notes
+- Project keeps deprecated compatibility paths (e.g., old flags and shortcuts).
+- Avoid removing aliases or changing warning behavior without explicit instruction.
+- Keep CLI/user-facing strings stable unless tests are updated accordingly.
+
+## Cursor/Copilot Instructions Check
+- `.cursor/rules/`: not present
+- `.cursorrules`: not present
+- `.github/copilot-instructions.md`: not present
+- If these files appear later, treat them as higher-priority agent instructions and update this file.
+
+## Agent Working Agreement
+- Keep diffs minimal and scoped.
+- Do not modify unrelated files.
+- Prefer targeted tests first, then full suite when needed.
+- Run formatter/lint/type checks for code changes before finishing.
+- Maintain backward compatibility unless task explicitly requests breaking change.
+
+## Handy Paths
+- Package entrypoint: `openapi_spec_validator/__main__.py`
+- API shortcuts: `openapi_spec_validator/shortcuts.py`
+- Validators: `openapi_spec_validator/validation/validators.py`
+- Reader utilities: `openapi_spec_validator/readers.py`
+- Integration tests: `tests/integration/`
+- Pyproject config: `pyproject.toml`
+- Tox config: `tox.ini`
+- Pre-commit config: `.pre-commit-config.yaml`
+
+## Quick Local Validation Recipe
+Run this sequence before handoff:
+1. `poetry run black . && poetry run isort .`
+2. `poetry run flake8`
+3. `poetry run mypy`
+4. `poetry run pytest -m "not network"`
+5. Add targeted network test runs only if your change touches URL/network behavior.
+
+## Practical Execution Notes
+- Pytest defaults from `pyproject.toml` include coverage and junit outputs.
+- For quick iterations, prefer `-o addopts=''` with a specific node id.
+- Keep command output readable; avoid noisy full-suite runs unless needed.
+- For CLI behavior changes, prioritize tests in `tests/integration/test_main.py`.
+- For validator behavior changes, prioritize `tests/integration/validation/`.
+- For version detection changes, prioritize `tests/integration/test_versions.py`.
+
+## Commit/PR Hygiene for Agents
+- Keep changes scoped to the requested task.
+- Do not bundle formatting-only churn with behavior changes unless requested.
+- Mention any intentionally preserved deprecated behavior in PR notes.
+- If you change user-visible messages, update tests in the same change.
diff --git a/Dockerfile b/Dockerfile
@@ -1,4 +1,4 @@
-ARG OPENAPI_SPEC_VALIDATOR_VERSION=0.8.0
+ARG OPENAPI_SPEC_VALIDATOR_VERSION=0.8.1
 
 FROM python:3.14.3-alpine as builder
 

diff --git a/README.rst b/README.rst
@@ -85,7 +85,7 @@ pre-commit hook
 
    repos:
    -   repo: https://github.com/python-openapi/openapi-spec-validator
-       rev: 0.8.0 # The version to use or 'master' for latest
+       rev: 0.8.1 # The version to use or 'master' for latest
        hooks:
        -   id: openapi-spec-validator
 

diff --git a/docs/cli.rst b/docs/cli.rst
@@ -23,27 +23,48 @@ CLI (Command Line Interface)
 
          docker run -v path/to/openapi.yaml:/openapi.yaml --rm pythonopenapi/openapi-spec-validator /openapi.yaml
 
+      Show all validation errors:
+
+      .. code-block:: bash
+
+         docker run -v path/to/openapi.yaml:/openapi.yaml --rm pythonopenapi/openapi-spec-validator --validation-errors all /openapi.yaml
+
+      Show all validation errors and all subschema details:
+
+      .. code-block:: bash
+
+         docker run -v path/to/openapi.yaml:/openapi.yaml --rm pythonopenapi/openapi-spec-validator --validation-errors all --subschema-errors all /openapi.yaml
+
    .. md-tab-item:: Python interpreter
 
       .. code-block:: bash
 
          python -m openapi_spec_validator openapi.yaml
 
-.. code-block:: bash
+.. code-block:: text
 
-   usage: openapi-spec-validator [-h] [--errors {best-match,all}]
-                                 [--schema {2.0,3.0.0,3.1.0,detect}]
-                                 filename
+   usage: openapi-spec-validator [-h] [--subschema-errors {best-match,all}]
+                                 [--validation-errors {first,all}]
+                                 [--errors {best-match,all}] [--schema {detect,2.0,3.0,3.1}]
+                                 [--version] file [file ...]
 
    positional arguments:
-     filename              Absolute or relative path to file
+     file                  Validate specified file(s).
 
    options:
      -h, --help            show this help message and exit
-     --errors {best-match,all}
-                           Control error reporting. Defaults to "best-
-                           match", use "all" to get all subschema
-                           errors.
-     --schema {2.0,3.0.0,3.1.0,detect}
-                           OpenAPI schema (default: detect)
-
+     --subschema-errors {best-match,all}
+                           Control subschema error details. Defaults to "best-match",
+                           use "all" to get all subschema errors.
+     --validation-errors {first,all}
+                           Control validation errors count. Defaults to "first",
+                           use "all" to get all validation errors.
+     --errors {best-match,all}, --error {best-match,all}
+                           Deprecated alias for --subschema-errors.
+     --schema {detect,2.0,3.0,3.1}
+                           OpenAPI schema version (default: detect).
+     --version             show program's version number and exit
+
+Legacy note:
+   ``--errors`` / ``--error`` are deprecated and emit warnings by default.
+   Set ``OPENAPI_SPEC_VALIDATOR_WARN_DEPRECATED=0`` to silence warnings.
diff --git a/docs/hook.rst b/docs/hook.rst
@@ -16,7 +16,7 @@ A full .pre-commit-config.yaml example you can use in your repository:
 
    repos:
    -   repo: https://github.com/python-openapi/openapi-spec-validator
-       rev: 0.8.0 # The version to use or 'master' for latest
+       rev: 0.8.1 # The version to use or 'master' for latest
        hooks:
        -   id: openapi-spec-validator
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -63,6 +63,10 @@ Usage
 
                docker run -v path/to/openapi.yaml:/openapi.yaml --rm pythonopenapi/openapi-spec-validator /openapi.yaml
 
+             .. code-block:: bash
+
+                docker run -v path/to/openapi.yaml:/openapi.yaml --rm pythonopenapi/openapi-spec-validator --validation-errors all /openapi.yaml
+
          .. md-tab-item:: Python interpreter
 
             .. code-block:: bash
@@ -77,7 +81,7 @@ Usage
 
          repos:
          -   repo: https://github.com/python-openapi/openapi-spec-validator
-             rev: 0.8.0 # The version to use or 'master' for latest
+             rev: 0.8.1 # The version to use or 'master' for latest
              hooks:
              -   id: openapi-spec-validator
 

diff --git a/openapi_spec_validator/__init__.py b/openapi_spec_validator/__init__.py
@@ -15,7 +15,7 @@
 
 __author__ = "Artur Maciag"
 __email__ = "maciag.artur@gmail.com"
-__version__ = "0.8.0"
+__version__ = "0.8.1"
 __url__ = "https://github.com/python-openapi/openapi-spec-validator"
 __license__ = "Apache License, Version 2.0"