---
title: "JSON, YAML and Markdown Explained"
description: "JSON, YAML and Markdown are three plain-text formats you will meet constantly. Learn what each is for and how to read them at a glance."
type: "fundamental"
locale: "en"
category: "concepts"
canonical: "https://agenticschool.dev/fundamentals/json-yaml-markdown"
dateModified: "2026-06-12"
---

# JSON, YAML and Markdown Explained

- Category: concepts
- Updated: 2026-06-12
- Keywords: JSON, YAML, Markdown, config files, data formats
- Canonical URL: https://agenticschool.dev/fundamentals/json-yaml-markdown
- Locale: en

> JSON, YAML and Markdown are three plain-text formats you will meet constantly. Learn what each is for and how to read them at a glance.

JSON, YAML and Markdown are three plain-text formats you will run into constantly when building anything. JSON and YAML both store structured data like settings and lists, while Markdown is for writing formatted text such as documentation and notes. None of them are programming languages; they are just agreed ways to write information so that both people and programs can read it. Once you can recognise the three, most config files stop looking scary.

## JSON: data for machines

JSON (JavaScript Object Notation) stores data as key and value pairs, with curly braces and quotes. It is everywhere: API responses, package files, app settings. It is strict, so a single missing comma or quote breaks it.

```json
{
  "name": "my-app",
  "version": "1.0.0",
  "private": true
}
```
Keys and string values are always in double quotes.

## YAML: data for humans

YAML stores the same kind of data as JSON but uses indentation instead of braces, which makes it easier to read and write by hand. It is common in workflow and deployment config. The catch is that spacing matters: YAML uses spaces for indentation, never tabs.

```yaml
name: my-app
version: 1.0.0
private: true
```
Same data as the JSON above, indentation instead of braces.

## Markdown: formatted writing

Markdown is for text, not data. You add simple symbols to plain text to mark headings, bold, lists and links, and it renders as nicely formatted content. This page, most READMEs, and AI agent instruction files like CLAUDE.md are all Markdown.

```markdown
# A heading

Some **bold** text and a list:

- first item
- second item
```
A "#" makes a heading; "**text**" makes it bold; "-" makes a list.

## How to tell them apart

A quick rule of thumb settles most confusion. If you see curly braces and lots of quotes, it is JSON. If you see clean indentation with colons and no braces, it is YAML. If you see "#" headings and "-" bullets meant to be read by a human, it is Markdown. You do not have to write any of them perfectly by hand, because your AI agent generates and edits these files for you. What helps is recognising which is which, so when a tool asks for "a YAML config" or "a JSON file" you know what it expects and can spot an obvious mistake at a glance.

## FAQ

### When do I use JSON vs YAML?

They store the same kind of data. JSON is stricter and common in code and APIs; YAML is friendlier to read and write by hand and common in config. Often the tool you use decides which one you need.

### Is Markdown a programming language?

No. Markdown is a simple way to format text with plain symbols. It is used for documentation, notes and AI instruction files, not for logic or data.

### Why does my YAML keep breaking?

Almost always indentation. YAML uses spaces, never tabs, and the number of spaces matters. Line things up consistently and most YAML errors disappear.