Choose Text and Data Formats for People, Software, and LLMs

Choose a format from the interface contract, not from claims that one syntax is universally best for people, software, or LLMs. Identify the authoritative consumer, information that must survive, available validators, likely errors, and recovery path. Then test the actual workflow.

A useful default is:

• Markdown for human-readable structured documents;
• JSON for typed data exchange;
• XML when named nested boundaries and an existing XML ecosystem matter;
• YAML for human-maintained configuration when its rules are understood;
• CSV for one simple table; and
• ordinary prose when no program must parse the structure.

These are starting points, not rankings.

Define the interface before the format

Write:

Primary author:
Authoritative consumer:
Other consumers:
Required structure and data types:
Human editing needs:
Validation:
Error-recovery needs:
Streaming or size constraints:
Existing course, API, or project requirement:

If an assignment, API, or repository already requires a format, that contract usually decides the question. Do not convert required JSON to XML because the tags seem clearer to an AI system.

Compare the formats by their jobs

The CommonMark specification defines Markdown as a plain-text format for structured documents. RFC 8259 defines JSON’s primitive and structured value types. The XML 1.0 Recommendation defines nested elements and well-formed documents. The YAML 1.2.2 specification defines a human-oriented data serialization language. RFC 4180 documents a common CSV format while noting variation among implementations.

Specifications define syntax and processing rules. They do not prove that the content is correct or that one format improves every model’s output.

Give authority to the correct consumer

Suppose a person writes a study plan, a program schedules reminders, and an LLM suggests revisions.

If the program executes the schedule, its parsed data model must be authoritative. The human-facing explanation can be Markdown, while a validated JSON object carries the dates and task identifiers.

If the document is primarily guidance for a person, Markdown may be authoritative. A program should extract only fields governed by an explicit contract.

Do not make an LLM’s preferred presentation the authority when deterministic software must execute the result.

Use Markdown for documents

Markdown works well for:

• instructions with headings and lists;
• explanations containing code or tables;
• notes intended for line-based review; and
• prompts that combine prose with bounded examples.

Use descriptive headings and fenced code blocks. When a prompt needs clearer boundaries, XML-style tags can be embedded as delimiters:

## Task
Compare the two policies.

<policy-a>
...
</policy-a>

<policy-b>
...
</policy-b>

Those tags help name boundaries, but they do not turn the whole document into valid XML or guarantee that an LLM will obey them.

Use JSON for a typed handoff

JSON represents objects, arrays, strings, numbers, booleans, and null:

{
  "course": "CS 101",
  "tasks": [
    {"title": "Review recursion", "minutes": 30, "complete": false}
  ]
}

Use a JSON parser rather than visual inspection alone. Define required fields, allowed values, units, and whether unknown fields are rejected. A schema can add mechanical checks when the workflow justifies it.

Valid JSON can still contain an impossible date, wrong unit, invented citation, or unsafe command.

Use XML when named nesting is part of the contract

XML makes boundaries explicit:

<study-plan course="CS 101">
  <task>
    <title>Review recursion</title>
    <minutes>30</minutes>
  </task>
</study-plan>

XML fits an existing XML API, document workflow, or schema ecosystem. It can also make repeated nested sections easy to label in a prompt. Do not select it only because more punctuation appears more precise.

Use a standard parser with safe settings. Treat untrusted external entities and other advanced features as security concerns rather than implementing a parser with string operations.

Use YAML and CSV for narrower cases

YAML can make configuration pleasant to edit:

course: CS 101
tasks:
  - title: Review recursion
    minutes: 30

Use a known YAML version and parser. Quote values when implicit interpretation could change meaning, and validate the loaded structure.

CSV fits one rectangular table:

course,title,minutes
CS 101,Review recursion,30

Document columns, units, missing values, delimiter, encoding, and quotation rules. Do not use CSV when nested tasks or a complete type model are required.

Test three representations

Represent the same small study-plan handoff in Markdown, JSON, and XML. For each, record:

Information preserved:
Human editing cost:
Machine validation:
Likely malformed-output failure:
Recovery method:
Authoritative consumer:

Delete one required delimiter or closing marker. Observe:

• whether a parser rejects the input;
• whether the error identifies a useful location;
• whether a person can still recover the intended meaning; and
• whether an LLM revision preserves the contract.

Choose the format whose failure behavior and validation fit the real task, not the one that wins an abstract readability contest.

Common mistakes

• Choosing a format before identifying the authoritative consumer.
• Calling human-readable syntax unambiguous.
• Treating valid syntax as correct data.
• Assuming every Markdown tool follows the same dialect.
• Using CSV for nested or strongly typed information.
• Selecting XML only to influence an LLM.
• Asking an LLM to repair malformed data without rerunning a parser.
• Sending private information to an unapproved AI service.

Do this now

Complete the three-format comparison for one non-sensitive task. Parse the JSON and XML with approved tools, inspect the Markdown rendering, introduce one controlled error, and record which representation best fits the interface.

Log what you learned

Record only:

• Result: What did the action produce?
• Evidence: What observation, test, or source supports that result?
• Next action or unresolved question: What should happen next?

Next, compare how prose, structured documents, schemas, and code expose different parts of your reasoning.