Convert between two formats that are not JSON

service: orders-api
ports:
  - 8080
  - 8443

JSON
{
  "service": "orders-api",
  "ports": [
    8080,
    8443
  ]
}

XML
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <service>orders-api</service>
  <ports>8080</ports>
  <ports>8443</ports>
</root>

Wrapped the JSON value in a root element.

Of the thirty pairs on Convert, twenty have JSON on neither side: YAML to XML, CSV to YAML, TSV to SQL and the rest. There is no separate converter for each of them. Instead the page reads your source into JSON with the reader it uses for that format, and then writes the target from that JSON with the writer it uses for that one — the same two halves that the pairs with JSON on one side use on their own.

That has a useful consequence. A chain can never behave differently from doing the two halves yourself: YAML to XML gives exactly what YAML to JSON followed by JSON to XML would, byte for byte, notices included. So anything this guide says about one format holds in a chain as well.

Seeing the step

When a pair is a chain, the row of controls shows it: between the ⇄ button and the To menu there is a small → JSON →, and the result gains two tabs above it, JSON and the name of the target. The target is in front, since that is what you asked for. The JSON tab holds the middle document, and it is a full result in its own right — its own file name, its own size, and its own Copy and Download.

The example above prints the two tabs one after the other. The first is what the YAML reader made of the source; the second is what the XML writer made of that. Reading them in that order is the fastest way to tell which half is responsible for something you did not expect. In this case the ports list became two ports elements, which is XML’s way of writing a list, and the writer needed a wrapper because the JSON had two top-level keys — the note under the result says so.

Open JSON in Editor takes the step, not the source and not the target, because the step is the only JSON the pair has. That is handy when a YAML file needs searching or comparing before it goes on to become XML.

When the second half refuses

orders: []

JSON
{
  "orders": []
}

SQL
Nothing to put in a table: this JSON has no rows — in the JSON step; see the JSON tab.

Here the YAML holds a list of orders with nothing in it. The reader is perfectly happy with that — an empty list is a valid value — so the JSON step succeeds. The SQL writer is not: it looks for rows, finds an empty array, and has nothing to insert and no values to decide the column types from. The message is the writer’s, and the page adds where it happened: in the JSON step; see the JSON tab.

That pointer matters. A refusal from the reader is about your source, and the page says so by naming a line and a column in the status bar. A refusal from the writer is about the JSON in the middle, which you did not type and may never have looked at, so there is no line in the source to point to. The JSON tab is where the answer is; here it shows the empty orders list, and the fix is in the data, not in the YAML’s syntax.

Swapping a chain round

⇄ works on a chain the way it does on any pair: YAML to XML becomes XML to YAML, and the XML that was the result becomes the new source. It is disabled when the target cannot be read back. A Markdown table and SQL are both formats the page writes but never reads, so YAML to SQL or CSV to a Markdown table only go one way, and the button’s tooltip says why.

Options on a chain

A chain shows both halves’ options at once, under two headings: one starting Read for the source and one starting Write for the target. CSV to SQL has Read CSV, with its delimiter and header choices, above Write SQL, with the dialect and the statements. Each heading holds exactly the options that half would have on a pair of its own.

A Path goes under the Write heading, because it is applied between the halves, and it narrows what the writer sees while the JSON tab keeps the whole document. That makes the tab a convenient place to find the path you want.

The notes under a chain’s result

Both halves can add notes, and a chain lists them all: the reader’s first, then the writer’s. A CSV to SQL that works says which delimiter the reader found and how many rows it read, and then whatever the writer had to decide on its own. When something looks wrong in the target, the reader’s notes are the first place to look, because a wrong delimiter guess shows up there long before it shows up as a strange column in the SQL.

Open Convert and pick two formats that are not JSON, or Open the editor to look at the JSON step on its own.