Replace deprecated `jsonschema.RefResolver` with `referencing.Registry`

[radoering]

Fixes #1786 (which was closed prematurely as pointed out in https://github.com/spec-first/connexion/issues/1786#issuecomment-2474017122)

Fixes the following deprecation warnings:

connexion/json_schema.py:18
  /home/randy/connexion/connexion/json_schema.py:18: DeprecationWarning: jsonschema.RefResolver is deprecated as of v4.18.0, in favor of the https://github.com/python-jsonschema/referencing library, which provides more compliant referencing behavior as well as more flexible APIs for customization. A future release will remove RefResolver. Please file a feature request (on referencing) if you are missing an API for the kind of customization you need.
    from jsonschema import Draft4Validator, RefResolver

connexion/json_schema.py:19
  /home/randy/connexion/connexion/json_schema.py:19: DeprecationWarning: jsonschema.exceptions.RefResolutionError is deprecated as of version 4.18.0. If you wish to catch potential reference resolution errors, directly catch referencing.exceptions.Unresolvable.
    from jsonschema.exceptions import RefResolutionError, ValidationError  # noqa

See also https://python-jsonschema.readthedocs.io/en/latest/referencing/#migrating-from-refresolver

[chrisinmtown]

Thanks for this, I'm a little tired of seeing those warnings every time I run tox. I hope someone can explain why the code test pipeline/workflow didn't run automatically on this PR, only the read-the-docs check?

[chrisinmtown]

The referencing library is in status Alpha and their issues board includes a ticket about very slow performance:

https://github.com/python-jsonschema/referencing/issues/178

Did you notice any slowdown here?

[radoering]

Did you notice any slowdown here?

I did not notice any slowdown in the tests. I did not try with larger schemas.

[radoering]

I hope someone can explain why the code test pipeline/workflow didn't run automatically on this PR, only the read-the-docs check?

The workflow requires approval from a maintainer according to https://github.com/spec-first/connexion/actions

[FelixSchwarz]

Thanks for this, I'm a little tired of seeing those warnings every time I run tox.

You can suppress warnings via pytest.ini:

[pytest]
...
filterwarnings =
    error
    # Connexion 3.1 -> jsonschema
    ignore:Accessing jsonschema.draft4_format_checker is deprecated and will be removed in a future release.:DeprecationWarning
    ignore:jsonschema.RefResolver is deprecated as of v4.18.0, in favor of:DeprecationWarning
    ignore:jsonschema.exceptions.RefResolutionError is deprecated as of version 4.18.0.:DeprecationWarning

I hope someone can explain why the code test pipeline/workflow didn't run automatically on this PR, only the read-the-docs check?

GitHub offers maintainers options to not run workflows for non-members or first-time contributors. I believe this was added because of security concerns (workflows might have access to secrets which the PR could exfiltrate) and abuse (e.g. using the workflow for crypto mining).

[chrisinmtown]

Just my $0.02, FWIW I think the JSON schema people might have acted hastily in adding those deprecations. I am not sure my first impression is correct, but the recommended replacement (another github project) looks new, not quite ready, very Alpha status. Given other instabilities that seem to plague Connexion 3, taking on the risk of making this switch doesn't seem like something to rush into.

[radoering]

The recommended replacement (referencing) is from the JSON schema people:

• https://github.com/python-jsonschema/jsonschema
• https://github.com/python-jsonschema/referencing

The first release was over two years ago.

And considering the "Alpha" status: I would not put too much into it. For example, black was beta until 2021 and much more stable than many other "stable" packages.

To be clear: I do not know how stable referencing is, but I think the arguments considering it unstable are not that strong.

[Stranger6667]

FWIW, referencing passes most of the official referencing test suite (except URI normalization) + jsonschema which uses referencing passes the official JSON Schema Test Suite except for 1 test case (quite a rare one I must say).

Additionally, I've successfully borrowed the referencing design in my jsonschema implementation (it is closer to 100% spec compliance than jsonschema and often >300x faster).

I.e. as one of the jsonschema implementers & users of referencing I want to say that referencing is a great piece of software I've been relying on for many years.

[briceburg]

Curios re: the progress on this? IMO pytest should simply work for our users without a deprecation warning. We can port everything that refResolver did to use referencing equivalents. It's as easy as providing a custom resolver to handle all the relative pathing / http lookups / &c.

it would be nice to use an @referencing.retrieval.to_cached_resource() annotation on the method... but it's going to be more complicated than that... ;) and can implement its own caching as necessary. https://referencing.readthedocs.io/en/stable/intro/

is there a review process or feedback/progress on any existing PRs? would this project accept another? I feel that getting referencing in place is going to be a stepping stone towards finally supporting the openapi 3.1 spec.... and in meantime we can limit resolver to using Draft7 schemas & validators.

[briceburg]

@RobbeSneyders was closed prematurely -- see https://github.com/spec-first/connexion/issues/1786#issuecomment-2474017122 ... curious what we can do to get a fix for this. anyone using connexion w/ pytest is seeing:

=========================== test session starts ===========================
platform linux -- Python 3.13.5, pytest-8.4.1, pluggy-1.6.0
rootdir: /foo
configfile: pyproject.toml
plugins: anyio-4.9.0
collected 6 items                                                         

tests/api/test_players.py .                                         [ 16%]
tests/api/test_station_presets.py .                                 [ 33%]
tests/test_schemas.py ....                                          [100%]

============================ warnings summary =============================
venv/lib/python3.13/site-packages/connexion/json_schema.py:16
venv/lib/python3.13/site-packages/connexion/json_schema.py:16
  /foo/venv/lib/python3.13/site-packages/connexion/json_schema.py:16: DeprecationWarning: jsonschema.RefResolver is deprecated as of v4.18.0, in favor of the https://github.com/python-jsonschema/referencing library, which provides more compliant referencing behavior as well as more flexible APIs for customization. A future release will remove RefResolver. Please file a feature request (on referencing) if you are missing an API for the kind of customization you need.
    from jsonschema import Draft4Validator, RefResolver

... and this will not go away util we replace RefResolver with referencing per this PR, or another approach??