In writing about Workflow (then) and Shortcuts (now) for a living, at some point I realized that if I wanted to build more complex shortcuts to either deal with web APIs or store data in iCloud Drive, I had to learn the basics of parsing and writing valid JSON. The format is behind most of the web API-based Shortcuts I have shared here on MacStories1 and is one of the techniques I recently explained on Club MacStories when I built a shortcut to save highlights from Safari Reading List. The beauty of JSON is that, unlike XML, it’s cleaner and more readable – provided you have a dedicated viewer that supports syntax highlighting and/or options to navigate between objects and inspect values. There’s no shortage of such utilities on macOS, but this is the kind of niche that still hasn’t been fully explored on iOS by developers of pro apps. That changes today with the launch of Jayson, created by Simon Støvring.
Readers of MacStories may be familiar with Støvring’s name – he’s the developer behind one of the most powerful and innovative pro apps of 2018, the excellent Scriptable for iOS. For this reason, it shouldn’t come as a surprise that Jayson, a project that was born out of Støvring’s personal frustration with the lack of a modern JSON viewer for iOS, has that same spark of innovation and integration with native iOS functionalities that set Scriptable apart last year. If you do any kind of work with JSON on your iPhone or iPad, you need Jayson in your life, and here’s why.
Document Browser and Saving Files
From the outset, one of the best decisions Støvring made with Jayson was adopting the native Files document browser instead of a proprietary file picker.
When you open Jayson, you’re presented with a classic Files view that lists your recent documents and tagged items under the ‘Jayson Recents’ section; however, the app will filter iCloud Drive to only show you .json files that can be opened and previewed. If you want to navigate to specific folders across multiple locations (including third-party file providers), you can do so from the ‘Browse’ tab. As we’ve frequently noted both on MacStories and AppStories, the advantage of the document browser is that it retains all of Files’ essential features such as search, tagging, and drag and drop.
As someone who works on advanced shortcuts that often save data into JSON files stored in iCloud Drive, I welcome the ability to open those items in Jayson using the same iCloud UI I see in Files. Thankfully, though, this is not the only way to get JSON files into the app. Jayson comes with an action extension and rich notifications that, among other things, can open JSON content directly in the app or copy it into the app as a file. In Jayson’s settings, you can choose how imported files should behave: you can save them into Jayson’s own iCloud Drive folder (this is what I do), save them locally in the ‘On My iPad’ storage space, or not save them at all and always open them with the ‘Don’t Copy’ option.
I’m a big proponent of apps adopting Files’ document browser on iOS and sharing the same working set of documents; I think apps like Jayson, iThoughts, and PDF Viewer are examples other developers should follow.
Tabs and Splits
Of course, what makes Jayson special isn’t its approach to file management but how it lets you preview and navigate the contents of JSON files. The short answer is: there’s a lot of flexibility, and it’s clear that this is an app created by someone who needed to scratch his own peculiar JSON itch.
The contents of JSON files (objects, arrays, and strings in key:value pairs) can be browsed with a list-based interface that progresses through the JSON’s structure and displays your path with a breadcrumb trail in a toolbar at the top. Think of it as a Finder, but for the contents of the current JSON file only. You can tap on “locations” in the breadcrumb navigation to instantly move back to them and you can see, for instance, how many keys are contained inside an object. Everything is very visual and intuitive; Jayson is, by far, the prettiest and easiest way to parse JSON I ever tested on iOS, but there’s more.
At any point, you can share the file or the current value alone, and, this being a modern iOS app, you can tap URLs, copy text, or drag and drop content out of Jayson. You can also tap & hold items to show buttons to copy a key or value to the clipboard, and – more importantly – you can hit a ‘TXT’ button to instantly switch the presentation in the current view to raw JSON plain text with syntax highlighting. You can even swipe across items to open them with a new split or tab, which brings me to the next major feature of the app.
Tabs are pretty self-explanatory: multiple views from the same JSON file can be opened in separate Safari-like tabs, and you can navigate to a different point of the JSON’s structure in one tab to compare it to another. Tabs can be rearranged with drag and drop; when opening a file you previously explored with Jayson, you can choose to restore the tabs you had open before or create a new tab. Tabs are great if you need to compare different parts of your JSON but don’t need to do so very often.
I prefer splits. A split lets you, well, split the current view in two. Each split then becomes its own view, which can navigate to different points of the JSON or be presented as raw text instead of tables. Splits can be rearranged with drag and drop and, at least on the 12.9” iPad Pro, you can create up to three separate splits per tab to open multiple views simultaneously (you can create up to two splits on iPhone).
Splits are, in my opinion, the absolute best way to understand or debug JSON because of the multiple perspectives they provide. Perhaps you want to have a split of two views – one as a standard table, the other as highlighted source code; or maybe you have an array and you want to keep one split at the root level and the other going deep into nested objects and strings. All of this can be done with splits in Jayson.
I have used splits extensively when creating advanced shortcuts for Club MacStories2, and I can genuinely say they have saved me minutes I would have spent searching or scrolling up and down to look at highlighted JSON in Kodex. Støvring’s split UI immediately made more sense to me than Kaleidoscope’s, and I wish he would apply his talents to building a Jayson-like tool for text diffs instead of JSON files. The combination of tabs and view-independent splits makes for a fantastic in-app multitasking experience, and I’d like more apps to consider this approach for browsing different parts of deep file structures or long documents.
Shortcuts and Rich Notifications
But the best feature of Jayson – and one that confirms Støvring’s status as one of the few indie developers pushing the envelope on iOS – isn’t something that you can use in the app itself. Jayson’s best feature is a rich notification that lets you navigate JSON files without opening the Jayson app at all. It is the most impressive implementation of rich notifications I’ve ever seen on iOS, and it has fundamentally changed how I create shortcuts that parse JSON from web APIs.
Here’s how it works: Jayson can donate a shortcut to iOS 12 that can display JSON content (fetched from the system clipboard) in a rich notification. Thanks to improvements in iOS 12, upon expanding the rich notification you’ll be presented with the same Jayson interface you see in the main app, in which you can freely navigate the JSON structure and select text. It is, effectively, like having an app inside of a notification, and not just a preview of a particular screen of an app (like the notifications from Twitter or CARROT Weather), but an actual, fully-interactive portion of an app that supports multiple layers of navigation and even text selection. In years I’ve spent covering iOS apps and testing various takes on rich notifications, I’ve never seen anything like this.
Because the notification is triggered by a shortcut, it can become part of a longer process that generates the necessary JSON code, copies it to the clipboard, then fires off the Jayson shortcut. I’m referring, obviously, to running a custom shortcut in the Shortcuts app. Now, whenever I’m working on a shortcut that involves JSON returned by an API or my own local JSON files, I can copy the JSON text to the clipboard then drag in the ‘View JSON in Notification’ app shortcut donated by Jayson and place it after the ‘Copy to Clipboard’ step.
When the shortcut runs and the Jayson step is triggered, I can drag down the local notification sent by Jayson and inspect the JSON that was just copied to the clipboard in a visual environment. I cannot split the notification in two parts, but everything else is supported with the same UI of the main app; I can also choose to copy the JSON as a file into Jayson or just open it in the app without saving a file.
With the ability to preview JSON on the fly without leaving Shortcuts to open a separate text editor (or, worse, previewing JSON in Shortcuts’ own alerts), I’m saving a lot of time because I’m faster at understanding how JSON responses are structured. Going forward, unless Shortcuts adds native debug steps for JSON and other API responses, I see no other way to preview JSON but Jayson’s donated shortcuts.
The shortcut that turns the clipboard into a JSON inspector within a notification isn’t the only shortcut offered by Jayson though. By default, in the Shortcuts app you’ll also find Jayson shortcuts to view JSON in the app with and without the option of saving it as a file. I like the one that takes the clipboard and opens it in Jayson without creating a new file.
Jayson also takes a page from PCalc and CARROT Weather and provides a settings page to configure your own Siri shortcuts with custom parameters. In the ‘Siri Shortcuts’ screen inside the app’s settings, you can create multiple shortcuts that either act on JSON stored in the clipboard or download JSON from a link in the clipboard. You can choose to view the resulting JSON in an interactive notification or send it directly to the app, and you can also select whether the app should create a new file for the JSON content or not.
Shortcuts you create in settings can always be added to Siri as voice shortcuts, but they will show up in the Shortcuts app as donations too. I’m not sure about the practical utility of voice activation for debugging JSON, but I do appreciate the versatility granted by configurable actions I can add to my advanced shortcuts.
Wrap-Up
Jayson is a programming utility with a niche appeal. If you regularly work with web APIs on iOS and have been looking for ways to inspect and debug JSON in a visual environment, Jayson is the new best-in-class option and you should go download it right now. The app is free with a $1.99 In-App Purchase to unlock themes, custom icons, accent colors, and the ability to open more than two tabs at once. Jayson is a must-have for any web programmer who wants to work from an iPhone or iPad.
It’s also important to note how some of the modern iOS features adopted by Jayson are remarkable technical achievements regardless of the app’s limited audience. Tabs and splits are a fascinating way to allow users to multitask within the same document; the app’s use of rich notifications is the non plus ultra of what can be achieved with this API at the moment. Even if you don’t know what JSON is or don’t need this app in your workflow, Jayson stands as a model for other iOS productivity apps to follow.
Jayson is available as a free download on the App Store.
- Modern web services with a REST API tend to return JSON results. ↩︎
- I’ve been on a time zone kick these past few weeks, building advanced shortcuts for time zone conversions using the TimeZoneDB API. All of these shortcuts are available to Club MacStories members including an in-depth explanation of how they were built and why. ↩︎
