Convert

From, To and the JSON in the middle

name: orders-api
replicas: 3
regions:
  - eu-west-1
  - us-east-1

{
  "name": "orders-api",
  "replicas": 3,
  "regions": [
    "eu-west-1",
    "us-east-1"
  ]
}

Five formats can be read — JSON, YAML, XML, CSV and TSV — and seven written, those five plus a Markdown table and SQL. Any of the first can go to any of the second that is not itself, which makes thirty pairs, and nine of the common ones have an address of their own, such as YAML to JSON. The rest are reached by picking From and To on any of them.

Nothing needs to be pressed: the result follows the source after a short pause in your typing. A document over a megabyte shows Converting… while it works, and the ⇄ button between the menus turns the pair round, taking the result as the new source. The name above each pane is the file name a download will use.

YAML

{
  "feature": "dark-mode",
  "enabled": "no",
  "mode": "on",
  "permissions": "0755",
  "accountId": 12345678901234567890
}

feature: dark-mode
enabled: "no"
mode: "on"
permissions: "0755"
accountId: 12345678901234567890

YAML has had two versions with different ideas about what a bare word means. Version 1.1, which many tools still read, takes no and on for booleans and a leading zero for an octal number. So when the writer meets a string that an older reader would take for something else, it quotes it, and the text survives the round trip whichever version reads it next.

Reading goes by the newer rules, 1.2, where yes and no stay strings, and Options says so. Anchors and aliases are expanded into copies, and a number too long for JavaScript is carried as written — the account id above keeps all twenty digits. With One YAML document per array element ticked, an array is written as a stream of documents separated by ---. The pair pages go further: JSON to YAML and YAML to JSON.

XML

<orders>
  <order id="A-17">
    <item>Pen</item>
    <item>Ink</item>
  </order>
  <order id="A-18">
    <item>Pad</item>
  </order>
</orders>

As read
{
  "orders": {
    "order": [
      {
        "@id": "A-17",
        "item": [
          "Pen",
          "Ink"
        ]
      },
      {
        "@id": "A-18",
        "item": "Pad"
      }
    ]
  }
}

With item always an array
{
  "orders": {
    "order": [
      {
        "@id": "A-17",
        "item": [
          "Pen",
          "Ink"
        ]
      },
      {
        "@id": "A-18",
        "item": [
          "Pad"
        ]
      }
    ]
  }
}

XML has no way to say “this is a list”, so the reader decides from what it sees: an element that appears twice under the same parent becomes an array, and one that appears once becomes a single value. That is why the first order’s items are an array and the second order’s lone item is not, and why code that loops over item breaks on the second order.

Always make arrays for takes a comma-separated list of element names that should be arrays every time, however many there are. Attributes arrive as keys starting with @. Text stays text unless Detect numbers and booleans is on. Neither reading option is remembered between visits, because the right answer depends on the document. Going the other way, Root element names the wrapper the writer adds when the JSON has no single element to stand at the top. More on XML to JSON.

CSV and TSV

id;name;city
1;Ada;London
2;Grace;New York

[
  {
    "id": 1,
    "name": "Ada",
    "city": "London"
  },
  {
    "id": 2,
    "name": "Grace",
    "city": "New York"
  }
]

semicolon-separated
header row
2 rows × 3 columns

The reader looks at the first lines to work out the delimiter and whether the first row is a header, and then tells you what it decided. The three lines under the result — the delimiter, the header and the size of the table — are those notes. When a guess is wrong, Delimiter in Options overrides it, and its Auto entry names what was detected. Numbers are read as numbers, so an id column arrives as 1, not "1".

TSV is its own entry in From and To rather than a delimiter setting, because a file with tabs is usually called that. Writing CSV or TSV from JSON builds the table the editor’s Table view would open on, with Header row and Row labels (key or #) as switches. See CSV to JSON and JSON to CSV.

A Markdown table

[
  { "command": "ls | wc -l", "does": "counts the files" },
  { "command": "pwd", "does": "prints where you are" }
]

| command     | does                 |
| ----------- | -------------------- |
| ls \| wc -l | counts the files     |
| pwd         | prints where you are |

A Markdown table is the quickest way to put a small set of records into a README, a pull request or an issue, where it renders as a grid. The columns are padded so the source lines up too, and a pipe inside a value is escaped with a backslash, as in the first command, so it cannot end a cell early.

A header row is always written, because GitHub’s tables need one; its switch is shown ticked and cannot be cleared. Row labels (key or #) adds a first column with each row’s index or key, which is on by default and remembered, so the example turns it off. A Markdown table cannot be read back into JSON, so on this pair ⇄ is disabled. See JSON to a Markdown table.

SQL

[
  { "id": 1, "email": "[email protected]", "plan": "pro", "tags": ["beta"] },
  { "id": 2, "email": "[email protected]", "plan": null, "tags": [] }
]

CREATE TABLE "users" (
  "id" INTEGER NOT NULL,
  "email" TEXT NOT NULL,
  "plan" TEXT,
  "tags" JSONB NOT NULL
);

INSERT INTO "users" ("id", "email", "plan", "tags") VALUES
  (1, '[email protected]', 'pro', '["beta"]'),
  (2, '[email protected]', NULL, '[]');

Every row of the array becomes an INSERT, and the columns of the CREATE TABLE come from looking at every row, not the first one: a column is NOT NULL only when no row is missing it and none holds null, which is why plan is nullable here. A nested array or object goes into one JSON column — JSONB on PostgreSQL — rather than being spread into a second table.

The table is named after the document, users for users.json, and Table name shows that as a placeholder you can type over. Dialect and Statements are remembered between visits; the table name never is. Long arrays are split into INSERTs of five hundred rows each. JSON to SQL has the dialects side by side.

Convert between two formats that are not JSON

Pick YAML and XML, or CSV and SQL, and neither side is JSON. The page still converts: it reads the source into JSON, then writes the target from that JSON, and it shows the middle document instead of hiding it. A tab above the result holds it, so a chain that goes wrong can be followed one step at a time. Convert between two formats that are not JSON works through two of them, one that succeeds and one that is refused half-way.

Paste, open, drop or fetch a source

There are four ways in, and they all land in the same place. Paste into the pane, or press Paste above it; drop a file on it; open Open and choose Open file…; or choose From URL… in the same menu to fetch a document from an address that allows it. A fetched document keeps the name at the end of its address.

Whichever way it arrives, the page reads the text and moves From to match what it finds, so a CSV dropped on a JSON pair becomes a CSV pair. To does not move unless it would equal From. The status bar under the cards says what was detected. Clear empties the source and the result together.

A source that will not parse

{
  "name": "orders-api",
  "replicas": 3,
}

line 3, column 16: Trailing comma before "}"

When the source does not parse, the result pane says Fix the source to see the result. and the status bar under the cards names the line and the column of the first problem, which is where the caret should go. The message is the parser’s, so it says what it expected rather than only that something is wrong.

When From is JSON, Repair, first in the source’s second row of buttons, turns amber. It is the editor’s repair, the same fixes in the same words, and one undo takes it back. It never appears for YAML, XML or CSV: those have their own grammars, and a JSON repair would only make them worse. What Repair can and cannot fix is set out in Repair broken JSON.

Convert one part of a document

A large API response is rarely what you want as a spreadsheet; one array inside it is. Path in Options takes a JSONPath and converts only what it selects. The rule that surprises people is that a filter always gives an array, even when one item matched, while a plain path to one place gives that value alone. Convert one part of a document shows both, and what a Path does to the file name.

Minify the JSON

name: orders-api
replicas: 3
regions:
  - eu-west-1
  - us-east-1

{"name":"orders-api","replicas":3,"regions":["eu-west-1","us-east-1"]}

When the target is JSON, Options has a Write JSON heading with one switch under it. Ticked, the result is written with no spaces or line breaks at all, which is what a request body, an environment variable or a one-line log entry wants.

Unticked, the JSON is indented by the amount chosen in Settings ⚙, the same setting the editor’s Format uses. Minify is applied last, after any Path, and the choice is remembered, so the next conversion to JSON will be minified too until you untick it. It has no effect on any other target: YAML and XML are always written indented, and a table is a table.

Between Convert and the editor

The editor and Convert share one handover in each direction. From the editor, Convert in the header takes the document you were working on across as the source. From here, Open JSON in Editor takes whichever side of the pair is JSON: the source when From is JSON, the result when To is, and the middle step when neither is.

The two sides behave differently on arrival, and that is deliberate. The editor asks before replacing a document, because it is where your work lives. Convert replaces its source without asking, because what was there was a conversion you can make again. Only the tab you are in is affected; a second tab keeps its own.

The keys

Three keys cover the page. ⌘O opens a file into the source. ⌘S downloads the result. ⌘⇧Enter copies it to the clipboard. On Windows and Linux they are Ctrl+O, Ctrl+S and Ctrl+Shift+Enter. All three work with the caret in either pane.

With nothing converted yet, the page says so in the status bar instead of downloading an empty file. When a chain shows its JSON tab, download and copy take the tab in front, so you can save the middle step without switching pairs. The ⌨ button in the header lists these with every other key on the site.