Fix/json system prompt customization

[Waqar53]

Add json_system_prompt parameter for Mode.JSON allowing users to customize
or disable the default system prompt.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)

Related Issues

Fixes #1514

Changes Made

• Add json_system_prompt parameter to handle_json_modes()
• Support {schema} placeholder for JSON schema injection
• Empty string skips prompt modification entirely
• 8 comprehensive unit tests

---

Note

Enables customizable system prompts for OpenAI JSON modes while preserving default behavior.

• Adds json_system_prompt support in handle_json_modes for Mode.JSON, Mode.MD_JSON, and Mode.JSON_SCHEMA; supports {schema} substitution and empty-string to disable system prompt changes
• Updates dispatcher in response.py to pass json_system_prompt through mode handlers
• Keeps default "genius expert" prompt when unset; avoids modifying system message for JSON_SCHEMA
• Adds comprehensive tests covering custom prompt, placeholder substitution, skipping, existing system message append, and mode-specific behavior

^{Written by Cursor Bugbot for commit 2bfb3ca. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

[cursor]

Format string crashes on prompts with curly braces

Medium Severity

Using str.format() for placeholder substitution causes a KeyError if json_system_prompt contains curly braces other than {schema}. Users may reasonably want to include JSON examples in their prompt like "Return JSON like: {"id": 1} matching {schema}", which will crash. Literal braces require escaping as {{ and }}, but this limitation isn't documented. Consider using a safer substitution method like str.replace("{schema}", json_schema) instead.

 

[Waqar53]

Thanks for the feedback, @jxnl That makes sense — I was approaching this from a simple use case (customizing or disabling the prompt), but I agree a V2 could benefit from a more principled design. While working on this, a few ideas came up: - *Template engine* — Support multiple placeholders like {schema}, {model_name}, {description} - *Prompt builders* — Composable sections (schema, instructions, examples) with presets - *Mode-specific configs* — Different strategies per mode (JSON vs JSON_SCHEMA vs MD_JSON) I’d be happy to help implement whichever direction you choose for V2. Let me know if you’d like me to iterate on this PR or close it in favor of a more comprehensive solution.

…

On Mon, 26 Jan 2026 at 20:26, Jason Liu ***@***.***> wrote: *jxnl* left a comment (567-labs/instructor#2031) <#2031 (comment)> I'm working on a V2, and I'll try to think a little bit harder about how we can parametrize the system prompt a little bit. — Reply to this email directly, view it on GitHub <#2031 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BBEYB4AS6MOCPNRO2PN7K2D4IYTKPAVCNFSM6AAAAACS2WX6PGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTQMBQGAYTMNJQHA> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[jianxux]

🔧 Fix for Ruff lint failure:

Remove the unused imports in tests/test_json_system_prompt.py:

- import json
...
- from unittest.mock import MagicMock
+ from unittest.mock import patch

(Keep only the imports that are actually used in the test file.)