# Fix the jsonschema RefResolver Deprecation Warning

Yes. An agent unpins jsonschema in its sandbox, shows RefResolver both warns and fails to resolve local refs on 4.18+, ports to referencing and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/fix-refresolver-deprecation-warning/jsonschema/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent clones the repository into its own cloud sandbox and reads why the pin is there. In a Python library like center-for-threat-informed-defense/attack-flow, `pyproject.toml` is a Poetry project for Python 3.12 to 3.14 with `jsonschema = "4.17.3"`, an exact pin, beside `stix2`, `networkx` and `graphviz`; `poetry.lock` matches. The resolver lives in `src/attack_flow/schema.py`: `get_validator_for_object` builds `jsonschema.validators.RefResolver(base_uri="", referrer=True, handlers={"https": resolve_url_to_local, "http": resolve_url_to_local})` at line 145 and passes it to `jsonschema.Draft202012Validator(schema_json, resolver=resolver)`. `resolve_url_to_local` maps the URLs the schemas reference, such as the ten `http://raw.githubusercontent.com/oasis-open/cti-stix2-json-schemas/stix2.1/schemas/common/identifier.json` refs in `attack-flow-schema-2.0.0.json` and the relative `../common/core.json` refs in the STIX object schemas, onto the 60 JSON files under `stix/`. `tests/test_schema.py` has 14 tests, `af validate` is the CLI command behind the Makefile's `validate` target, and `.github/workflows/build.yml` runs `poetry install` and `make test-ci` on Python 3.12.

It installs the package in editable mode on Python 3.12 with the pin and runs the baseline: `af validate tests/fixtures/flow1.json` prints `OK` and the 14 tests pass. Then it installs `jsonschema>=4.18`, which resolves to 4.26.0 with `referencing` 0.37.0, and runs both again with warnings enabled. The warning is the one in the title, at `schema.py:145`: `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.` But the run does not stop at a warning: `af validate` raises `jsonschema.exceptions._RefResolutionError: Unresolvable JSON pointer: 'definitions/extension-type-enum'`, and 8 of the 14 tests fail the same way. On the new version the compatibility `RefResolver` no longer follows this code's handlers the way 4.17.3 did, which is the real reason the pin exists.

The port is small because the handlers already do the work. The agent replaces the resolver with a `referencing.Registry(retrieve=...)` whose `retrieve` wraps the existing `resolve_url_to_local` in `Resource.from_contents(..., default_specification=DRAFT202012)`, and passes `registry=registry` to the validator in place of `resolver=`. That is 7 lines in and 6 out in `schema.py`. Under 4.26.0 with `-W error::DeprecationWarning`, `af validate` prints `OK` for the fixtures and all 14 tests pass, which proves both halves at once: no warning, and local references resolve again.

It also checks the floor. The `registry=` argument does not exist in 4.17.3, where the ported code fails with `TypeError: ... got an unexpected keyword argument 'registry'`, so the pull request moves the pin to `jsonschema = "^4.18"` and relocks with Poetry rather than leaving a constraint the code no longer satisfies. The `functools.lru_cache` on `get_validator_for_object` stays, so each object type still builds its validator once.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "This repository pins jsonschema below 4.18 and the current release prints \"DeprecationWarning: jsonschema.RefResolver is deprecated as of v4.18.0\". Read the dependency files and the lock, every module that constructs a RefResolver or passes resolver= to a validator, the schema files it resolves, and the tests that cover validation first. Install with the pin and run the validation tests and the CLI for a baseline, then install the current jsonschema and run both again with warnings enabled; quote the warning and any resolution error it produces, because the compatibility RefResolver may no longer honour custom handlers. Port the resolver to the referencing library: a Registry with a retrieve function that reuses the existing URL-to-local-file mapping, and registry= on the validator. Prove it with warnings as errors on the current jsonschema, then check whether the ported code runs on the old pinned version and raise the minimum version in the dependency file if it does not, relocking with the project's tool. Open a pull request that quotes the before and after test and CLI output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request with a 13-line change in `schema.py`, the `jsonschema` constraint moved to `^4.18` in `pyproject.toml`, and the lock file relocked. The description quotes the baseline on 4.17.3 (`OK`, 14 passed), the warning at `schema.py:145` and the `Unresolvable JSON pointer: 'definitions/extension-type-enum'` error on 4.26.0 with 8 failures, and the clean run after the port with `-W error::DeprecationWarning` turned on: `OK` for the fixtures, 14 passed.

It also quotes the `TypeError` the ported code raises on 4.17.3, which is why the floor moved. A reviewer reads the `retrieve` function against the old handlers, confirms the same URL mapping is used, and merges; the run's record holds every install and test session behind the quoted lines.

## Run it on every Monday morning

An exact pin is what a weekly upgrade run trips over: every week it would report that `jsonschema` cannot move until this port lands. An automation in the Project that holds the repository, with a `schedule` trigger, a `cron` of `0 7 * * 1` and the team's `timezone`, runs this prompt once to clear the pin, and from then on the weekly run can carry `jsonschema` forward with the tests as its check. A run an automation starts has its own `max_runs_per_hour` cap and is not tied to an API key.

From your own scheduler instead, send this body to `POST /o/{org}/sessions` with a `request_id` that is a UUID v5 of the week's date, so a retried job returns the run it already started. The key's `webhook_url` receives `run.completed` or `run.failed` with the session URL when the run ends.

## Why run it on Rush?

This is a case where the warning understates the problem: on the new version the old resolver does not just warn, it stops resolving the project's own schemas. Only running the suite under both versions shows that, and the agent does it in its own sandbox with a Python it installs for the purpose, and keeps every run in the record, so the pull request can say what breaks, with the exact pointer that fails, before it says how the port fixes it.

It is also a pin someone added for a reason they may not have written down, in a validation path that a security tool depends on. Running the port on a schedule, with the fixtures and the 14 tests as the check and a hard floor on the version, turns a mystery pin into a reviewed pull request, and the same prompt works on the next project that pinned `jsonschema` the same way.

## Frequently asked questions

### Why does validation fail on the new version instead of just warning?

Because `RefResolver` on 4.18 and later is a compatibility shim over the new `referencing` machinery, and this code relies on handlers plus an empty `base_uri` to map remote URLs to local files; under the shim a nested pointer into one of those local schemas no longer resolves and it raises `Unresolvable JSON pointer`. The agent reproduces the failure on the real schemas and fixtures before writing the port, so the pull request shows the failing pointer rather than guessing.

### Can the same URL-to-file mapping be kept?

Yes, that is the whole port. `referencing.Registry` takes a `retrieve` callable that is given a URI and returns a `Resource`; the agent wraps the existing `resolve_url_to_local` function in it, so every schema is still read from the files under `stix/` and nothing is fetched from the network.

### Why raise the minimum version too?

Because `registry=` is not accepted by validators before 4.18; the agent runs the ported code on 4.17.3 and quotes the `TypeError`. Leaving the old pin would declare a version the code cannot run on, so the pull request moves the constraint and relocks.

### Does this change what the schemas accept?

It should not, and the 14 validation tests plus the CLI over the fixture flows are the check: the same files pass before and after, and the bad-flow fixtures still produce the same results. Any difference in behaviour would show there, and the agent reports it rather than adjusting a test.

## More jobs like this: Upgrade dependencies weekly

- [Fix "Using / for division outside of calc() is deprecated" in Sass](https://getrush.ai/run/fix-sass-division-deprecation/sass/)
- [Fix "Support for the test command was removed in Setuptools 72"](https://getrush.ai/run/fix-setup-py-test-command-removed/setuptools/)
- [Fix "The sphinxcontrib.applehelp extension used by this project needs at least Sphinx v5.0"](https://getrush.ai/run/fix-sphinxcontrib-applehelp-version-error/sphinx/)
- [Fix "The Default Datetime Adapter Is Deprecated as of Python 3.12" in a sqlite3 App](https://getrush.ai/run/fix-sqlite3-default-datetime-adapter-deprecated-warning/sqlite3/)
- [Fix "'Starlette' object has no attribute 'route'" After Upgrading to Starlette 1.0](https://getrush.ai/run/fix-starlette-object-has-no-attribute-route/starlette/)
- [Fix "TypeError: stub(obj, 'meth', fn) has been removed" After Upgrading Sinon](https://getrush.ai/run/fix-stub-obj-meth-fn-has-been-removed/sinon/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
