JSON File (.json): What It Is, How It Works + Sample Files

The basics

What is a JSON file?

A JSON file stores data as text, using a small set of rules borrowed from JavaScript: curly braces for objects, square brackets for lists, double quotes for text. Because the rules are few and strict, almost every programming language can read and write it with its standard library or a common package.

Most web APIs send and receive JSON. You also meet it as configuration (package.json, tsconfig.json, composer.json, VS Code settings), as an export format from apps and databases, and inside browser extensions and web app manifests.

Three things JSON is not:

Not JavaScript. JSON looks like a JavaScript object, but it can't hold functions, comments, undefined, dates or unquoted names. It is data only.
Not self-describing. A JSON file doesn't say what its fields mean or which are required. That is the job of documentation or a separate JSON Schema file.
Not a database. It is a file format. Some databases store JSON documents, but the file itself has no indexes, queries or locking.

Anatomy

What's inside a JSON file

JSON is built from two structures: objects, which are sets of named values in curly braces, and arrays, which are ordered lists in square brackets. They can nest inside each other as deeply as you need. Here is a small but complete file, part by part.

person.json

{
  "name": "Ada Example",
  "age": 36,
  "member": true,
  "nickname": null,
  "languages": ["en", "nl"],
  "address": {
    "city": "Utrecht",
    "postcode": "3511 AB"
  },
  "balance": -12.5,
  "joined": "2026-10-27T09:30:00Z",
  "bio": "Says \"hi\".\nLikes tea."
}

1{ … }
The root object
The whole file is one value, here an object. It could also be an array, or even a single string or number: all are valid JSON texts.
2"name": "Ada Example"
A member
A name, a colon, then a value. The name must be a string in double quotes. Members are separated by commas, and the last one has no comma after it.
3"Ada Example"
A string
Always in double quotes. Single quotes are not allowed, which is the most common reason hand-written JSON fails to parse.
4"age": 36
A number
Written in decimal, without quotes. JSON has one number type: there is no separate integer, decimal or currency type.
5"member": true
A boolean
true or false, lowercase, without quotes. "true" in quotes is a string, which code then has to compare as text.
6"nickname": null
Null
An explicit empty value. Leaving the member out and setting it to null are different things, and APIs often treat them differently.
7["en", "nl"]
An array
An ordered list in square brackets. The values can be of any type, and can be mixed, though most APIs keep each list to one type.
8"address": { … }
A nested object
Objects and arrays can contain other objects and arrays. Nesting is how JSON represents related data without a separate table.
9-12.5
A negative decimal
A minus sign and a decimal point are allowed; a plus sign, a leading zero like 07, NaN and Infinity are not.
10"2026-10-27T09:30:00Z"
A date, as a string
JSON has no date type. The usual convention is an ISO 8601 string like this one, which sorts correctly as text and carries its time zone.
11"Says \"hi\".\nLikes tea."
Escape sequences
A backslash introduces an escape: \" for a quote, \n for a line break, \\ for a backslash, \u00e9 for any character by its code. A real line break inside a string is not allowed.

The grammar

The rules, and what breaks them

The grammar takes only a few pages of RFC 8259. A parser must reject anything outside it, so a single misplaced character stops the whole file from loading. These are the mistakes that cause most errors:

Written as	Valid?	Why
`{"a": 1}`	Yes	Names in double quotes, values after a colon.
`{'a': 1}`	No	Single quotes are not allowed, for names or strings.
`{a: 1}`	No	Names must be quoted strings.
`[1, 2, 3,]`	No	No comma after the last item. JavaScript allows it; JSON doesn't.
`// note` or `/* note */`	No	JSON has no comments.
`007`, `+7`, `.5`, `0x1F`	No	No leading zeros, plus signs, bare decimal points or hex. Write `7` and `0.5`.
`NaN`, `Infinity`, `undefined`	No	Not part of JSON. Use `null` or a string.
A string with a real line break in it	No	Line breaks inside strings must be written as `\n`.
`"tab\there"`	Yes	Escapes are fine: `\t`, `\n`, `\"`, `\\`, `\/`, `\uXXXX`.
`"hello"` or `42` on its own	Yes	Any value can be the whole file, not only an object or array.

Duplicate names are legal, but unreliable

RFC 8259 says names within an object SHOULD be unique, not MUST. When a name appears twice, JavaScript's JSON.parse and Python's json module both keep the last value; the RFC notes that other implementations report an error or return every pair. sample-edge-cases.json below has a duplicate so you can see what your tools do.

Data types

Numbers, dates and other things JSON doesn't have

JSON's grammar allows a number of any length, but the program reading it has to store that number somewhere. Many, including JavaScript, store every number as a 64-bit floating-point value. RFC 8259 notes that integers between −(2^53 − 1) and 2^53 − 1 are safe; beyond that, precision is lost without warning.

Large IDs. JSON.parse in JavaScript reads 9007199254740993 as 9007199254740992. APIs with 64-bit IDs often send them as strings for this reason.
Money. 0.1 + 0.2 is not exactly 0.3 in floating point. Send amounts as integer cents (1999) or as a string ("19.99"), and say which in the documentation.
Dates and times. There is no date type. Use ISO 8601 strings such as "2026-10-27T09:30:00Z". JavaScript's JSON.stringify turns a Date into a string in this format, but JSON.parse doesn't turn it back: it stays a string.
Binary data. Images or files go in as Base64 text, which makes them about a third larger.
Not-a-number and infinity. JSON.stringify(NaN) writes null. Python's json.dumps writes NaN and Infinity by default, which strict parsers then reject; pass allow_nan=False to catch it.

Related formats

JSON variants and neighbouring formats

Because plain JSON has no comments and no trailing commas, several relaxed versions grew up around it. They are not interchangeable: a strict JSON parser rejects all of them.

Format	What it is
JSON (`.json`)	The strict format described here.
JSONC	JSON with comments. VS Code settings and `tsconfig.json` accept it. `package.json` does not: npm reads it as strict JSON.
JSON5 (`.json5`)	A superset that adds comments, trailing commas, single quotes, unquoted names, hex numbers and `Infinity`. Needs its own parser.
JSON Lines (`.jsonl`, `.ndjson`)	One complete JSON value per line, with no surrounding array. Used for logs and large datasets, because a program can read it one line at a time. The file as a whole is not valid JSON.
GeoJSON (`.geojson`)	Ordinary JSON with an agreed structure for map features, defined in RFC 7946.
JSON Schema	A JSON document that describes what another JSON document must contain, used for validation and editor autocomplete.
YAML (`.yaml`, `.yml`)	An indentation-based format for configuration. YAML 1.2 was designed so that JSON documents are also valid YAML.
XML (`.xml`)	The older markup-based format for structured data. More verbose, but with comments, attributes, namespaces and mature schema languages.

Troubleshooting

Why won't my JSON parse?

Parsers report the first character they didn't expect, which is often after the real mistake. The usual causes:

Unexpected token '<' means you received HTML, not JSON: usually an error page, a login page or a 404 from the server. Look at the raw response before looking at your code.
A trailing comma or a comment, often left by someone editing a config file by hand.
Curly quotes. Word processors and some chat apps turn " into “ and ”, which JSON doesn't accept. Copy JSON through a plain-text or code editor.
Windows paths. "C:\Users\ada" contains \U and \a, which are not valid escapes. Each backslash must be doubled: "C:\\Users\\ada".
A byte order mark (BOM). RFC 8259 says JSON must not start with one, and JavaScript's JSON.parse rejects it. Some Windows editors add one when saving as UTF-8; save as UTF-8 without BOM.
Several values in one file. Two objects one after the other, without an enclosing array, are not JSON. One object per line is the JSON Lines format, which needs a JSON Lines reader.

To find the exact position of an error, run python3 -m json.tool file.json or jq . file.json in a terminal. Both print the line and column of the first problem, and pretty-print the file if there is none.

How to

How to open, edit and convert a JSON file

View it: drag it into a browser. Firefox shows JSON as a collapsible tree with a search box; other browsers show the text, some with a pretty-print option. On a phone, a JSON file usually opens in a text viewer or a files app preview.
Edit it: use a code editor such as VS Code, which checks the syntax as you type and formats the file with the Format Document command. Avoid word processors, which change quotes.
Format or minify it: jq . in.json pretty-prints; jq -c . in.json puts it all on one line. Minifying removes only whitespace, so the data is unchanged.
Turn it into a spreadsheet: in Excel for Windows, use Data, Get Data, From File, From JSON, which opens Power Query to flatten nested data into columns. Nested arrays have no single correct flat form, so expect to choose which parts become rows.
Turn a spreadsheet into JSON: save it as CSV first, then convert it with a short script or a tool such as csvkit's csvjson.

Security

Is JSON safe?

A JSON file is data, so opening one can't run anything. The risks are in how programs read it:

Never parse JSON with eval(). It runs any code the text contains. RFC 8259 calls this an unacceptable risk; use JSON.parse or your language's JSON library.
Prototype pollution. JSON.parse safely creates a property called __proto__, but code that then deep-merges that object into another can change the prototype of every object in a JavaScript program. Skip the keys __proto__, constructor and prototype when merging untrusted data.
Size and depth. A huge or deeply nested file can exhaust memory or the call stack. RFC 8259 allows parsers to limit both; set limits on anything you accept from outside.
Secrets in config files. API keys and passwords in a committed config.json or a public link are a common leak. Keep them in environment variables or a secrets manager.

Free downloads

Sample JSON files to download

Free sample JSON files for testing APIs, parsers, uploads, encodings and size limits. Each one is valid JSON under RFC 8259.

sample-order.json · 1.4 KBDownload Open

Loading…

What's inside sample-order.json

JSON has no comments, so this file explains itself through its field names. Open it in a text editor or a browser and look for these parts.

The `_about` field
A note about the file stored as ordinary data. A field like this is the usual workaround for JSON having no comments.
Strings, booleans and null
status is a string, paid and giftWrap are booleans, and coupon is an explicit null.
Nested objects and arrays
customer holds an address object and a tags array; items is an array of objects, the shape most API lists take.
Numbers
Integers (qty), decimals (unitPrice, vatRate), a negative number (temperatureC) and exponent notation (distanceKm is 1.2e1, which is 12).
Escapes
A quoted word inside a string (\"Hello, world\"), a line break written as \n, and a Windows path with every backslash doubled.
Unicode two ways
text.raw and text.escaped hold the same characters, once as UTF-8 and once as \u escapes. The emoji needs two escapes, a surrogate pair. A correct parser returns identical strings for both.
Empty values
An empty object, an empty array and an empty string, which some code mistakes for missing values.

All sample JSON files

Sample order (API response)
sample-order.json · 1.4 KB (1,450 bytes)
A realistic, pretty-printed order with every JSON type, nesting, escapes and the same text as raw UTF-8 and as \u escapes.
- Mocking an API response
- Teaching the parts of a JSON file
Download Open
Minimal JSON file
sample-minimal.json · 19 bytes
One object with one member: {"hello": "world"} and a final line break.
- Parser smoke tests
- Upload and content-type checks
Download Open
Unicode test
sample-unicode.json · 2.7 KB (2,781 bytes)
Greetings in 14 languages, including right-to-left Arabic and Hebrew, as raw UTF-8 and again as \u escapes, plus emoji sequences, a decomposed é and invisible characters.
- Finding encoding bugs in pipelines
- Checking string length and normalisation handling
Download Open
Edge cases parsers disagree on
sample-edge-cases.json · 688 bytes
Valid JSON that different parsers read differently: an integer above 2^53, 1E400, -0, a duplicate name, an empty name, a \u0000 character and a lone surrogate (\ud800) that jq 1.7 rejects.
- Comparing JSON libraries
- Testing validation and error handling
Download Open
500 levels of nesting
sample-deep-nesting.json · 10.7 KB (10,954 bytes)
Objects nested 500 deep on one line. Python's json module reads it; jq 1.7 refuses anything deeper than 256 levels.
- Checking nesting limits
- Recursion and stack-depth tests
Download Open
1 MB JSON file
sample-1mb.json · 1 MB (1,048,576 bytes)
An array of fictional records, pretty-printed and padded to exactly 1,048,576 bytes (1 MiB).
- Upload and request-size limits
- Parser performance
Download Open

Ways to test with them

Size limits: sample-1mb.json is exactly 1,048,576 bytes, so you can test a request or upload limit right at the boundary.
Number precision: parse sample-edge-cases.json and check bigInteger. If it comes back as 9007199254740992, your parser uses floating point and will corrupt large IDs.
Encoding: run sample-unicode.json through your pipeline and compare greetings with greetingsEscaped. Any Ã or â€ means a step read UTF-8 as another encoding.
Depth limits: an API that accepts JSON should reject sample-deep-nesting.json with a clear error, not crash.

Free to use for testing, teaching and demos, commercially or not, with no attribution needed. A link back to this page is always appreciated.

Put it online

Have a JSON file? Give it a link.

Drop a JSON file on 99helpers and it gets its own web address. Browsers display it, and scripts, apps and API mocks can fetch it straight from the link.

Put a JSON file online

Questions

JSON files, frequently asked

What does JSON stand for?

JavaScript Object Notation. The syntax comes from JavaScript's way of writing objects, but JSON is a data format that every major language can read and write.

How do I open a JSON file?

Any text editor opens it. To read it more easily, drag it into a browser (Firefox shows it as a collapsible tree) or open it in a code editor such as VS Code, which can format it.

Can JSON have comments?

No. The standard has no comment syntax and strict parsers reject // and /* */. Use a field such as "_comment", or a relaxed format like JSONC or JSON5 if the tool that reads the file supports it.

Why does my JSON say Unexpected token?

The parser met a character the grammar doesn't allow there. Common causes are a trailing comma, single quotes, a comment, curly quotes from a word processor, or an HTML error page received instead of JSON.

What's the difference between JSON and a JavaScript object?

JSON is text with stricter rules: names must be in double quotes, and there are no functions, comments, undefined, dates or trailing commas. JSON.parse turns the text into a JavaScript object, and JSON.stringify does the reverse.

Is JSON better than XML?

For web APIs and app data, JSON is usually simpler and smaller. XML still suits documents with mixed text and markup, formats that need namespaces, and industries with established XML schemas.

How do I convert JSON to Excel or CSV?

In Excel for Windows, use Data, Get Data, From File, From JSON. On the command line, jq can turn an array of flat objects into CSV. Nested data has to be flattened first, and you choose how.

Should a JSON file start with a BOM?

No. RFC 8259 says implementations must not add a byte order mark to JSON sent over a network, and JavaScript's JSON.parse fails on one. Save as UTF-8 without BOM.

Is there a size limit for JSON files?

The format sets none, but parsers may limit size, nesting depth and number range. Very large datasets are often stored as JSON Lines instead, so they can be read one record at a time.

Related formats

Other file types explained

XML file CSV file JavaScript file HTML file All file types

Keep going

Host a JSON file

Put a JSON file online at its own address in seconds.

Share a JSON file

Send JSON as a link instead of an attachment.

Host a website

Put a whole folder of pages, scripts and data files online.

Sources

Last reviewed 27 October 2026.