Convert one part of a document

{
  "store": {
    "owner": { "name": "Ada", "since": 2019 },
    "books": [
      { "title": "Dune", "price": 12 },
      { "title": "Emma", "price": 8 }
    ]
  }
}

$.store.owner
name: Ada
since: 2019

Path $.store.owner: this node only.

$.store.books[[email protected] < 10]
- title: Emma
  price: 8

Path $.store.books[[email protected] < 10]: 1 match, as an array.

$.store.films
Path $.store.films matches nothing.

Path is a field in the Options column of Convert, with Whole document as its placeholder. Type a JSONPath into it and the writer sees only what the path selects; clear it and the whole document is converted again. The example runs three paths over the same small shop in turn, and each one shows a different outcome — one value, a list of matches, and a refusal.

The syntax is the one the editor’s Find bar uses when its JSONPath switch is on, so anything you have learned there works here, and the other way round. This page does not repeat it: Query JSON with JSONPath covers the selectors and the filters, and its cheat sheet has a row for each. What is covered here is what Convert does with the answer.

One value, or an array of matches

A path can select one place in a document or many, and Convert has to decide what to write in each case. It follows the rule in the JSONPath standard, RFC 9535, which calls a path singular when it is made only of names and indexes — $.store.owner, $.items[0] — and so can never point at more than one place.

A singular path gives you the value it points at, as it is. That is the first run above: the owner object, written as YAML with no wrapper. Every other path — one with a filter, a wildcard or .. — gives you an array of the values it matched, in document order, even when it happened to match only one. That is the second run: one book is cheap enough, and it still arrives as a list with one entry.

The reason is predictability. If the second run gave a bare object when one book matched and a list when two did, whatever reads the output would have to handle both shapes and would break the first time the data changed. By looking at the path rather than at how many matches it found, the shape of the result is settled before the document is read.

The line the result starts with

Each run above ends with a note, and on the page that note is the first line of the result’s footer. This node only means the path was singular and the value was taken as it is. 1 match, as an array — or however many matched — means the path could have matched several and the results were collected. When a writer has notes of its own, the Path’s note comes first, so the explanation of the shape is always the first thing you read.

When a path is refused

A path that matches nothing is refused rather than converted to an empty document, because an empty result would look like a bug in your data instead of a typo in the path. The third run shows the sentence the result gives. A path that is not valid JSONPath is refused the same way, with the parser’s reason, such as Expected a property name and the character where it gave up.

Either way the source is fine, so nothing points at a line in it. Instead the Path field is marked as invalid where it is, and its tooltip holds the reason, which lets you keep typing without losing your place. The result comes back as soon as the path matches again.

The file name and the table follow the node

A path changes what a table is called. When the target is CSV, TSV, a Markdown table or SQL, the name of the node you chose is added to the document’s: $.store.books in shop.json downloads as shop-books.csv, and SQL’s inferred table becomes books rather than shop. A table is always a table of something, and the node is that something. YAML and XML keep the document’s own name, since what they write is still a document.

A path on a chain

store: corner
books:
  - title: Dune
    price: 12
  - title: Emma
    price: 8

JSON
{
  "store": "corner",
  "books": [
    {
      "title": "Dune",
      "price": 12
    },
    {
      "title": "Emma",
      "price": 8
    }
  ]
}

CSV
title,price
Dune,12
Emma,8

Path $.books: this node only.

When neither side is JSON, the page reads the source into a JSON step first and writes the target from it. The path is applied between the two, so it narrows only what the writer sees. The JSON tab keeps the whole document, as the example shows, which means you can look at it to work out what the path should be without clearing the one you have. Convert between two formats that are not JSON says more about the step.

The CSV above is shown with plain line breaks and no byte-order mark. The file a download writes starts with one and ends its lines with CRLF, which is what Excel needs to read the accents in a name correctly. Neither is visible in the result pane either.

What is kept, and what clears it

The path is kept for the tab, with the source, and comes back after a reload. It is not part of the page’s address, so a link you send someone opens on the whole document. Pressing ⇄ clears it, because after a swap the old result is the new source and the path was written for the other document. Changing From or To leaves it as it is.

Open Convert to try your own paths, or Open the editor to test them against the document in the Find bar first, where each match is highlighted.