Recent updates in NaviServer (5.1) and OpenACS introduce built-in support for handling JSON request bodies seamlessly with ad_page_contract.
JSON requests (application/json and application/*+json) are now automatically parsed and flattened into the connection form set, making JSON-based APIs first-class citizens in existing OpenACS applications. This enables contract validation, filtering, and type handling for JSON payloads in the same consistent way as traditional form submissions.
Motivation
The goal of this enhancement is not just additional functionality, but improved adherence to modern web standards and best practices.
Specifically:
- Automatic handling of JSON media types (including structured syntax suffixes)
- Validation errors returned as
application/problem+json (RFC 9457)
- Use of JSON Pointer references (RFC 6901) to identify invalid fields
- Proper HTTP status codes (e.g., 422 Unprocessable Content)
- Consistent request processing aligned with HTTP semantics
This improves interoperability, clarity of API behavior, and security, while keeping the familiar OpenACS development model.
Stability and Compatibility
The new functionality is covered by regression tests in acs-automated-testing, including success cases, nested JSON validation failures, proper status codes, and standards-compliant error responses.
Full backward compatibility is preserved. Existing HTML form handling and page contracts continue to behave exactly as before.
More documentation and examples are available here:
https://openacs.org/xowiki/json-page-contract
The experimental webauthn package will be updated soon to leverage these new JSON page contract capabilities.
