What is JSON? (the format your tools speak to each other)

What it actually is

JSON (short for JavaScript Object Notation) is a way to write structured data as plain text. Structured data means things with named fields, and lists of things. A JSON file is text you can open in any editor and read with your own eyes, and every language in your stack can parse it, despite the JavaScript in the name.

You can read most JSON once you know its two shapes:

Shape	Starts with	Holds	Everyday version
Object	{	named fields	a contact card
Array	[	items in order	a grocery list

An object is a contact card: labeled slots, each label paired with a value, like "name": "Ana" and "email": "ana@example.com". An array is a grocery list: items in order, no labels. The two nest freely, and that nesting is the entire trick. Your package.json is one object. An API that returns your users sends an array of objects. Each user object can hold its own array of orders, and so on down.

JSON only describes data. It has no logic and no loops, and it never runs. A contact card can’t make a phone call, and a JSON file can’t do anything to your machine by itself. Code files like vite.config.js look similar but are real JavaScript, which is why they allow comments and clever tricks while JSON stays strict.

Why your AI just did this

Your agent reads and writes JSON all day, usually without announcing it. When it says it will add a dependency, it edits package.json, which is JSON. When it calls an API endpoint and summarizes what came back, it parsed a JSON response first. Config files it touches, like vercel.json and tsconfig.json, are JSON too.

It goes one level deeper. When your agent uses a tool (function calling), the request and the result are packaged as JSON on the wire. So when it shows you a wall of braces or asks you to paste a response body, it expects JSON, the one format everything in your stack has in common.

And when your agent pins down what shape your data must have (which fields exist, what type each one is), that contract is a schema, and JSON is usually the format the schema describes.

When you’ll run into it

The greatest hits, with the exact error strings:

• npm error code EJSONPARSE when you run npm install. Your package.json stopped parsing, and npm spells out the rule a few lines down: package.json must be actual JSON, not just JavaScript.
• Expected double-quoted property name in JSON at position 42 (line 4 column 1). This is Node’s way of reporting a trailing comma: the parser saw the comma, expected another field, and found } instead. The line and column point at the spot where parsing gave up.
• Unexpected token '<', "<!DOCTYPE "... is not valid JSON in the browser console. Your code expected JSON from an API but received an HTML page, usually an error page or a login redirect. The parser choked on the first <.
• The Network tab of your browser’s dev tools. Select a request and open its Response tab to see the exact JSON the server sent back.
• API documentation. Nearly every API’s docs show example requests and responses in JSON, so you can see the shape of a service’s data before writing any code.

What to check

• Paste the full parse error into your agent and ask it to fix and validate the file. Trailing commas and missing quotes are one-shot fixes.
• Check the last item inside every { } and [ ] when you edit JSON by hand. A comma after the final item is illegal in JSON, and it is the number one way to break a file.
• Use double quotes around every field name and every text value. Single quotes and bare names work in JavaScript and fail in JSON.
• Strip comments out of any plain .json file. Strict JSON has no comment syntax; a looser dialect called JSONC allows them, which is why comments survive in VS Code’s settings.json but kill your package.json.
• Read the line X column Y part of a parse error before scrolling past it. It is a map reference to the broken character.

Say it like a dev

Instead of: “my file with all the brackets is broken and npm won’t run” Say: “npm fails with EJSONPARSE on package.json. Find the syntax error, fix it, and confirm the file parses.”

Instead of: “the API sent back gibberish” Say: “The response isn’t valid JSON, it looks like an HTML error page. Log the raw body and the status code before parsing.”

Instead of: “can I write notes inside this config file?” Say: “Is this file strict JSON or JSONC? If strict, remove my comments so it parses.”