JSON Prompting

If you have been reading about prompt engineering lately, you have probably seen the new trend: JSON Prompting.

The idea is simple. Instead of writing a normal paragraph to an AI, you wrap your entire instruction inside a code block. You treat the LLM less like a chatbot and more like an API endpoint.

It looks like this:

JSON

{
  "role": "developer",
  "task": "fix error",
  "code": "print ("Hello World)",
  "error": "SyntaxError: unterminated string literal (detected at line 1)"
}

The theory is that LLMs are trained on so much code that they “understand” this structure better than natural language. And strictly speaking, that is true. Models like Claude and GPT-4 are excellent at parsing JSON.

But just because you can write your entire prompt in JSON doesn’t mean you should.

The Problem with JSON Inputs

While JSON is fantastic for machines, it is messy for humans. It is heavy on syntax. Every time you want to add a simple rule, you are dealing with curly braces, quotation marks, and commas. If you miss one comma, the structure breaks.

From a “token” perspective, standard JSON is expensive. All those brackets and quotes add up.

This is where I think the current trend gets it wrong. We are forcing a machine format onto the human part of the process.

A Better Way: The Hybrid Strategy

My preferred approach is to stop looking for one perfect format and instead use the right tool for each part of the job.

I use Markdown for the instructions, YAML for the data, and JSON only for the output.

1. Markdown for Instructions Markdown is the native language of the web. It is how the models learned to read. Using headers like “# Rules” or “## Context” creates a clear hierarchy that the model instinctively understands. It is clean, cheap on tokens, and easy to scan.

2. YAML for Input Data When you need to give the AI a persona or a list of examples, YAML is superior to JSON. It relies on indentation rather than brackets. It is readable, cleaner, and uses fewer tokens.

3. JSON for Output This is where JSON shines. When you ask the AI to reply, you absolutely want JSON. It is strict and easy for code to parse.

What This Looks Like in Practice

Instead of a messy block of JSON brackets, a “Hybrid Prompt” looks like this.

# INSTRUCTIONS
You are a travel agent. Read the user profile below and suggest 3 destinations.

# USER PROFILE (YAML)
name: Demian
budget: low
interests:
  - hiking
  - photography
  - history

# OUTPUT FORMAT
Please respond in JSON

[
  {
    "city": "Kathmandu",
    "country": "Nepal",
    "reason": "Great for hiking and low budget."
  },
  {
    "city": "Cusco",
    "country": "Peru",
    "reason": "Historic sites and photography."
  }
]