What a JSON file is and why you might create one

A JSON file is a plain text document that stores information in a format computers can read and organize. JSON stands for JavaScript Object Notation. It uses straightforward symbols — curly braces, square brackets, colons, and commas — to structure data so that programs can understand what each piece of information means.

You might create a JSON file to store a list of contacts with their phone numbers and email addresses, keep track of household inventory, record expenses by category, or back up settings from a program you use. JSON files are readable by almost any program and take up very little space, which makes them useful for keeping organized records that you can move between devices or share with others.

Unlike a spreadsheet or database, a JSON file is just text. You can open it in Notepad, Word, or any text editor. This also means you can read it without special software, and it will look the same on a Windows computer, a Mac, or a Linux machine.

Key Takeaways

  • A JSON file is plain text that uses braces, brackets, and colons to organize information in a way programs can understand.
  • You create a JSON file by typing the data structure directly into a text editor like Notepad, then saving it with a .json file extension.
  • JSON uses objects (wrapped in curly braces) to hold related information and arrays (wrapped in square brackets) to hold lists of items.
  • Every piece of data in JSON must be paired with a label, and text values must be wrapped in quotation marks.
  • You can test whether your JSON file is correctly formatted by pasting it into an online JSON validator before you rely on it.

The basic structure: objects and arrays

JSON organizes information using two main containers. An object holds related pieces of information together and is wrapped in curly braces. Inside an object, each piece of information has a label (called a key) and a value. For example, a contact object might look like this:

{ "name": "Sarah Chen", "phone": "555-0147", "email": "sarah.chen@email.com" }

An array is a list of items, wrapped in square brackets. If you want to store multiple contacts, you put them in an array of objects:

[ { "name": "Sarah Chen", "phone": "555-0147", "email": "sarah.chen@email.com" }, { "name": "Marcus Webb", "phone": "555-0293", "email": "marcus.webb@email.com" } ]

Notice that text values are always wrapped in quotation marks, and each key and value are separated by a colon. Items in a list are separated by commas, but there is no comma after the last item in a list or object.

Creating your first JSON file in a text editor

Open Notepad (on Windows, search for "Notepad" in the Start menu) or TextEdit (on Mac, open Applications > Utilities > TextEdit). Do not use Microsoft Word or Google Docs — these add invisible formatting that will break your JSON file.

Type your data using the structure described above. Start with an opening curly brace if you are storing a single object, or an opening square bracket if you are storing a list. Add your information with labels and values, remembering that text must be in quotation marks and items must be separated by commas. Close with a matching curly brace or square bracket.

Once you have typed your data, go to File > Save As. In the filename field, type a name followed by .json — for example, "contacts.json" or "household-inventory.json". Make sure the file type is set to "All Files" or "Plain Text", not "Word Document" or "Rich Text Format". Choose where you want to save it (your Documents folder or Desktop is usually easiest to find later), then click Save.

Common rules that prevent errors

JSON has strict rules about formatting. Text values must be wrapped in straight quotation marks, not curly ones. Numbers do not need quotation marks — you can write "age": 34 without quotes around the 34. Boolean values (true or false) also do not need quotes.

Every opening brace or bracket must have a matching closing one. If you open with {, you must close with }. If you open with [, you must close with ]. Commas separate items in a list or properties in an object, but you never put a comma after the last item.

Keys (the labels on the left side of the colon) must always be text wrapped in quotation marks. Values (on the right side) can be text in quotes, numbers without quotes, true or false, or even another object or array nested inside.

A common mistake is forgetting to close a quotation mark or brace. If your file does not work, read through and count: every opening quotation mark should have a closing one, and every opening brace or bracket should have a closing one.

Checking your JSON file for errors

Before you rely on a JSON file you created, paste its contents into an online JSON validator to check for mistakes. Search for "JSON validator" in your web browser. Popular options include JSONLint and the JSON formatter at jsoncrack.com. Copy all the text from your JSON file, paste it into the validator, and click the button to validate or format.

If the validator finds an error, it will tell you which line the problem is on and what is wrong — for example, "missing comma on line 5" or "unexpected character on line 12". Go back to your text editor, find that line, and fix the issue. Common problems are missing commas between items, unclosed quotation marks, or mismatched braces.

Once the validator says your JSON is valid, you can save the file and use it. Many programs that work with JSON will also tell you if there is a formatting error when you try to open the file, so the validator is a safety check before you depend on it.

Organizing multiple records in a single JSON file

If you are storing many similar items — like a list of books you own, expenses by month, or household inventory — structure your JSON file as an array of objects. Each object represents one item and contains the same keys. This makes it straightforward to read and also makes it straightforward for programs to process your data.

For a book inventory, your file might look like this:

[ { "title": "The Midnight Library", "author": "Matt Haig", "year": 2020, "read": true }, { "title": "Project Hail Mary", "author": "Andy Weir", "year": 2021, "read": false } ]

Notice that all objects have the same keys (title, author, year, read), even if some values are different. This consistency makes your file easier to search through or import into another program later. If you need to add more books, just add another object to the array, remembering to put a comma after the previous object.

Editing and updating your JSON file

To change information in your JSON file, open it in your text editor, make the changes you need, and save the file. You can add new objects to an array by typing a comma after the last object, then adding a new one. You can remove an object by deleting it and the comma before it (unless it is the last object in the array).

Be careful when editing to keep the structure correct. If you add a new key to one object, consider adding it to all objects in the array, even if some values are blank. This keeps your file consistent and prevents problems if you later use a program to read it.

After you make changes, save the file and run it through a JSON validator again to make sure you did not accidentally break the formatting. This takes only a few seconds and prevents errors from building up over time.

Frequently Asked Questions

Can I open a JSON file in Excel or Google Sheets?

You can open a JSON file in Excel or Sheets, but the data will not automatically arrange into columns and rows the way it does with a spreadsheet file. It is better to open JSON in a text editor if you want to edit it, or use a program designed to work with JSON. If you want spreadsheet-style organization, consider saving as a CSV file instead.

What is the difference between JSON and CSV?

CSV (comma-separated values) is simpler and works better for flat lists of data with columns and rows, like a contact list or expense log. JSON is better when your data has nested information or complex relationships. For most household records, either works — choose whichever is easier for you to read and edit.

Do I need special software to create a JSON file?

No. Any text editor that comes with your computer — Notepad on Windows or TextEdit on Mac — is enough. Avoid word processors like Word or Google Docs because they add hidden formatting. If you create many JSON files, you might later try a code editor like Visual Studio Code, which highlights errors and makes formatting easier, but it is not required to start.

What happens if I accidentally delete a comma or brace?

Your JSON file will not work until you fix it. A program trying to read it will report an error. This is why checking your file with a JSON validator before you rely on it is important — the validator will tell you exactly where the problem is, making it straightforward to find and fix.

Can I use JSON to back up settings from a program I use?

Some programs let you export settings as JSON, and you can then import them back later or on another device. Check your program's settings or preferences menu for an export or backup option. If it offers JSON as a format, that is a good choice for keeping a readable backup that you can move between computers.