How to format JSON on a Mac
You can do this with Note My, on your own machine, with nothing pasted into a website. Here is how to lay a one-line JSON file out, what the command changes, and the one thing to decide before you run it.
JSON that came out of an API, a build tool or a configuration export usually arrives with every space squeezed out of it: one line, several thousand characters long, entirely unreadable. You want it indented so you can find the key you are looking for. You would rather not paste a production payload into a web page to get it.
This guide covers formatting JSON in Note My — where the command is, exactly what it changes, how to read the result once it is laid out, and how to find the fault when the JSON is broken.
The formatting happens entirely on your Mac. Nothing is uploaded, there is no account, and the file never leaves the machine — which is the point, if the payload holds customer records or a token.
What Format JSON does to your file
Three things, and it is worth knowing all three before you run it.
- It re-indents with two spaces per level. Two spaces is the width JSON is conventionally written in, so the result matches what the rest of your toolchain, your repository and your colleagues already expect.
- It sorts the keys of every object. Alphabetically, at every level. See the warning below.
- It accepts a top-level fragment. A bare string, number or boolean on its own counts as valid JSON here, rather than being rejected for not being an object or an array.
All three land in the editor, and the file on disk stays exactly as it was. Nothing there changes until you save, so you can format a file, read it and close it again unchanged. Undo works on it like any other edit — ⌘Z takes you straight back to the squashed line — and our auto-recovery safety net looks after the unsaved version in the meantime.
Format a JSON file
-
Open the file
Press ⌘O, or drag the file from the Finder onto the tab bar. If the payload has no
.jsonextension, or an extension macOS has handed to something else, press ⇧⌘O for File ▸ Open Anything as Text… and it opens anyway.If you are pasting rather than opening, paste as usual — the editor pastes plain text only, so a blob copied from a browser arrives as characters and not as styling you have to strip.
-
Decide the scope
The structured-text commands work on the selection if there is one, and on the whole document if there is not. So select nothing to format the entire file; select a single well-formed object inside a larger file to format only that.
-
Run the command
Choose Edit ▸ Format JSON, where it sits alongside Validate JSON, Minify JSON and the XML pair. It runs immediately, with no sheet and no confirmation to dismiss: one trip to the menu and the indented document is in front of you.
-
Read the result
The status bar's Lines counter is the quickest confirmation that something happened: a one-line file becomes a many-line file. The other counters — characters, words, spaces, selection and occurrences — update with it.
Format JSON sorts your keys — read this first
Formatting reorders every object's keys alphabetically. Key order carries no meaning in JSON itself, but it may well carry meaning to you — a hand-written config where name sits at the top, or a file under version control where a reordered diff is noise. Decide before you run it, not after.
If key order matters to you, there are two good ways to keep it and still get the readable view you came for. Format a copy rather than the original: File ▸ Duplicate Tab (⌃⌘D) gives you a second tab of the same content to format and read, leaving the original untouched. Or reach for Validate JSON, which tells you whether the document is well formed and where it is not, and never changes a character.
To see exactly what the sort moved, format the duplicate and compare the two tabs. With exactly two documents open, Quick Compare pairs them straight away in our comparison view: differing lines are tinted in place and the inspector counts them. Scrolling mirrors between the panes only while you hold ⇧ — it is a held key, not a mode you switch on — and ⎋ leaves compare mode.
Going the other way: Minify JSON
Edit ▸ Minify JSON collapses the document back to a single line with no insignificant whitespace. It uses the same scope rule — selection first, otherwise the whole document.
One difference is worth remembering: minifying leaves key order exactly as it finds it. Only formatting sorts. So format a file and then minify it and you get your data back on a single line carrying the sorted order the format gave it — worth knowing when the result is heading back into version control.
A minified file is one very long line, which is where soft wrap earns its place. Wrap is on by default and is toggled from the toolbar or the View menu — with it off, a minified payload runs off to the right for the length of the file.
When the JSON is invalid
Nothing is formatted and your text is left exactly as it was. Failure is not partial: you do not end up with the first half indented and the rest mangled.
The message you get back is the useful part. The message names a position, in the form (around line N, column M). Take that line number, press ⌘L for Go to Line, type it and you are at the problem. The field arrives pre-filled with the line you are on and selected, so you can type straight over it. A line number the file does not have is refused rather than accepted, which is itself a signal that you read the number wrong.
"Around" is doing real work in that phrase. Treat the reported line as where to start looking rather than as the exact character at fault — a missing brace or a stray comma often sits some way above it. Read upwards from that line as well as at it, and check the end of the line before it: a comma left off between two objects is the most common cause of a message that points somewhere innocent.
Two other messages you may see, both of which tell you exactly what to do next. An empty document reports "There's no content to format…" rather than doing nothing silently. And a document that is not UTF-8 text gets its own message. Our encoding handling covers both directions from File ▸ Encoding, and which one you want depends on what is on screen. If the characters look correct, choose Convert to Encoding… to write the text out as UTF-8, then try again. If the characters themselves came out garbled, choose Reload with Encoding… and open the same file under the encoding it was really written in.
Reading the file once it is formatted
Indented JSON is still a lot of text. Four things make a large document navigable.
Fold what you are not reading. Double-click a brace and everything between it and its partner collapses out of sight; double-click it again, or click where the folded text was, to bring it back. The gutter carries a marker beside every foldable block. Folding works on {}, () and [], so both objects and arrays fold. It never edits the document and never marks it as changed, so it costs you nothing on a file you are only reading.
Follow the indentation. Indentation guides are on by default, in one of ten styles chosen in Settings ▸ Guides, and the toolbar has a toggle for them. On deeply nested JSON they are the difference between counting spaces and seeing the structure.
Highlight a key everywhere it appears. Double-click an identifier and every other occurrence of it lights up, matched as a whole word rather than as a substring. The Occ counter in the status bar tells you how many there are.
Search the file, or every open file. Our find and replace opens from the toolbar's magnifying-glass button, with Case Sensitive, Whole Word and Regular Expression options, and a scope switch for this file or all open tabs. The match count updates as you type, so you can see whether a query is too broad before you replace anything with it. On a heavy payload a tighter query pays for itself — a whole-word key name rather than a fragment of one takes you to the branch you actually want, and the same search run across all open tabs answers "which of these five exports still carries that field" in a single pass.
Large JSON files
The structured-text commands have no size cutoff. A multi-megabyte export goes through the same menu item as a twenty-line fixture, so you never have to split a payload into pieces to get it laid out. Choose the command once and let it land: the whole payload comes back indented in a single move, complete from the first brace to the last, and the Lines counter jumps the moment it arrives.
Opening a file that size is just as comfortable. Our large-file engine keeps the window usable on documents that would otherwise be unwieldy, so you can scroll and read a heavy payload rather than wait on it, and the status bar carries a Large File badge on the biggest documents, so you can tell at a glance which of your open tabs is the heavy one. A file of that size stays on your Mac like any other — there is nowhere for it to be sent.
Pasting a very large payload puts a progress sheet on screen with a cancel button, so a paste you did not mean to make is not something you have to sit through.
Two habits help at that size. Save before you format, so undo is not your only way back. And when you only need one branch, select that object and format the selection alone.
Troubleshooting
The menu item did nothing visible
Check the Lines counter in the status bar. If it has not changed, the file was probably already formatted with two-space indentation and sorted keys, in which case the result is identical to what was there. If an alert appeared instead, the JSON is not valid — see above.
Only part of the file was formatted
You had a selection. The command formats the selection whenever one exists, and formats the whole document only when nothing is selected. Click once to collapse the selection, then run it again.
My JSON file opens as plain text
That is the plain-text view, and every command on this page reads the structure straight from the characters rather than from colour, so all of it behaves identically there: Format JSON, Validate JSON, folding, indentation guides and the double-click key highlight. Once the file is laid out, the indentation guides and the fold markers in the gutter give you the shape of the document at a glance. Our advanced language identifier and our syntax engine bring colour to the source files you keep open alongside it. In a plain-text document you may also see macOS's own spell-check and grammar underlines under key names — those come from the system, not from the editor, and they are underlines only: no word is ever rewritten for you.
I am worried Note My will "helpfully" change my quotes
It will not. No automatic text assistance is switched on in any mode: no automatic spelling correction, no smart quotes, no dash substitution, no text replacement, no link or data detection. A straight quote you type stays a straight quote, which is exactly what JSON requires.
I formatted the wrong file
⌘Z. Undo reverses a format the way it reverses any other edit, and one press takes the whole thing back rather than unpicking it a line at a time. Our auto-recovery safety net is quietly keeping earlier versions of your work in the background the whole time you edit, so the habit worth forming is simply to read the result before you save — undo stays available for as long as you have not committed the change to disk.
What else you can do with an open JSON file
Formatting is one command in a small set that works on the same document and shares the same selection-or-document scope. Here is the whole set, and what each one leaves behind.
| Command | What you get | Changes your text |
|---|---|---|
| Format JSON | Two-space indentation, keys sorted | Yes |
| Minify JSON | One line again, key order left alone | Yes |
| Validate JSON | Whether it is well formed, and where it is not | No |
| Format XML | An XML document laid out over indented lines | Yes |
| Minify XML | An XML document collapsed back down | Yes |
Around those five, the rest of the app is doing the work that makes a payload pleasant to sit with.
- Work on a copy. ⌃⌘D duplicates the tab, so you can format one view for reading and keep the original exactly as it arrived.
- Put two payloads side by side. With two documents open, Quick Compare pairs them in our comparison view, tints the differing lines in place and counts them in the inspector.
- Search everything you have open at once. Our find and replace switches between this file and all open tabs, with case, whole-word and regular-expression matching.
- Start from a known-good skeleton. File ▸ New from Template offers
data.jsonfrom the Languages group, out of our template library. - Open a payload that came from somewhere else. Our encoding handling reads a file back under the encoding it was really written in, and writes it out as UTF-8 when that is what you need.
Frequently asked questions
Where does Format JSON live?
In the Edit menu, with Validate JSON, Minify JSON and the XML pair grouped beside it, so the whole set is one trip away and you can see at a glance which one you want. ⌘L for Go to Line is the shortcut worth remembering alongside them, because that is how you reach the line an error message names.
How do I keep my original key order?
Read a formatted copy and leave the original as it arrived: ⌃⌘D duplicates the tab, so one view is laid out for reading while the other holds the order you started with. Validate JSON is the other route — it tells you whether the document is well formed and where it is not, and never changes a character.
Does the file get uploaded anywhere to be formatted?
The formatting happens in the app, on your Mac, and the file stays exactly where you keep it. There is no account, nothing is uploaded and no usage is reported, so there is nowhere for a payload to go. A production export with customer records in it can be laid out and read with the same confidence as a scratch file.
What about XML?
The same Edit menu has Format XML and Minify XML, with the same selection-or-document scope: select one element to lay out that branch alone, or select nothing and lay out the whole document. Once it is indented, the rest of this page applies to it too — indentation guides, the double-click highlight and our find and replace across every open tab.
What can I record as a macro to repeat?
Our macro recorder covers typing, deletion, paste, navigation, selection, find and replace, Go to Line, saving, encoding and line-ending conversion, bookmarks and tab renames — so the repetitive half of a payload clean-up is recorded once and replayed over the next export. Anything outside that list tells you so at the moment you try, with a beep and a short message, so a recording plays back exactly as you made it.
How do I start a new JSON file from scratch?
Use File ▸ New from Template, or the Templates pull-down in the toolbar, and pick data.json from the Languages group. Our template library gives you a valid skeleton to type into.