ping·aiCSTU · CSE 642 · Foundations · Data formats and structures
Part A · The words

Why data formats matter

Programs, settings files and Coding Agent Apps all pass data around as text.

Four text formats cover most of what you will meet: Markdown for documents, YAML for settings, JSON for data between programs, and XML for older systems. All of them are built from two ideas: key-value pairs and lists.

If you can name the format and the structure you want, a Coding Agent App can write or fix it for you.

Slide 1 of 13

Read this deck as an article

The same content as the slides above, in one page.

Why data formats matter

Programs, settings files and Coding Agent Apps all pass data around as text.

Four text formats cover most of what you will meet: Markdown for documents, YAML for settings, JSON for data between programs, and XML for older systems. All of them are built from two ideas: key-value pairs and lists.

If you can name the format and the structure you want, a Coding Agent App can write or fix it for you.

Two places you type

A terminal takes exact commands. A Coding Agent App takes plain-language prompts.

The Terminal

A text window where you type exact commands. The shell inside it runs each command the moment you press Enter.

  • Spelling and spacing must be exact.
  • macOS and Linux use zsh or bash. Upper and lower case matter there: Git is not git.
  • Windows uses PowerShell. It does not care about case in command names, but type them as shown anyway.
  • Names inside a command, such as Linux file paths, branch names and image names, can be case-sensitive in any shell.
  • The two kinds of shell have different commands: ls -la works in zsh and bash, while PowerShell uses Get-ChildItem -Force.

Terminal command, macOS and Linux (zsh or bash, case-sensitive): ls -la

Terminal command, Windows PowerShell (command names are not case-sensitive): Get-ChildItem -Force

A Coding Agent App

It looks like a chatbot, but it does much more: it can read your project files, run commands, edit code and use tools, and it often asks your permission first. Product names and features change fast and differ a lot, so these decks use one group name for all of them.

Examples: Kiro, Claude Code Desktop, GitHub Copilot's desktop app, Google Antigravity, the Codex and ChatGPT desktop apps, OpenCode, Hermes, LangChain's Deep Agents desktop app, and others. Which one you use does not matter here.

  • Plain language is fine. Say what you want, and use the right names for things.
  • Capital letters and small slips are forgiving; the meaning is what counts.
  • It may run terminal commands for you. Read what it proposes, especially anything that deletes files or sends data.
  • Pasting a command into the prompt does not guarantee it runs as typed. Ask for the result you want, or ask the app to explain the command first.
Prompt for a Coding Agent App: “What changed in my project since the last commit? Explain it in plain words.”

The same job, two ways

Terminal command, Any shell: git status

In a terminal you type the exact command. In a Coding Agent App you describe what you want.

Six words

Each card gives the word, what it means, and a sentence you can say to a Coding Agent App.

Key-value pair
A name matched with a value: name: Ada.
Prompt for a Coding Agent App: “Turn this list of facts into key-value pairs.”
Array (list)
An ordered collection of items, such as several skills.
Prompt for a Coding Agent App: “Make skills an array, not one long string.”
Object (dictionary)
A group of key-value pairs that belong together, such as one person.
Prompt for a Coding Agent App: “Group these fields into one object per person.”
String, number, boolean, null
Text, a number, true or false, and “nothing”.
Prompt for a Coding Agent App: “Which field should be a number, not text?”
Parse
Read text in a format and turn it into data a program can use.
Prompt for a Coding Agent App: “Why does this fail to parse?”
Schema
The agreed shape of the data: which keys, and what type each value has.
Prompt for a Coding Agent App: “Write a schema for this data.”

Key-value pairs and arrays, in pictures

Key-value pairs
name → Ada; role → engineer Look up a value by its name, like a labeled drawer.
Array
[SQL, Python, Docker] Items in order. The first is at position 0 in most programming languages.
Nested
A person has a name and a list of skills Values can themselves be objects or arrays, to any depth.
A list of objects
Many people, each with name and skills The most common shape for the data behind a table.

The same fact, four ways

A person named Ada with two skills.

JSON
{ "name": "Ada", "skills": ["SQL", "Python"] } Braces, quotes and commas. Made for programs.
YAML
name: Ada, then skills: [SQL, Python] No braces; indentation shows structure. Made for people to edit.
XML
<person><name>Ada</name><skills>SQL, Python</skills></person> Every value sits in named tags.
Markdown
**Ada** — SQL, Python For readable documents, not for structured data.

Markdown

Formatted text in a plain text file (.md).

# Heading
A heading More # means a smaller heading.
**bold** and *italic*
Emphasis Wrap text in asterisks.
- item
A bullet list Start each line with a dash and a space; use 1. for numbers.
[text](https://example.com)
A link The words in brackets, the address in parentheses.
`code`
Inline code Wrap in backticks. Three backticks on their own lines make a code block.
README.md, AGENTS.md
Files you will meet Coding Agent Apps read instruction files written in Markdown.

YAML

Settings and data that people edit.

  • A key and value are written key: value, with a space after the colon.
  • A list item starts with a dash and a space. Indenting shows what belongs inside what.
  • Indent with spaces, never tabs. A wrong indent changes the meaning or breaks the file.
  • A line starting with # is a comment. Quote values that contain a colon or start with a special character, such as "3000:3000".
  • You will meet YAML in Docker Compose files and in many configuration files.

Say to your AI: “This YAML fails to parse: <paste>. Fix the indentation and tell me what was wrong.”

JSON

The format most web APIs speak.

  • An object is written in curly braces with "key": value pairs. An array is written in square brackets.
  • Keys and text values must use double quotes. Single quotes are not valid JSON.
  • Items are separated by commas, and no comma may follow the last item.
  • JSON has no comments. Values are text, numbers, true, false, null, objects or arrays.
  • A model's “structured output” is usually JSON, so a broken comma or quote breaks the program reading it.

Say to your AI: “Make this valid JSON and tell me what was wrong.”

XML

Named tags around every value.

  • Every value sits between an opening and a closing tag, such as <name>Ada</name>.
  • Tags nest inside each other to show structure, and an attribute adds detail inside a tag.
  • It is wordier than JSON. You will still meet it in sitemaps, feeds, and older enterprise systems.
  • If a system you must connect to speaks XML, ask your Coding Agent App to convert to and from JSON for your code.

Which one should I use?

Markdown
Documents people read Notes, README files, instructions for Coding Agent Apps.
YAML
Settings people edit Docker Compose, tool configuration.
JSON
Data passed between programs API requests and responses, saved results.
XML
When a standard or older system requires it Sitemaps, feeds, some enterprise tools.

Common errors and the words to use

Unexpected token / Expecting property name
JSON has a stray comma, a single quote or a missing quote Paste the JSON into your Coding Agent App and ask it to find the first invalid character.
mapping values are not allowed here
YAML has a colon inside a value Put the value in quotes.
found character that cannot start any token
YAML has a tab or a bad indent Replace tabs with spaces and align the indentation.

Say it to your Coding Agent App

Name the format, the structure you want, and paste the data.

Prompt for a Coding Agent App: “Convert this YAML to JSON and keep the key names.”
Prompt for a Coding Agent App: “Return the answer as JSON with an array called skills and a string called summary.”
Prompt for a Coding Agent App: “Find the first invalid character in this JSON and fix it.”
Prompt for a Coding Agent App: “Write this as a Markdown README with headings and a bulleted list.”
  • Remove keys, tokens and personal details before you paste data into a prompt.

Learn more from the source

Checked against the linked pages on 7 November 2026.

  • The Markdown Guide shows every basic symbol with examples.
  • yaml.org hosts the YAML specification and examples.
  • json.org shows JSON's complete grammar on one page.
  • The W3C's XML page links the standards behind XML.