JSON vs YAML vs TOML for AI Prompts (and When to Use Each)

Structured prompts beat prose prompts. The next question is which structured format. Here is the field guide, with copy-paste examples for each.

Why structured prompts, brieflyProse prompts ("write a blog post about X for Y in Z style") work, but they hide the structure in the prose. When the model has to guess which parts of your paragraph are the goal, which are the audience, and which are the format, it will guess wrong often enough to be annoying. Structured prompts remove the guessing. The format is the brief.I covered the smallest useful structure in [the 3-field post. This post is the next question: which serialization format. JSON, YAML, TOML, and a few others, with concrete recommendations.The three formats, side by sideJSON

    {
      "goal": "Write a 600-word blog post about prompt structure for marketing managers.",
      "audience": "Marketing managers at companies under 50 people who use ChatGPT occasionally.",
      "format": "Three sections. Each section ends with a copy-paste example. No bullet lists."
    }

Best for: code that has to parse the prompt. Anything that will be sent through a script (e.g. a Python loop, a TypeScript app, a serverless function). The parsers are universal. The errors are loud (you get a syntax error, not silent acceptance of a typo).Worst for: prompts you are writing by hand in a chat box. JSON requires quotes, commas, and braces in the right places. A trailing comma will break the whole thing, and you will not get a useful error from the model; you will just get a refusal or a fallback response.YAML

    goal: Write a 600-word blog post about prompt structure for marketing managers.
    audience: Marketing managers at companies under 50 people who use ChatGPT occasionally.
    format: |
      Three sections. Each section ends with a copy-paste example.
      No bullet lists.

Best for: prompts you are writing by hand and want to read later. No braces, no commas, no required quoting. Indentation is the structure. It looks like a config file, which means your future self will not be afraid to edit it.Worst for: deeply nested data. YAML's "Norway problem" (unquoted NO parses as boolean false in some YAML 1.1 parsers) is a real footgun, and the indentation rules bite anyone who mixes tabs and spaces. Also: YAML is a superset of JSON, which sounds great until you accidentally write a JSON string in the middle of a YAML file and watch the parser do something weird.TOML

    goal = "Write a 600-word blog post about prompt structure for marketing managers."
    audience = "Marketing managers at companies under 50 people who use ChatGPT occasionally."
    format = """Three sections. Each section ends with a copy-paste example.
    No bullet lists."""

Best for: prompts you are writing by hand that have a flat (not deeply nested) structure. TOML is explicit (= for assignment, """ for multi-line), which means the parser does not have to guess your indentation. It is the easiest of the three to read at a glance and the hardest to break with a typo.Worst for: complex nested structures. TOML's array-of-tables syntax is fine, but it is more verbose than YAML's, and the verbosity adds up fast. If your prompt has more than 3-4 levels of nesting, you are fighting TOML.When to use whichHere is the rule I actually follow, simplified:If the prompt is being generated by code: JSON. The script is the source of truth. The model receives JSON. Nothing else makes sense.If the prompt is being written by hand and is flat (1-2 levels deep): TOML. It is the easiest to edit. You will not break it with a stray space.If the prompt is being written by hand and is nested (3+ levels): YAML. The indentation-based structure is verbose but readable. Just be careful with the Norway problem and tabs.If the prompt is going into a UI field: whatever the UI is built for. Don't fight the tool.For 80% of what I write, I default to TOML. The 3-field fix from [the last post is TOML-shaped. The prompts in [the Blog Writing Factory are TOML-shaped. If you are starting out, start with TOML.What the model actually does with the formatAn honest note: the model is a language model. It does not "parse" JSON, YAML, or TOML. It pattern-matches the structure. If you give it JSON, the model will likely treat the keys as named fields. If you give it YAML, the model will likely treat the indentation as hierarchy. If you give it TOML, the model will likely treat the key = value as labeled fields.That means: pick a format that the model sees often. JSON is the most common. YAML is the second. TOML is the third but rising. The rarer the format, the more the model will struggle, especially on smaller models.For GPT-4 and Claude Sonnet, all three work. For older or smaller models, prefer JSON. For GPT-5 / Claude 4 and beyond, pick whatever you can write fastest; the model will figure it out.Common mistakesMixing formats. Do not put JSON inside YAML or YAML inside TOML. The model will treat the embedded string as a string, not as a structured field. If you need to embed structured data, escape it explicitly or move it to a separate prompt.Over-nesting. If your prompt has 5 levels of indentation, you have a code structure problem, not a prompt problem. The model does not benefit from deep nesting the way a parser does. Flat is better than nested for prompts.Using the wrong format for the tool. If your prompt is being passed to a Python function that does json.loads(prompt), you cannot send YAML. The parser will reject it. Pick the format that matches what the receiving code expects. If there is no receiving code, pick the format that you can write fastest.The full example, in all threeSame prompt, three formats. Pick whichever you would actually write.JSON:

    {
      "goal": "Write a 600-word blog post about prompt structure for marketing managers at small companies.",
      "audience": "Marketing managers at companies under 50 people who use ChatGPT occasionally and have never written a structured prompt. They are skeptical of 'AI hype.'",
      "format": "Three sections. Each section opens with a one-sentence problem statement. Each section ends with a copy-paste example. No bullet lists. No 'in conclusion.' Plain English, no jargon without a parenthetical definition.",
      "constraints": ["No em-dashes", "No 'in today's fast-paced world'", "No 'unlock the power of'"],
      "tone": "teacherly, dry, warm-but-direct",
      "examples": [
        "Good: 'Most prompts fail for the same three reasons.'",
        "Good: 'Here is the smallest structure that actually moves the needle.'"
      ]
    }

YAML:

    goal: |
      Write a 600-word blog post about prompt structure for marketing
      managers at small companies.
    audience: |
      Marketing managers at companies under 50 people who use ChatGPT
      occasionally and have never written a structured prompt. They are
      skeptical of "AI hype."
    format: |
      Three sections. Each section opens with a one-sentence problem
      statement. Each section ends with a copy-paste example. No bullet
      lists. No "in conclusion." Plain English, no jargon without a
      parenthetical definition.
    constraints:
      - No em-dashes
      - No "in today's fast-paced world"
      - No "unlock the power of"
    tone: teacherly, dry, warm-but-direct
    examples:
      - 'Good: Most prompts fail for the same three reasons.'
      - 'Good: Here is the smallest structure that actually moves the needle.'

TOML:

    goal = "Write a 600-word blog post about prompt structure for marketing managers at small companies."
    audience = "Marketing managers at companies under 50 people who use ChatGPT occasionally and have never written a structured prompt. They are skeptical of 'AI hype.'"
    format = """Three sections. Each section opens with a one-sentence problem statement. Each section ends with a copy-paste example. No bullet lists. No 'in conclusion.' Plain English, no jargon without a parenthetical definition."""
    constraints = ["No em-dashes", "No 'in today's fast-paced world'", "No 'unlock the power of'"]
    tone = "teacherly, dry, warm-but-direct"
    examples = [
      'Good: Most prompts fail for the same three reasons.',
      'Good: Here is the smallest structure that actually moves the needle.'
    ]

My defaultTOML for hand-written prompts. JSON when the prompt is being generated by code. YAML when I need to nest deeper than 3 levels. That is the rule. It is not the only rule, but it is the one I have not had to override in the last six months.If you want to see structured prompts in use, every prompt in [the Blog Writing Factory is TOML-shaped and includes the goal / audience / format / constraints / tone / examples fields. That is what the format decisions look like in production.Get the prompt pack that uses this formatThe Blog Writing Factory is ten TOML-shaped prompts that turn a one-line seed into a publish-ready draft. One ZIP, $14, yours forever.Buy on Gumroad. $14

Send me the rough edges if you try it. I read every message.