Open and save a document

Paste a document in

{
  "service": "orders-api",
  "region": "eu-west-1",
  "replicas": 3,
  "tags": ["eu", "prod"]
}

7 nodes · depth 2

Pasting is the fastest way in and the one most people use. Click into a pane and paste; there is no import dialog and nothing to confirm. What is worth knowing is how to check that the whole thing arrived, because a truncated paste looks exactly like a short document.

The status bar along the bottom answers that. It shows the size of the text, and beside it a node count and a depth — the number of values in the document and how deeply the deepest one is nested. Those two numbers are the quickest check that a paste is complete: a config you know has forty settings in it that reports seven nodes was cut off somewhere.

The count is blank while a pane is in Code, which surprises people until they know why. Counting nodes needs the document taken apart into a tree, and a pane showing text has not necessarily done that work yet. Switch either pane to Tree, Table or Graph and the field fills in.

Open a file

For anything bigger than a paste, open the file directly. The Open menu in a pane’s toolbar has Open file… at the top, and the keyboard reaches it without the menu: ⌘O on a Mac, Ctrl+O on Windows and Linux. The picker offers the extensions the editor recognises rather than every file on your disk.

The document lands in the pane you opened it from and the pane’s name becomes the file’s name. Opening does not ask before it replaces what was there, for the same reason pasting does not: the previous document is one undo away, and a confirmation on every open would be a question you answer a hundred times to be useful once.

Drop a file on the page

Dragging a file onto the page does the same thing as opening one, with one difference worth knowing: the drop target is the pane, not the window. Drop on the left pane and the left pane takes it; drop on the right in Compare and the right takes it while the left stays exactly as it is. That is how you get two files side by side without touching a menu.

One file at a time. A drop of several is not a request the editor can answer sensibly — there are two panes and no obvious pairing — so it takes none of them rather than guessing which two you meant.

Load from a URL

From URL…, in the same Open menu, fetches a document straight from an address. It is the quickest way to look at an API response, a published schema or a config in a repository, and the fetch is made by your browser from this page — so the address has to be one your browser could reach anyway.

That is also where the two refusals come from. A server that does not send cross-origin headers will not let this page read its response, and a plain http:// address cannot be fetched from a page served over HTTPS. Neither is something the editor can work around, and it says which of the two happened rather than reporting a generic failure, so you know whether to try a different address or download the file and open it.

Load a sample

Samples holds a handful of documents chosen to have something to demonstrate: an array of records that makes a good table, a deeply nested one for the tree and the graph, a pair of configs that differ in a few places, and a document with a schema to check it against. They exist so that trying a feature does not require finding a file first.

A sample arrives like any other document — it replaces the pane, the status bar says what it is for, and one undo puts back what was there. The pair loads into both panes at once and switches the mode with it, which is the same move the Try it in the editor links in these guides make.

Name a pane

Click the name above a pane and type; it is a field, not a caption. Three separate things read it afterwards, which is why it is worth setting: the two panes in Compare are labelled with it, a download is called after it, and the code generators use it to name the root type they write.

That last one is the reason to bother. Renaming a pasted document to order.json before generating types gives you an Order interface; leaving it as it arrived gives you something you then rename by hand in your own editor. Ten seconds here saves that.

Save, download and copy

There are three ways out and they differ in where the text goes rather than in what it is. Save writes the pane’s text to your downloads folder, under the pane’s name, and has the keyboard shortcut you would expect: ⌘S on a Mac, Ctrl+S on Windows and Linux. Copy puts the same text on the clipboard.

Neither changes the document. What is written out is exactly what is in the pane, including its indentation — so if you want it formatted or minified, do that first and then save. The Table has an export of its own, which is a different thing: it writes rows and columns rather than the document, and it is covered on the views page.

When it is not JSON

Not everything that arrives is JSON, and the editor does not pretend otherwise. A YAML file, an XML response or a CSV export lands as text, and the chip beside the pane’s name says which format the text was recognised as. Nothing is converted behind your back and nothing is rejected: the text is there, and it is simply not valid JSON yet.

The chip is a link to Convert, which is the whole story. The editor itself never converts anything — that decision keeps the two jobs apart, so a document in a pane is always the document you put there. One trip across to Convert turns your YAML into JSON, and you come back with it; the Convert guide says what each format does on the way.