Repository navigation
Support OpenAPI 3.1/3.2; deprecate legacy validators - #171
Conversation
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>
Reviewer's GuideAdds 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 warningssequenceDiagram
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
File-Level Changes
Assessment against linked issues
Possibly linked issues
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
for more information, see https://pre-commit.ci
There was a problem hiding this comment.
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.Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
There was a problem hiding this comment.
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-validatorin backend auto-detection, bump the[osv]extra toopenapi-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
flexandswagger-spec-validator(and document the deprecation), emittingDeprecationWarningwhen 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.
| assert 200 in parser.specification["paths"]["/test"]["post"]["responses"] | ||
|
|
||
|
|
||
| @pytest.mark.filterwarnings("ignore::DeprecationWarning") |
| parser = BaseParser("tests/specs/petstore.yaml", backend="flex") | ||
|
|
||
|
|
||
| @pytest.mark.filterwarnings("ignore::DeprecationWarning") |
| parser = BaseParser("tests/specs/missing_reference.yaml", backend="flex") | ||
|
|
||
|
|
||
| @pytest.mark.filterwarnings("ignore::DeprecationWarning") |
| assert "200" in parser.specification["paths"]["/test"]["post"]["responses"] | ||
|
|
||
|
|
||
| @pytest.mark.filterwarnings("ignore::DeprecationWarning") |
| parser = BaseParser("tests/specs/petstore.yaml", backend="swagger-spec-validator") | ||
|
|
||
|
|
||
| @pytest.mark.filterwarnings("ignore::DeprecationWarning") |
| BaseParser("tests/specs/openapi_3_1_features.yaml", backend="flex") | ||
|
|
||
|
|
||
| @pytest.mark.filterwarnings("ignore::DeprecationWarning") |
| absurl = url.absurl(os.path.abspath(full)).geturl() | ||
| code = f""" | ||
| @pytest.mark.xfail() | ||
| @pytest.mark.filterwarnings("ignore::DeprecationWarning") |
| # Deprecated backends remain available for Swagger 2.0, but emit | ||
| # DeprecationWarning when selected. Prefer openapi-spec-validator. | ||
| DEPRECATED_BACKENDS = frozenset({"flex", "swagger-spec-validator"}) |
| +------------------------+-----------------+-------------+----------------------------------------------------------------------------------+----------------+-----------------------------------------------------------------------------------+ | ||
|
|
||
| The ``[ssv]`` and ``[flex]`` extras are likewise deprecated; install ``prance[osv]`` | ||
| instead. Selecting a deprecated backend raises ``DeprecationWarning``. |
| @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 |
Summary
openapi-spec-validatoras the default backend when installedosvextra toopenapi-spec-validator~=0.9.0, with fixtures covering 3.2-only constructs (query,itemSchema,$self, device auth, etc.)flexandswagger-spec-validator(and[flex]/[ssv]extras): selecting them emitsDeprecationWarning; recommendprance[osv]Validator status
Closes #95
Closes #165
Test plan
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:
Enhancements:
Documentation:
Tests:
Chores: