The term "JSON" stands for JavaScript Object Notation. Strictly speaking, it is a standardized specification for a syntax that can be used to communicate information, especially between a Web server and a Web client. Typically, such a client is a Web browser on someone's computer, where some JavaScript code can use that JSON data to determine what information will be visible to the user of the computer and how it will look. In the present instance, however, JSON is the vehicle chosen for exporting the contents of the present offline database that supports this Website (see our maintenance page) to a modern online database system. That process requires, among other things, the acquisition of a tool that is "JSON-aware" in order to verify that the exported information actually complies with the JSON standard. This article resulted from the Webmaster's experiences in finding, acquiring and using an editor that can perform such a task. (The project itself is far from complete, as of this writing.)
Since the Webmaster's computers are all Macintosh systems of various ages, the only feasible source for a JSON editor was the Apple Store. While there were many hits in a search for "JSON editor," many were obviously only peripherally related to the planned task, while others were perhaps inadequately described by their creators. In spite of mixed reviews, what was eventually chosen was a low-priced program named Power JSON Editor, from a source called TickPlant. Although that source has a Website, it is not up to date (the latest copyright year is 2022), and nothing can be discovered about its owner. (The acquired version of this product is 2.17.1, but the Website only mentions version 2.17.0, and it has no mention of changes from previous versions.) Still, that editor is doing what is needed here, so the following review is intended to share this Webmaster's experiences with other potential or actual users of this product.
This app does not have true Help — only a link to a publicity page on the developer's Website. There one finds teasers about what the Editor can do, but no explanations of how to do them, nor any description of why one might want to do them, nor any mention of possible operational limits. So the only way to learn how to use this program is by trial and error (many errors!).
Like most editors, this one can work on an existing file (of JSON text) or create a new one. This review does not cover all of the features of the software — only those that were found to be directly useful in the work with JSON on the project mentioned above. That work involved validating JSON files that were created elsewhere; this reviewer did not attempt to create new JSON files via this editor.
Visually, the design of this product is clean, straightforward and effective, once its functionality is understood.
- -
Lessons learned:
PART I - What should have been in a Help file
1. When the app is opened, it displays a window with a toolbar plus three panes.
The left pane displays the content of a JSON file (or what will become one) as editable text; the upper right pane displays a table of the JSON elements of that file via columns for Key, Type and Value; the lower right pane is an editor for the key and value of the node selected in the upper right pane.
Escaped CR in JSON text remains escaped in the node table but is effective in the value field of the node editor pane.
All panes can be resized by dragging a separator bar or line; likewise the column widths in the upper right panel can be adjusted by dragging the separators in the column headings bar.
Initial contents of the three panes are minimal when the app is opened without specifying a file, unless a file was open when the app was last quitted.
When an existing JSON file is opened, if it is error-free then all three panes are populated; otherwise, an error banner appears at the bottom of the left pane, and the right two panes are not populated until all errors in the JSON text are corrected.
Only the first detected error is visible, and it must be resolved before any subsequent error can be detected and displayed.
When a JSON component is selected in the table (upper right pane), its text is shadowed in the text (left pane) and its key and value become editable in the node editor (lower right pane).
2. The Apple menubar contains the following dropdown menus:
File - typical file options.
Included is an Open Playground option, but there is no clue to what that means, and this reviewer has not explored it.
Edit - typical menu of text editing options, for the JSON text editor (left pane)
JSON - options Beautify and Compact (see below)
Node - long list of possible operations, apparently related to the node table. When a node is selected in the node table, menu options for Copy Node Path and Copy Access Path are activated, with the latter having choices for JavaScript, Objective-C, Python and Ruby.
This reviewer's untested impression is that what's copied to the clipboard may not be accurate for referencing the selected node of the JSON document.
View - toggles visibility of the JSON Text Editor, the Node Editor, and the Toolbar; enables customization of the Toolbar
Plug-ins - (9 listed, none explained or experimented with)
Window - typical options, apparently useful only if multiple files are open
Help - not helpful (see above)
3. The toolbar of an open window contains several icons with names. Their functions duplicate the menubar functions identified above, which are described in more detail in the following paragraphs.
4. The Beautify and Compact buttons at the left end of the toolbar offer mirrored operations, which can also be invoked from the JSON menu.
"Beautify" inserts whitespace to transform the JSON text so that there is no more than one key identifier (plus its following colon) and/or value per visible line, with indentation to make the logical structure visible.
Arrays and objects are displayed with the opening bracket or brace following the colon on the key identifier line and the closing bracket or brace on a line by itself after the last value.
There is no option to use a different style of presentation.
"Compact" removes all whitespace to transform the JSON text into a single physical line or record, although is is soft-wrapped to be fully visible within the pane.
(Vertical scrolling might be necessary, but horizontal scrolling is not.)
5. In the middle of the toolbar are eight buttons. The first six represent standard JSON components (object, array, etc.) and will insert one such component at the currently selected position in the upper right pane, after which the selection indicator moves down one line. The last two, both labelled "Wrap" but visually distinguishable, will wrap the selected component(s) in the upper right pane with a new object or an array.
6. At the right end of the toolbar are two gray buttons (labelled JSON and Node) plus a search bar. The JSON button toggles the visibility of the left pane (which displays the raw JSON material in the file) while the Node button toggles the visibility of the lower right pane (the node editor). I have not explored the use of the search bar.
7. In the upper right pane, objects and arrays have disclosure triangles, allowing the contents of those elements to be displayed or hidden at will.
8. When a valid JSON file is being displayed, deleting an object via the object editor (upper right pane) will cause the text editor display (left pane) to change as if the Beautify command (button or menu option) had been selected. Undoing that deletion (via Edit > Undo or Command-Z) will return the text display to its previous appearance.
Part II - Problems encountered and (sometimes) solved.
Once all of the above characteristics have been discovered, the editor does become easier to use. However, there are a few bugs and design flaws.
1. BUG: The program becomes unresponsive (spinning pizza wheel of death) in some circumstances if the user has made the right panes too narrow. So don't do that! Instead, turn them off. (To recover, force quit the program, restart, and immediately turn off the JSON Text Editor [left pane]. Resize the window, then reopen the JSON Text Editor.)
2. DESIGN FLAW: Although detection of JSON text errors is fast, dynamic and automatic, and an error message banner gives a clear presentation of the nature of an error (which may be "lexical" or "parse" or ???) finding the error es not as easy as it ought to be. That banner includes a "Locate Error" button, which not very useful — it makes the JSON text editor insertion point bar disappear, it does not identify the text display line number on which the error occurs (nor highlight that line), and depending on the nature and position of the error, it might or might not dimly highlight a single character somewhere in the JSON text. However, if the error location is not currently visible in the text edit pane, then the file will scroll vertically so that the error is approximately in the middle of the pane, if possible. Fortunately, text coloration may in some circumstances give a hint as to where to look. Also, Shift-Arrow (up or down) will usually highlight an area around the error; comparing that highlighted text with the text fragment in the error banner should make it evident where the program has detected an error. (Correction of the error may require making a change somewhere else, of course, because syntactically correct JSON may nevertheless be an inaccurate reflection of the logical relationships that the user intended.)
3. BUG: In some cases, this editor refuses to open a file, with no explanation of the cause. Serendipitously, this author's prior experience with various text encodings led to discovery of a possible solution. Unlike HTML, the syntax of JSON does not provide any way to specify the encoding of the file containing it. The Power JSON Editor apparently assumes that all JSON files will be encoded as UTF-8, but the default on Macintosh computers is Western (Mac OS Roman). If the JSON text of a file in that default encoding includes extended ASCII characters (such as é or É), then it is incompatible with UTF-8 encoding. In a text editor that can handle different encodings (e.g., BBEdit), this situation is readily detectable in an HTML file that has "charset=utf-8" specified internally but is actually in Mac OS Roman. BBEdit will warn of such a discrepancy, and will display an errant character as a solid black diamond with a white question mark. The Power JSON Editor apparently isn't that smart; instead, it just refuses to work (with no explanation). The workaround for this problem is to open the file in BBEdit, change the encoding from Mac OS Roman to UTF-8, and save it. Then the Power JSON Editor will open and colorize it correctly (provided that there are no errors).
4. BUG: In some cases, this editor will open a file but not color it according to detected syntax. Since it does open some files with syntax coloration (in spite of the presence of parsing errors), it is evident that this is the intended mode of operation. This lack of coloration has been observed to happen both in files with JSON syntax errors and in files which are syntactically correct. The difference, of course, is that in the first instance there will be an error banner and the right panes will remain unpopulated.
5. DESIGN FLAW?: One instance of where the error banner can be misleading is the case of an unescaped quote mark within a text string. The editor might point to the next subsequent space rather than to the quote mark itself. Or it might point to the second character after the quote mark while highlighting the first character after the quote mark. Fortunately, it's usually easy to see what's wrong.
- -
SUMMARY: This editor is doing what is needed for the project for which it was acquired. That would be worth a rating of at least four stars if the unguided learning curve were not so steep.
This page was created on 2024/11/16 and last revised on 2024/11/18.
Please send comments or questions about this page to
the
Webmaster/owner.
Use similar links on other pages to send specific comments or questions
about those pages.