Skip to content

Support OpenAPI 3.1/3.2; deprecate legacy validators - #171

Merged
RonnyPfannschmidt merged 5 commits into
mainfrom
support-modern-openapi
Jul 19, 2026
Merged

RonnyPfannschmidt merged 5 commits into
mainfrom
support-modern-openapi

Conversation

@RonnyPfannschmidt

@RonnyPfannschmidt RonnyPfannschmidt commented Jul 19, 2026 •

Copy link
Copy Markdown
Owner

Summary

  • Declare OpenAPI 3.1 support with feature-rich fixtures and docs; prefer openapi-spec-validator as the default backend when installed
  • Add OpenAPI 3.2 support by bumping the osv extra to openapi-spec-validator~=0.9.0, with fixtures covering 3.2-only constructs (query, itemSchema, $self, device auth, etc.)
  • Deprecate flex and swagger-spec-validator (and [flex] / [ssv] extras): selecting them emits DeprecationWarning; recommend prance[osv]

Validator status

Backend Status
openapi-spec-validator Recommended; 2.0 / 3.0–3.2
swagger-spec-validator Deprecated; Swagger 2.0 only
flex Deprecated; unmaintained since 2019

Closes #95
Closes #165

Test plan

  • CI green on 3.10–3.14
  • Review 3.1/3.2 feature fixtures and rejection-as-older-version tests
  • Confirm deprecated backends warn; osv does not

Made with Cursor

Summary by Sourcery

Add support for validating OpenAPI 3.1 and 3.2 specifications while preferring the openapi-spec-validator backend and deprecating legacy validation backends.

New Features:

  • Support validation of OpenAPI 3.1 feature-complete specifications via the openapi-spec-validator backend.
  • Support validation of OpenAPI 3.2 feature-complete specifications via the openapi-spec-validator backend.

Enhancements:

  • Prefer openapi-spec-validator as the default validation backend when available, ahead of deprecated backends.
  • Clarify CLI help, package description, and module docs to recommend openapi-spec-validator for modern OpenAPI versions.
  • Update optional osv dependency to openapi-spec-validator~=0.9.0 to gain OpenAPI 3.1/3.2 support.

Documentation:

  • Update top-level and project documentation to describe support for OpenAPI 3.x and the backend requirements for 3.1 and 3.2.

Tests:

  • Add fixtures and tests exercising OpenAPI 3.1-specific constructs and ensuring they are rejected when mis-labeled as 3.0.
  • Add fixtures and tests exercising OpenAPI 3.2-specific constructs and ensuring they are rejected when mis-labeled as 3.1.
  • Add tests verifying deprecated backends (flex, swagger-spec-validator) reject OpenAPI 3.1 specs and emit DeprecationWarning when selected.
  • Add tests verifying openapi-spec-validator is preferred in backend ordering and does not emit deprecation warnings.

Chores:

  • Introduce changelog entries documenting OpenAPI 3.1/3.2 support and deprecation of legacy validation backends.

RonnyPfannschmidt and others added 4 commits July 19, 2026 07:36
Validation already worked via openapi-spec-validator; document 3.1,
prefer osv over unmaintained flex when choosing a default backend,
and add acceptance tests. flex and swagger-spec-validator remain
Swagger 2.0-only.

Co-authored-by: Cursor AI <ai@cursor.sh>
Co-authored-by: Cursor Grok 4.5 <grok@x.ai>
Bump the osv extra to ~=0.9.0 so 3.2 specs can be detected and
validated, and add a minimal acceptance test.

Co-authored-by: Cursor AI <ai@cursor.sh>
Co-authored-by: Cursor Grok 4.5 <grok@x.ai>
Replace version-only smoke specs with fixtures that use
version-specific features (webhooks, type arrays, query method,
itemSchema, deviceAuthorization, etc.) and assert both acceptance
and rejection when labeled as an older OpenAPI version.

Co-authored-by: Cursor AI <ai@cursor.sh>
Co-authored-by: Cursor Grok 4.5 <grok@x.ai>
Emit DeprecationWarning when those backends are selected, document
the [flex]/[ssv] extras as deprecated, and steer users to
openapi-spec-validator via prance[osv].

Co-authored-by: Cursor AI <ai@cursor.sh>
Co-authored-by: Cursor Grok 4.5 <grok@x.ai>
Copilot AI review requested due to automatic review settings July 19, 2026 05:40
@sourcery-ai

sourcery-ai Bot commented Jul 19, 2026 •

Copy link
Copy Markdown

Reviewer's Guide

Adds first-class support and fixtures for validating OpenAPI 3.1 and 3.2 specs via openapi-spec-validator, makes it the preferred/default backend, and formally deprecates the legacy flex and swagger-spec-validator backends with warnings and updated docs/tests.

Sequence diagram for backend selection and deprecation warnings

sequenceDiagram
    actor User
    participant CLI as command_invoke
    participant Util as default_validation_backend
    participant Backends as validation_backends
    participant Parser as BaseParser.__init__
    participant Warn as warnings.warn

    User->>CLI: invoke CLI command
    CLI->>Util: default_validation_backend()
    Util->>Backends: validation_backends()
    Backends-->>Util: ["openapi-spec-validator", ...]
    Util-->>CLI: "openapi-spec-validator"

    CLI->>Parser: BaseParser.__init__(backend)

    alt backend is deprecated flex or swagger-spec-validator
        Parser->>Warn: warn(DeprecationWarning)
    else backend is openapi-spec-validator
        Parser-->>User: parse and validate OpenAPI 3.x
    end
Loading

File-Level Changes

Change Details Files
Prefer openapi-spec-validator as the default validation backend and update backend discovery/error messaging accordingly.
  • Reordered validation_backends() to detect openapi-spec-validator first, followed by swagger-spec-validator then flex
  • Updated default_validation_backend() error message to only recommend installing openapi-spec-validator via the osv extra
  • Adjusted CLI help text to prefer openapi-spec-validator and mark swagger-spec-validator and flex as deprecated
prance/util/__init__.py
prance/cli.py
Introduce deprecation handling for legacy flex and swagger-spec-validator backends while keeping them available for Swagger 2.0.
  • Added DEPRECATED_BACKENDS set on BaseParser and emit DeprecationWarning when a deprecated backend is selected
  • Clarified BaseParser init backend parameter docstring to note which backends are deprecated
  • Added tests asserting flex and swagger-spec-validator backends emit DeprecationWarning and that openapi-spec-validator does not
  • Marked many existing flex/swagger-spec-validator tests to ignore DeprecationWarning to keep them passing
prance/__init__.py
tests/test_backends.py
tests/test_zzz_specs.py
Add fixtures and validation tests for OpenAPI 3.1 and 3.2, and ensure older-version validators reject specs using newer-only features.
  • Added openapi_3_1_features.yaml and openapi_3_2_features.yaml spec fixtures exercising version-specific constructs
  • Added tests that openapi-spec-validator accepts these specs and parses them as 3.1.0/3.2.0 with expected feature shapes
  • Added tests that the same specs are rejected when their version headers are downgraded (3.1 as 3.0.3, 3.2 as 3.1.0)
  • Added tests that flex and swagger-spec-validator backends reject an OpenAPI 3.1 spec with a version mismatch
tests/specs/openapi_3_1_features.yaml
tests/specs/openapi_3_2_features.yaml
tests/test_backends.py
Align project metadata and docs with OpenAPI 3.x support and bump the osv extra to openapi-spec-validator~=0.9.0.
  • Updated package description strings to reference OpenAPI 3.x support in init and pyproject.toml
  • Bumped the osv optional dependency to openapi-spec-validator~=0.9.0
  • Documented that OpenAPI 3.1/3.2 validation requires the openapi-spec-validator backend and that flex/swagger-spec-validator are deprecated
  • Added changelog fragments for OpenAPI 3.x support and backend deprecation issues
prance/__init__.py
pyproject.toml
README.rst
docs/source/index.rst
changelog.d/+deprecate_legacy_backends.removal.rst
changelog.d/165.feature.rst
changelog.d/95.feature.rst
Ensure the validation backend ordering test reflects the new preference for openapi-spec-validator.
  • Added test_validation_backends_prefer_osv() to assert that openapi-spec-validator is first in the discovered backend list when installed
tests/test_backends.py

Assessment against linked issues

Issue Objective Addressed Explanation
#95 Add parser/validation support for OpenAPI 3.1.0 specifications in the library. ✅
#95 Update project configuration and documentation to declare and reflect OpenAPI 3.1 support. ✅
#165 Add support for parsing and validating OpenAPI 3.2.0, including correct version detection of openapi: "3.2.0". ✅
#165 Maintain backward compatibility and continued support for existing OpenAPI/Swagger versions while adding 3.2.0 capabilities. ✅
#165 Implement support for OpenAPI 3.2-specific features (e.g., JSON Schema 2020-12 constructs, webhook-like objects, new security schemes and other 3.2-only fields) via appropriate validation and fixtures. ✅

Possibly linked issues

  • #[Feature]: Support for OpenAPI Spec 3.2: PR introduces OpenAPI 3.2 validation, fixtures, and version handling as requested, plus 3.1 support and backend deprecations.
  • #(unprovided): PR updates osv extra to openapi-spec-validator~=0.9.0 and modernizes validation, directly addressing the dependency upgrade request.

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey - I've left some high level feedback:

  • The tests that simulate version downgrades by string-replacing openapi: "3.1.0"/"3.2.0" in the spec files are quite brittle; consider building the spec dict and adjusting the version programmatically to avoid failures when the fixture formatting changes.
  • Using broad @pytest.mark.filterwarnings("ignore::DeprecationWarning") on the flex and swagger-spec-validator tests may hide unrelated deprecation warnings from those tests; tightening the filter (e.g., with a specific message regex) would make it easier to spot new deprecations in those code paths.
Prompt for AI Agents
Please address the comments from this code review:

## Overall Comments
- The tests that simulate version downgrades by string-replacing `openapi: "3.1.0"`/`"3.2.0"` in the spec files are quite brittle; consider building the spec dict and adjusting the version programmatically to avoid failures when the fixture formatting changes.
- Using broad `@pytest.mark.filterwarnings("ignore::DeprecationWarning")` on the flex and swagger-spec-validator tests may hide unrelated deprecation warnings from those tests; tightening the filter (e.g., with a specific message regex) would make it easier to spot new deprecations in those code paths.

Sourcery is free for open source - if you like our reviews please consider sharing them ✨
Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR updates prance’s validation story to explicitly support OpenAPI 3.1 and 3.2 via openapi-spec-validator, makes that backend the preferred default when installed, and deprecates the legacy flex / swagger-spec-validator backends with DeprecationWarning.

Changes:

  • Prefer openapi-spec-validator in backend auto-detection, bump the [osv] extra to openapi-spec-validator~=0.9.0, and update CLI/docs to recommend it for OpenAPI 3.x (3.0–3.2).
  • Add OpenAPI 3.1/3.2 “feature” fixtures plus tests that assert acceptance under 3.1/3.2 and rejection when mis-labeled as older versions.
  • Deprecate flex and swagger-spec-validator (and document the deprecation), emitting DeprecationWarning when explicitly selected.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 11 comments.

Show a summary per file
File Description
prance/util/__init__.py Reorders backend preference to favor openapi-spec-validator; updates default-backend error messaging.
prance/__init__.py Documents 3.1/3.2 support expectations; emits DeprecationWarning for deprecated backends.
prance/cli.py Updates CLI help text to prefer openapi-spec-validator and note deprecated backends.
pyproject.toml Bumps [osv] extra to openapi-spec-validator~=0.9.0; updates project description to “3.x”.
README.rst Updates README to describe 2.0 + 3.x support, backend preference, and deprecation status.
docs/source/index.rst Updates docs landing page tagline to “2.0 and 3.x”.
tests/test_backends.py Adds 3.1/3.2 validation tests and deprecation-warning tests; adds warning filters for deprecated backends in other tests.
tests/test_zzz_specs.py Suppresses deprecation warnings in generated xfail example tests.
tests/specs/openapi_3_1_features.yaml Adds OpenAPI 3.1-only fixture exercising 3.1/JSON Schema 2020-12 constructs.
tests/specs/openapi_3_2_features.yaml Adds OpenAPI 3.2-only fixture exercising 3.2 constructs (e.g., query, itemSchema, $self).
changelog.d/95.feature.rst Changelog entry for OpenAPI 3.1 support.
changelog.d/165.feature.rst Changelog entry for OpenAPI 3.2 support and osv version bump.
changelog.d/+deprecate_legacy_backends.removal.rst Changelog entry documenting deprecation of flex / swagger-spec-validator and extras.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread tests/test_backends.py
assert 200 in parser.specification["paths"]["/test"]["post"]["responses"]


@pytest.mark.filterwarnings("ignore::DeprecationWarning")
Comment thread tests/test_backends.py
parser = BaseParser("tests/specs/petstore.yaml", backend="flex")


@pytest.mark.filterwarnings("ignore::DeprecationWarning")
Comment thread tests/test_backends.py
parser = BaseParser("tests/specs/missing_reference.yaml", backend="flex")


@pytest.mark.filterwarnings("ignore::DeprecationWarning")
Comment thread tests/test_backends.py
assert "200" in parser.specification["paths"]["/test"]["post"]["responses"]


@pytest.mark.filterwarnings("ignore::DeprecationWarning")
Comment thread tests/test_backends.py
parser = BaseParser("tests/specs/petstore.yaml", backend="swagger-spec-validator")


@pytest.mark.filterwarnings("ignore::DeprecationWarning")
Comment thread tests/test_backends.py
BaseParser("tests/specs/openapi_3_1_features.yaml", backend="flex")


@pytest.mark.filterwarnings("ignore::DeprecationWarning")
Comment thread tests/test_zzz_specs.py
absurl = url.absurl(os.path.abspath(full)).geturl()
code = f"""
@pytest.mark.xfail()
@pytest.mark.filterwarnings("ignore::DeprecationWarning")
Comment thread prance/__init__.py
Comment on lines +60 to +62
# Deprecated backends remain available for Swagger 2.0, but emit
# DeprecationWarning when selected. Prefer openapi-spec-validator.
DEPRECATED_BACKENDS = frozenset({"flex", "swagger-spec-validator"})
Comment thread README.rst
+------------------------+-----------------+-------------+----------------------------------------------------------------------------------+----------------+-----------------------------------------------------------------------------------+

The ``[ssv]`` and ``[flex]`` extras are likewise deprecated; install ``prance[osv]``
instead. Selecting a deprecated backend raises ``DeprecationWarning``.
Comment thread tests/test_backends.py
Comment on lines +22 to 25
@pytest.mark.filterwarnings("ignore::DeprecationWarning")
@pytest.mark.skipif(none_of("flex"), reason="Missing dependencies: flex")
def test_flex_issue_5_integer_keys():
# Must succeed with default (flex) parser; note the parser does not stringify the response code
@RonnyPfannschmidt
RonnyPfannschmidt merged commit 140728f into main Jul 19, 2026
14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature]: Support for OpenAPI Spec 3.2 Support for open api v3.1

2 participants