All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.

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

Keep reading