Human-friendly YAML, Machine-robust JSON: The Sweet Spot for Prompt Management #202

This article might be a "continuation of the last one."
Last time, I talked about switching between TEXT / YAML / JSON depending on the use case. as a topic.

This time, as a follow-up, I'm going to dig a bit deeper into the operational pattern that feels most natural to me right now—
"Input as YAML, Output as JSON."

Prompts get bloated. The more they bloat, the more of a nightmare they become to maintain.

To be honest, I'm the type who keeps adding to prompts on a whim, only to realize I've turned them into something pitch-black, like a "secret sauce" that's been simmering forever...

And when it comes time to fix them, this happens:

• Wait, where am I supposed to touch...

• I touched it and broke something else...

• In the end, I can't read the whole thing...

This isn't a matter of sense.

I've decided the cause is a lack of structure.

Conclusion: Write in YAML, finalize in JSON (Hybrid).

Change your perspective.

• Blueprint for human editing → YAML

• Deliverable for machine consumption → JSON

So, the method least prone to accidents is "Write in YAML, finalize in JSON."

Why JSON is suitable as a "deliverable"

JSON is "lightweight, text-based, and language-agnostic," with minimal rules. Because of that, parsing and validation tend to be more stable.

Why YAML is suitable as a "blueprint"

YAML allows for comments and is easier to keep looking clean. Furthermore, YAML 1.2 was organized so that "JSON can be treated as an official subset" (it's written that way in the specification too). yaml.org

Points to note for usage

1) Indentation errors

YAML structure is determined by indentation. A single character shift changes the meaning.
→ Solution: Fix indentation at 2 spaces, and assume a formatter is used.

2) Implicit interpretation (type inference)

In terms of specifications, the recommended schema for YAML 1.2 treats bools basically as true/false. Things like yes/on are treated as strings.
However, in reality, due to compatibility reasons, libraries may treat on/off as bools (*The official PyYAML documentation also shows behavior where on/off are treated as boolean values).
→ Solution: Use quotes if you want them to be strings. Establishing a 'quoting convention' within the team reduces accidents.

3) Safe loading (this is often misunderstood)

It's not that 'YAML is dangerous,' but rather that it can become dangerous if handled with unsafe loading methods.
The official PyYAML documentation clearly warns that using yaml.load on untrusted input is not safe and recommends yaml.safe_load.
→ Solution: Use safe_load for external input, or accept it as fixed JSON from the start.

A standard configuration to prevent getting lost: Input YAML → Output JSON

If you have these two conditions—'beginners will touch it' and 'scripts/renderers will receive it later'—I think this is the sweet spot.

Input is YAML, output is JSON

• Users fill in YAML (easy to read)

• Have the AI output JSON at the end (less prone to breaking)

• Validate the received JSON before using it (even more robust)

For copy-pasting: Minimal template

① Humans touch it (YAML)

goal: "このプロンプトで達成したいこと"
style:
  tone: "例：ミニマル、フラット、清潔感"
  avoid:
    - "読めない文字"
    - "手の崩れ"
vars:
  subject: "差し替える主役"
deliverable:
  format: "json"

② Pass it to machines (JSON: AI's final output)

{
  "goal": "...",
  "style": { "tone": "...", "avoid": ["...", "..."] },
  "vars": { "subject": "..." }
}

③ 'Instructions' used for conversion (the ones you throw at the AI)

上のYAMLを解釈して、厳密なJSONのみを出力してください。
説明文・コメント・コードブロック・余計なキーは禁止。
JSONが壊れていないことを確認してから出力してください。

Summary

YAML is a 'blueprint for humans,' and JSON is a 'deliverable for machines.'
Right now, I feel like 'writing in YAML and finishing with JSON' is the least accident-prone way.
But the right answer depends on the person, right? Which one does everyone use? (TEXT group / YAML group / JSON group)

……Am I the only one thinking about this? lol
Well, TEXT is fine too.

Except when you're 'explaining' super long TEXT prompts lol

#PromptDesign #StructuredPrompt #PromptOperations #PromptManagement #PromptTemplate #YAML #JSON #Validation #SchemaDesign #PyYAML #GenerativeAI #ChatGPT #LLM #AIUtilization #Engineering #Development #Automation #Programming #Workflow #KnowledgeSharing