What Is a JSON File? A Beginner’s Guide With JavaScript Examples

A JSON file is a plain text file that stores structured data using the JSON (JavaScript Object Notation) format. It usually has a .json extension and is commonly used for configuration files, APIs, data exports, and communication between a website and a server.

What JSON looks like

JSON stores data as key-value pairs and arrays. Keys are always wrapped in double quotes, values are separated from keys with colons, and multiple pairs are separated by commas.

{

"name": "Sarah",

"email": "sarah@example.com",

"age": 29,

"active": true,

"skills": ["WordPress", "PHP", "SEO"],

"address": {

"city": "Cape Town",

"country": "South Africa"

}

In this example:

"name", "email", and "age" are keys.
"Sarah", "sarah@example.com", and 29 are values.
"skills" is an array.
"address" is a nested object.
true is a boolean value.

JSON supports strings, numbers, booleans, arrays, objects, and null. It does not support comments.

JSON vs JavaScript objects

JSON looks similar to JavaScript objects, but it is text-based and has stricter rules. For example, JSON keys must use double quotes, while JavaScript object keys do not have to.

// JavaScript object

const user = {

age: 29

};

// JSON

const userJson = `{

"name": "Sarah",

"age": 29

}`;

A JSON file is simply a text file saved with the .json extension. Its standard MIME type is application/json.

Convert JSON to JavaScript

Use JSON.parse() to turn a JSON string into a JavaScript object or array.

const json = `{

"name": "Sarah",

"age": 29,

"skills": ["WordPress", "PHP", "SEO"]

}`;

const user = JSON.parse(json);

console.log(user.name); // Sarah

console.log(user.skills[0]); // WordPress

Demo

const json = `{

"name": "Sarah",

"age": 29,

"skills": ["WordPress", "PHP", "SEO"]

}`;

const user = JSON.parse(json);

document.getElementById("output").textContent =

user.name + " knows " + user.skills.join(", ");

</script>

Output

Sarah knows WordPress, PHP, SEO

Convert JavaScript to JSON

Use JSON.stringify() to convert a JavaScript object into a JSON string. This is useful when sending data to an API or saving it in a file.

const user = {

age: 29,

skills: ["WordPress", "PHP", "SEO"]

};

const json = JSON.stringify(user, null, 2);

console.log(json);

Output

{

"name": "Sarah",

"age": 29,

"skills": [

"WordPress",

"PHP",

"SEO"

]

}

The 2 adds two-space indentation, making the JSON easier to read.

Load a JSON file with JavaScript

You can load a JSON file in the browser using the Fetch API. The response.json() method reads the response and converts the JSON into a JavaScript value.

Create a file called users.json:

[

{

"id": 1,

"name": "Sarah",

"role": "Web Developer"

{

"id": 2,

"name": "James",

"role": "SEO Specialist"

}

]

Then load and display it:

async function loadUsers() {

const response = await fetch("users.json");

const users = await response.json();

const list = document.getElementById("user-list");

users.forEach(user => {

const item = document.createElement("li");

item.textContent = `${user.name} — ${user.role}`;

list.appendChild(item);

});

}

loadUsers();

</script>

Output:

- Sarah — Web Developer

- James — SEO Specialist

Read a local JSON file

If you want users to upload a JSON file, use the File Reader API.

document.getElementById("json-file").addEventListener("change", event => {

const file = event.target.files[0];

if (!file) return;

const reader = new FileReader();

reader.onload = () => {

try {

const data = JSON.parse(reader.result);

document.getElementById("result").textContent =

JSON.stringify(data, null, 2);

} catch (error) {

document.getElementById("result").textContent =

"Invalid JSON file.";

}

};

reader.readAsText(file);

});

</script>

This lets a visitor select a .json file, validates it, and displays its formatted contents.

Send JSON to a server

JSON is widely used when submitting data to APIs. Convert your JavaScript object to JSON with JSON.stringify(), then send it with fetch().

async function saveContact() {

const contact = {

email: "sarah@example.com",

message: "I need WordPress maintenance help."

};

const response = await fetch("https://example.com/api/contact", {

method: "POST",

headers: {

"Content-Type": "application/json"

body: JSON.stringify(contact)

});

const result = await response.json();

console.log(result);

}

The Content-Type: application/json header tells the server that the request body contains JSON.

Handle JSON errors safely

Invalid JSON will cause JSON.parse() to throw an error. Always use try...catch when parsing JSON from user input, files, or external sources.

const badJson = `{

"name": "Sarah",

"age": 29,

}`;

try {

const data = JSON.parse(badJson);

console.log(data);

} catch (error) {

console.error("Invalid JSON:", error.message);

}

The example above fails because JSON does not allow a trailing comma after "age": 29.

Common uses for JSON files

APIs: Send and receive structured data between a browser, mobile app, or server.
Configuration files: Store settings such as database details, feature flags, and build options.
Website content: Store product details, FAQs, testimonials, or blog settings in a structured format.
JavaScript projects: Files such as package.json store project information and dependencies.
WordPress block themes: Modern WordPress themes can use theme.json to define global styles, colours, typography, and spacing.
Data imports and exports: Move records between systems in a readable, portable format.