Imagine a messy desk vs a filing cabinet.
Both hold the same information. But only one of them lets you find anything. This whole module is about turning messy desks into filing cabinets — which, in code, means giving your data a shape.
Shaping data is the quiet move that turns text a human wrote into a thing a program can use. Every piece of software you've ever touched runs on shaped data underneath. This module is the first time you'll make your own.
Pick a collection you'd like to organize.
Data shapes are designed for collections — groups of similar things. A single fact doesn't need a shape. Fifty facts about fifty similar things absolutely do.
Notice the pattern: all six are groups of "things with similar fields." Each Pokemon card has a name + attack + HP. Each book has a title + author + pages. Each friend has a name + their thing. Collections are how shapes become useful.
Every piece of data is one of three shapes.
Three shapes cover almost all the data in the world. Master these three and the rest is just combinations.
Value
A single word, number, or true/false. The simplest possible shape — just one piece of information, alone.
3
true
Array
A list of values, one after another, in a specific order. Made with square brackets. Perfect for anything you'd call "a list of."
Object
A box with labels on each piece inside. Made with curly braces. Perfect for describing one thing with multiple properties.
"name": "Buddy",
"age": 3
}
The secret is that these three can nest inside each other. An array of objects. An object whose values are arrays. An object whose values are other objects. Almost every real-world data structure is some combination of the three.
A collection of similar things is almost always an array of objects — a list of labeled boxes that all have the same labels. That's the single most common shape in all of software.
JSON is how shapes get written down.
JSON (pronounced "jay-sawn") is the universal language for writing shaped data. Every language in the world — Python, JavaScript, Swift, Rust — can read and write JSON. It's how programs talk to each other.
// A list of dogs — the most common shape in software // An ARRAY (the brackets) of OBJECTS (the braces) [ { "name": "Buddy", "breed": "golden retriever", "age": 3, "quirks": [ "only answers in a higher pitch", "refuses normal treats", "barks at Mr Peterson specifically" ] }, { "name": "Mochi", "breed": "shiba inu", "age": 5, "quirks": [ "sits like a human watching TV", "refuses to walk in the rain", "knows the sound of her leash from any room" ] } ]
Read the shape top to bottom. Outer brackets
[ ]
= this is a list. Each object inside
{ }
= a labeled box for one dog. Inside each box, every
label has a value — and some values are their own arrays (like
quirks).
That's nesting. That's the whole idea.
The rules of JSON are simple: strings get double-quotes, numbers don't, labels always need quotes too, and every value except the last one in a block needs a comma after it. That's it. Three rules.
Type JSON on the left. See cards on the right.
A real JSON editor. Every time you type, the editor parses your data and renders each object as a little card. If you break the syntax, you'll see a helpful error instead. Your collection (—) is already preloaded.
Two shapes can hold the same data and still be different.
Knowing JSON isn't the same as knowing how to shape data well. Two judging rounds.
Round 1. Two ways to store a list of books. Which shape is better?
Round 2. Two ways to store a list of friends and their favorite foods. Which shape is better?
Five things to remember when shaping data.
- Use an array for lists. Anything you'd call "a list of" or "all my" becomes an array.
- Use an object for one thing. Anything you'd describe with multiple labels becomes an object.
- Keep shapes consistent. Every item in a list should have the same shape. No exceptions you can avoid.
- Give every field a meaningful label. Not x, not data1. If you can't name a field, you don't understand it yet.
- When in doubt, wrap in an array. "One favorite food" and "three favorite foods" should use the same shape — an array with 1 or 3 items. Not a string and an array.
You now speak JSON.
The universal language of shaped data. Every program you'll write from here on uses some version of this idea.
What you just learned
- Unshaped data is a messy desk. Shaped data is a filing cabinet.
- Every piece of data is one of three shapes: value, array, or object.
- The most common shape in all of software is an array of objects — a list of labeled boxes with the same labels.
- JSON is how you write shaped data down. Every programming language can read it.
- Consistent shapes beat prettier ones. If every item in a list has the same fields, everything gets easier.
- A shape is taste applied to data. This is where Code Club starts meeting Skills Workshop.
Notice how a Skills Workshop YAML Skill is just JSON with a different
syntax. facts
is an array. Each fact is a string. The personality is an object
field. You've been shaping data the whole time in Skills
Workshop — you just didn't have the word for it yet. Now you do.
In Module 02, you'll use this skill for real: you'll fetch shaped data from a real API on the internet — including Claude — and display it in your page. That's where your code stops being self-contained and starts talking to the rest of the world.
★ Before you call it done
Three questions. Same three. Every time.
These are the same three questions for every module in Kindling. They are how you check whether AI did the part it should and you did the part only you could. Tap each one to mark it true.
★ ★ ★