Add JSON mode for error responses #416

Copilot · 2026-01-05T18:51:30Z

JSON Mode Implementation - Complete

This PR implements JSON mode for Scotty, allowing all default error responses to be returned as JSON instead of HTML when the jsonMode flag is enabled in Options.

Changes Made

Added jsonMode flag to Options (defaults to False)
Updated error handlers to return JSON when enabled:
- scottyExceptionHandler - Scotty-specific exceptions (400, 413, 422, 500)
- someExceptionHandler - uncaught exceptions (500)
- notFoundApp - 404 errors
- unhandledExceptionHandler - unhandled ScottyExceptions
Fixed error message - FormFieldNotFound now says "Form field" not "Query parameter"
Fixed build error - Changed HashMap to Map for Form construction, added containers dependency with version constraint (>= 0.5 && < 0.8)
Consistent Content-Type headers - All JSON responses use application/json; charset=utf-8
Added tests for custom error handlers - 4 new tests demonstrate how custom handlers interact with HTTP status codes
Added changelog entry - Documented the JSON mode feature under "next" section

Testing

✅ All 120 tests pass (116 original + 4 new)
✅ New tests document custom error handler behavior with HTTP status codes
✅ JSON mode tests verify correct Content-Type headers and response format

Usage

scottyOpts (defaultOptions { jsonMode = True }) $ do
  get "/" $ json $ object ["message" .= "Hello"]

All JSON responses use consistent format: {"status": <code>, "description": "<message>"} with Content-Type: application/json; charset=utf-8.

Original prompt

This section details on the original issue you should resolve

<issue_title>JSON mode</issue_title>
<issue_description>In the default configuration Scotty returns always HTML. E.g.

Content-Type: text/html; charset=utf-8
Date: Mon, 25 Feb 2019 14:12:54 GMT
Server: Warp/3.2.26
Transfer-Encoding: chunked

<h1>500 Internal Server Error</h1>

There should be an option to run Scotty in a JSON mode where all default responses are JSON. E.g.:

Content-Type: application/json; charset=utf-8
Date: Mon, 25 Feb 2019 14:19:36 GMT
Server: Warp/3.2.26
Transfer-Encoding: chunked

{
    "status": 500
    "description": "There was an error while accessing the database"
}
```</issue_description>

<agent_instructions>Implement JSON mode :
* add runtime flag
* adjust all error handlers so that returned responses are JSON formatted if the flag is set.</agent_instructions>

## Comments on the Issue (you are @copilot in this section)

<comments>
<comment_new><author>@ocramz</author><body>
scotty-web/scotty#121 is also relevant for this</body></comment_new>
<comment_new><author>@ocramz</author><body>
@ip1981 @magthe In our current design (as of 0.21 let's say : https://github.com/scotty-web/scotty/blob/66d60f7a6828c7e9f8c7d2dc49e9597e7278b982/Web/Scotty/Action.hs#L113-L176 ) we have a cascade of handlers, which is where the exception to HTTP status translation takes place.

In turn `runAction` is called within `addroute` https://github.com/scotty-web/scotty/blob/66d60f7a6828c7e9f8c7d2dc49e9597e7278b982/Web/Scotty/Route.hs#L104 , which is where we could configure the output rendering (JSON, HTML etc.)</body></comment_new>
<comment_new><author>@ocramz</author><body>
I've just realized that currently our exception handling and server response generation are very coupled.

E.g. if a user specifies a custom handler, should they have to re-implement the response generation part?</body></comment_new>
</comments>

Fixes JSON mode #227

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Co-authored-by: ocramz <5902760+ocramz@users.noreply.github.com>

…f 'Query parameter' Co-authored-by: ocramz <5902760+ocramz@users.noreply.github.com>

Co-authored-by: ocramz <5902760+ocramz@users.noreply.github.com>

Copilot

Pull request overview

This PR adds JSON mode support to Scotty, allowing error responses to be returned as JSON instead of HTML when the jsonMode flag is enabled in Options.

Added a runtime jsonMode flag to Options (defaults to False)
Updated all error handlers to return JSON-formatted responses when JSON mode is enabled
Fixed the error message for FormFieldNotFound to say "Form field" instead of "Query parameter"
Fixed a build issue by changing HashMap to Map for Form construction

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
Web/Scotty/Internal/Types.hs	Added `jsonMode` field to Options data type with default value False
Web/Scotty/Trans.hs	Updated `unhandledExceptionHandler` and `notFoundApp` to support JSON responses; added NamedFieldPuns extension
Web/Scotty/Action.hs	Updated `scottyExceptionHandler` and `someExceptionHandler` to support JSON responses; fixed HashMap to Map for Form construction; fixed FormFieldNotFound error message
scotty.cabal	Added `containers` dependency for Map support
test/Web/ScottySpec.hs	Added comprehensive tests for JSON mode including 404, 500, and 400 error scenarios
examples/json_mode.hs	Added example demonstrating JSON mode usage with toggle between HTML and JSON modes
examples/scotty-examples.cabal	Added scotty-json-mode executable configuration

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-05T19:49:34Z

scotty.cabal

                       blaze-builder         >= 0.3.3.0  && < 0.5,
                       bytestring            >= 0.10.0.2 ,
                       case-insensitive      >= 1.0.0.1  && < 1.3,
+                       containers,


The containers dependency should include a version constraint for consistency with other dependencies in this file. Most dependencies specify version bounds to ensure build reproducibility and avoid unexpected breakage from incompatible versions.

@copilot please fix

Fixed in commit 89f49ff. Added version constraint: containers >= 0.5 && < 0.8

Web/Scotty/Trans.hs

double check that we add utf-8 encoding to all json responses Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

ocramz

@copilot please add tests that show how custom error handlers affect (or don't) the returned HTTP status.

E.g, a user has previously noted:
"a custom handler will lose the raised status, e.g. when lacking a body jsonData will result in a 400, but when installing a custom handler I get a 500."

ocramz · 2026-01-06T07:42:29Z

scotty.cabal

                       blaze-builder         >= 0.3.3.0  && < 0.5,
                       bytestring            >= 0.10.0.2 ,
                       case-insensitive      >= 1.0.0.1  && < 1.3,
+                       containers,


@copilot please fix

ocramz · 2026-01-06T07:44:41Z

Web/Scotty/Trans.hs

@@ -1,4 +1,4 @@
-{-# LANGUAGE OverloadedStrings, RankNTypes #-}
+{-# LANGUAGE OverloadedStrings, RankNTypes, NamedFieldPuns #-}


@copilot don't use NamedFieldPuns

Fixed in commit 89f49ff. Removed NamedFieldPuns and updated code to use explicit field access: jsonMode opts instead of pattern matching.

…tent-Type consistency Co-authored-by: ocramz <5902760+ocramz@users.noreply.github.com>

Co-authored-by: ocramz <5902760+ocramz@users.noreply.github.com>

Copilot · 2026-01-06T08:01:12Z

@copilot please add tests that show how custom error handlers affect (or don't) the returned HTTP status.

E.g, a user has previously noted:...

Added tests in commit c222284. The tests demonstrate the current behavior where custom handlers catch exceptions before scottyExceptionHandler can set the status, resulting in 200 responses unless the custom handler explicitly calls status.

Added 4 tests showing:

Custom handler returns 200 without explicit status setting
Custom handler can manually set appropriate status (workaround with pattern matching on exception type)
This behavior applies to all ScottyException types (query params, path params, malformed JSON, etc.)

All 120 tests pass.

ocramz

@copilot add a changelog entry under 'next' describing the changes

Co-authored-by: ocramz <5902760+ocramz@users.noreply.github.com>

Copilot · 2026-01-06T08:26:31Z

@copilot add a changelog entry under 'next' describing the changes

Added changelog entry in commit 2e2bb1a. The entry describes the JSON mode feature under the "next" section, including:

jsonMode flag in Options for JSON-formatted error responses
Format: {"status": <code>, "description": "<message>"}
Content-Type: application/json; charset=utf-8
Reference to issue WAI 3.0 Compatibility #97

Initial plan

2291683

Copilot AI assigned Copilot and ocramz Jan 5, 2026

Copilot started work on behalf of ocramz January 5, 2026 18:52 View session

Copilot AI and others added 6 commits January 5, 2026 19:03

Fix HashMap/Map type mismatch in formData - add containers dependency

0505832

Co-authored-by: ocramz <5902760+ocramz@users.noreply.github.com>

Add JSON mode support to Scotty error handlers

7e2e6d7

Co-authored-by: ocramz <5902760+ocramz@users.noreply.github.com>

Add JSON mode example demonstrating HTML vs JSON error responses

f0f8930

Co-authored-by: ocramz <5902760+ocramz@users.noreply.github.com>

Fix error message for FormFieldNotFound to say 'Form field' instead o…

c52e525

…f 'Query parameter' Co-authored-by: ocramz <5902760+ocramz@users.noreply.github.com>

Use Aeson for JSON encoding in error handlers and add import comment

07d8b54

Co-authored-by: ocramz <5902760+ocramz@users.noreply.github.com>

Add response bodies to error handlers for consistency

b26cd2c

Co-authored-by: ocramz <5902760+ocramz@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Add JSON mode for default responses~~ Add JSON mode for error responses Jan 5, 2026

Copilot AI requested a review from ocramz January 5, 2026 19:28

Copilot finished work on behalf of ocramz January 5, 2026 19:28

ocramz marked this pull request as ready for review January 5, 2026 19:43

ocramz requested a review from Copilot January 5, 2026 19:43

Copilot started reviewing on behalf of ocramz January 5, 2026 19:43 View session

Copilot AI reviewed Jan 5, 2026

View reviewed changes

Apply suggestion from @Copilot

0b6af5c

double check that we add utf-8 encoding to all json responses Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

ocramz requested changes Jan 6, 2026

View reviewed changes

Copilot started work on behalf of ocramz January 6, 2026 07:48 View session

Copilot AI and others added 2 commits January 6, 2026 07:58

Fix containers version constraint, remove NamedFieldPuns, and fix Con…

89f49ff

…tent-Type consistency Co-authored-by: ocramz <5902760+ocramz@users.noreply.github.com>

Add tests demonstrating custom error handler status behavior

c222284

Co-authored-by: ocramz <5902760+ocramz@users.noreply.github.com>

Copilot AI requested a review from ocramz January 6, 2026 08:02

Copilot finished work on behalf of ocramz January 6, 2026 08:02

ocramz requested changes Jan 6, 2026

View reviewed changes

Copilot started work on behalf of ocramz January 6, 2026 08:17 View session

Add changelog entry for JSON mode feature

2e2bb1a

Co-authored-by: ocramz <5902760+ocramz@users.noreply.github.com>

Copilot AI requested a review from ocramz January 6, 2026 08:27

Copilot finished work on behalf of ocramz January 6, 2026 08:27

ocramz approved these changes Jan 6, 2026

View reviewed changes

ocramz merged commit 0d2e030 into master Jan 6, 2026
7 checks passed

ocramz deleted the copilot/add-json-mode-support branch January 6, 2026 08:34

		@@ -1,4 +1,4 @@
		{-# LANGUAGE OverloadedStrings, RankNTypes #-}
		{-# LANGUAGE OverloadedStrings, RankNTypes, NamedFieldPuns #-}

Add JSON mode for error responses #416

Add JSON mode for error responses #416

Uh oh!

Conversation

Copilot AI commented Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

JSON Mode Implementation - Complete

Changes Made

Testing

Usage

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 5, 2026

Choose a reason for hiding this comment

Uh oh!

ocramz Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ocramz left a comment

Choose a reason for hiding this comment

Uh oh!

ocramz Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

ocramz Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Jan 6, 2026

Uh oh!

ocramz left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Jan 6, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Jan 5, 2026 •

edited

Loading