ChatML vs XML Tags vs JSONL — Why Prompt Formats Differ by Model
Anyone who's worked with several LLMs has noticed that "prompt format" means slightly different things at different companies. GPT docs mention ChatML, Claude docs tell you to use XML tags, and the moment fine-tuning comes up, JSONL suddenly appears. These three are concepts at different layers, but they often get lumped under the single phrase "prompt format" and create confusion. This guide sorts the three by layer.
1. The visible API structure has already converged
Today's major LLM APIs (OpenAI Chat Completions, Anthropic Messages API, etc.) look quite similar on the surface. Sending a JSON array of objects with a role and content — {"role":"system","content":"..."}, {"role":"user","content":"..."}, {"role":"assistant","content":"..."} — as the request body has effectively become the industry-common convention. For a developer, knowing just this structure lets you call multiple providers' APIs with similar code. But this "convergence of appearance" doesn't mean "processed in exactly the same way internally."
2. ChatML: the internal format OpenAI-family models were actually trained on
ChatML (Chat Markup Language) is a special-token-based structure of the form <|im_start|>role\ncontent<|im_end|> that OpenAI used when training GPT-family models for chat. The role-based JSON message array a user sends via the API is understood to be re-assembled on the server side into this internal token format before it actually reaches the model. In other words, the JSON array is the "outer packaging" for developer convenience, and ChatML is closer to the "actually trained structure" inside it. The ChatML approach was later adopted as a chat fine-tuning format by various open-source models — Mistral, the LLaMA family, Phi — making it effectively one of the widely used conventions in the industry.
3. Claude's XML tags: not an API structure but a "convention inside the body"
Anthropic's official prompt engineering guide recommends using XML-style tags like <document>, <instructions>, <example> inside the prompt body (content) to demarcate content. Here's an easy point of confusion — this doesn't replace the Messages API's role-based structure (system/user/assistant), it's a separate recommendation about how to organize the content text inside that structure. Because Claude was trained during learning to recognize XML-tag-delimited sections as a strong structural signal, wrapping long documents, complex instructions, and examples in tags helps the model more clearly distinguish each part's role (reference document, instruction, few-shot example) — which is why it's officially recommended.
4. JSONL: a fine-tuning dataset format, not a live prompt
JSONL (JSON Lines) is at a different layer from the other two. It's not about how to structure a single conversation — it's a dataset format for packing thousands to tens of thousands of conversation examples into one file to submit for model fine-tuning. The key is one JSON object per line (of the form {"messages":[{"role":"...","content":"..."}]}), making line-by-line streaming parsing possible. OpenAI and various other providers require JSONL as the upload format for fine-tuning training data. So while ChatML and XML tags deal with "what to make the model do at this moment," JSONL is a batch format for "how to re-train the model in advance."
5. Practical conclusion: role structure is common, body organization differs by model
To summarize: the role-based JSON structure of system/user/assistant is now close to a portable common convention across providers. But how you organize the content text inside it (whether to use XML tags, markdown headers, or just plain text) depends on which structural signals each model was trained to respond to more strongly during learning. That's why the advice "XML tags work well with Claude" and "markdown headers or clear numbered lists work well with GPT" coexist — not a contradiction, but practical tips reflecting each model's learned habits.
ChatML: the actual token structure of the OpenAI/open-source family (auto-converted, you don't write it directly) · XML tags: a structuring convention you write directly inside the Claude prompt body · JSONL: a fine-tuning training dataset file format, not a live conversation
6. What this tool does
MODOO HUB's Prompt Formatter takes source text separated by line breaks (blank lines) and instantly converts it into your choice of 5 formats — ChatML, XML tags, Markdown, JSONL, Plain. You can set the system message and each message's role (User prefix), making it useful for producing text for API calls or for eyeballing several formats' output side by side to build intuition.
Frequently Asked Questions
Q. Do I need to write ChatML directly in my API request?
A. No. In most cases the OpenAI Chat Completions API takes a role-based JSON array ({"role":...,"content":...}) and is understood to convert it internally into a ChatML-like structure. You rarely assemble a ChatML token string yourself — it's a concept to know when preparing fine-tuning data or working directly with open-source models locally.
Q. Does response quality drop if I don't use XML tags with Claude?
A. Not necessarily. Short, simple requests work fine in plain text. But for complex cases — referencing a long document, or mixing multiple instructions and examples in one prompt — splitting sections with XML tags is officially recommended to help the model distinguish each part without confusion.
Q. How do I make a JSONL file?
A. Make each fine-tuning conversation example a JSON object of the form {"messages":[{"role":"system",...},{"role":"user",...},{"role":"assistant",...}]}, and append one object per line to a text file. The line break acts as the separator, so each line itself must be complete JSON.
Q. How should I use the same prompt across multiple models?
A. The system/user/assistant role structure is supported in common by most providers, so it's reusable as-is. But the details inside the body (whether to use XML tags, whether to use markdown) are safer to tune per model — rather than expecting one universal format, refer to each model's official prompt guide.