refactor: migrate from jsonschema.RefResolver to referencing

[henryiii]

🤖 AI text below 🤖

Part of the code review in #2706.
Resolves #2139.

Summary

jsonschema.RefResolver has been deprecated since jsonschema 4.18. This migrates pyhf's schema validation to the referencing library:

• src/pyhf/schema/validator.py now builds a referencing.Registry with a retrieve callback (_retrieve_schema) that loads referenced schemas from disk, and passes registry=... to the jsonschema validator instead of the deprecated resolver=....
• The pyhf schemas carry a top-level $ref (e.g. model.json -> defs.json#/definitions/model). Under draft-06, a sibling $ref suppresses $id, so jsonschema cannot infer the root schema's base URI. The resolver base URI is therefore anchored explicitly to the schema $id so relative references like defs.json resolve correctly.
• A new loader.read_schema reads a schema directly from disk without consulting or mutating SCHEMA_CACHE, so resolving $refs does not pollute the cache. This preserves the existing caching semantics, including the pyhf.schema(new_path) custom-schema-path context manager and the InvalidSpecification exception behavior.
• Bumped jsonschema>=4.15.0 -> jsonschema>=4.18.0 and added referencing>=0.28.4 as an explicit dependency in both the project and pixi dependency tables (it is now imported directly).
• Removed the now-unneeded RefResolver DeprecationWarning filter. Since pytest runs with filterwarnings=error, any remaining deprecation path would now fail the suite.

Test plan

• uv pip install --group dev --editable .
• pytest tests/test_schema.py (70 passed)
• pytest tests/test_workspace.py tests/test_pdf.py (308 passed, 6 skipped)
• pytest tests/test_validation.py tests/test_patchset.py tests/test_public_api.py (all pass)
• pytest --doctest-modules src/pyhf/schema/ (3 passed)
• prek -a (lint clean)

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

@henryiii, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 17 minutes and 47 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more credits in the billing tab to continue.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 6626df9a-1764-4fa3-8b64-fcf2f1ce6421

📥 Commits

Reviewing files that changed from the base of the PR and between 0e54a51 and e55e252.

📒 Files selected for processing (3)

• pyproject.toml
• src/pyhf/schema/loader.py
• src/pyhf/schema/validator.py

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.47%. Comparing base (0e54a51) to head (e55e252).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2716      +/-   ##
==========================================
- Coverage   98.28%   96.47%   -1.81%     
==========================================
  Files          65       65              
  Lines        4305     4315      +10     
  Branches      465      465              
==========================================
- Hits         4231     4163      -68     
- Misses         46      119      +73     
- Partials       28       33       +5     

Flag	Coverage Δ
contrib	?
doctest	?
unittests-3.10	?
unittests-3.11	?
unittests-3.12	96.47% <100.00%> (+<0.01%)	⬆️
unittests-3.13	?
unittests-3.9	?

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.