Add basic JSON UI form field support (PP-4438)

[tdilauro]

Description

Adds a json form field type for integration settings. Fields annotated with FormFieldType.JSON display a textarea in the admin UI that accepts a JSON value. Two-way handling is wired up automatically:

• Form rendering: the field's default value is serialized to a JSON string so the UI displays it correctly.
• Form submission: the incoming string is parsed back to a Python value before Pydantic validation runs, with a clear error message if the input is not valid JSON.

Note: The ability to edit this field type depends on new support introduced on circulation-admin PR #224.

Motivation and Context

Integration settings that need to store structured data (objects, arrays) previously had no native form type. This adds a first-class JSON field type that makes the round-trip between the admin UI and the settings model transparent.

[Jira PP-4438]

How Has This Been Tested?

• Manual testing in local development environment admin UI.
• New/updated tests for the new functionality.
• All tests and checks pass locally.
• CI tests and checks pass.

Checklist

• N/A - I have updated the documentation accordingly.
• All new and existing tests passed.

[claude]

Claude finished @tdilauro's task in 3m 33s —— View job

---

Code Review

• Gather context and read changed files
• Analyze diff and identify findings
• Post final review

---

Summary

Clean, well-scoped implementation. The two-part design — serializing the default to a JSON string in to_dict and parsing it back in the model_validator(mode="before") — is the right approach and integrates naturally with the existing empty-string-to-None normalization (the first loop already handles "" before the JSON loop runs, so isinstance(v, str) correctly skips None). The test suite is thorough, covering the important edge cases including alias fields, passthrough of already-parsed values, and the invalid-input error path.

Details

Minor: src/palace/manager/integration/settings.py:213-217

The alias-resolution ternary has three reachable conditions: (1) no alias defined → key = name, (2) alias defined and alias is in values → key = alias, and (3) alias defined but alias not in values (field submitted by field name rather than alias, which is valid with populate_by_name=True) → key = name. test_json_field_alias_parsing covers case 2, and the non-aliased tests cover case 1, but case 3 is untested — this is what Codecov flags as the partial line. A one-liner addition to test_json_field_alias_parsing would close it:

# submitted by field name instead of alias
settings = AliasedJsonSettings(**{"data": '{"x": 1}'})
assert settings.data == {"x": 1}

circulation/src/palace/manager/integration/settings.py

Lines 213 to 217 in 764b68c

	key = (
	field_info.alias
	if field_info.alias is not None and field_info.alias in values
	else name
	)

Nit: tests/manager/integration/test_settings.py:141-143

The empty-string-normalizes-to-None assertion for JSON fields lands inside test_settings_validation alongside the generic whitespace tests, but the surrounding JSON-specific tests (test_json_field_parsing, etc.) are a more natural home. Moving it there or adding ("", None) as a parameter to test_json_field_parsing would keep JSON coverage in one place. Not a correctness issue.

circulation/tests/manager/integration/test_settings.py

Lines 141 to 143 in 764b68c

	# Empty string is normalized to None for all fields, including JSON fields.
	settings = JsonMockSettings(data="")
	assert settings.data is None

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.34%. Comparing base (5315bfb) to head (764b68c).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3386   +/-   ##
=======================================
  Coverage   93.34%   93.34%           
=======================================
  Files         507      507           
  Lines       46434    46451   +17     
  Branches     6336     6341    +5     
=======================================
+ Hits        43345    43361   +16     
- Misses       1999     2000    +1     
  Partials     1090     1090           

☔ View full report in Codecov by Sentry.
📢 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.

[tdilauro]

I improved the coverage and addressed useful AI review feedback. This is ready for human review.

[jonathangreen]

🚀 looks great!