Tips for your First JSON Document

by Susan Lee

I love technology, and I’m lucky that "work" lets me play with so many "toys". Most of my background is server side and integration, so several years ago, when a friend asked me for help with a project involving the relatively new JSON, I happily agreed to help.

Our project was pretty basic, and the JSON was not very complex, about 10 lines. It was a simple demonstration of JSON and JavaScript, and it was a successful experiment and fun to do. Afterwards my friend kept tinkering until he got it incorporated into his website.

Now that MarkLogic 8 supports JSON, I thought it was time to brush up on my JSON and try my hand with something more substantial. I set out to create a JSON document that loosely models a small portion of LinkedIn’s features. Seems straight forward, right? It’s only key/value, after all.

As I often do with small coding projects, I thought I could get this done with my favorite text editor. JSON is not hard to write, but it can get confusing when you start nesting objects in arrays. Being new to JSON syntax and faithfully using indentation best practices with an editor that does closed-bracket matching, I found myself tangled in nested chaos because I was still learning the syntax.

I found a few helpful resources along the way and wanted to share them. It’s good to have a basic understanding of JSON syntax, which you can get from the official website, www.json.org. Some good tutorial information can be found at http://www.tutorialspoint.com/json/json_overview.htm. A very popular validation site http://jsonlint.com.

My favorite find was a JSON Editor with side-by-side view https://www.jsoneditoronline.orgAs you type, it will tell you when you have a syntax error – there will be a red ‘X’ in the line numbers, and that tells you to fix this fast before you get yourself in deeper mess.

This is the final version of my example JSON document.

It’s easy to think that because JSON is "just" key/value pairs you don’t need to do advanced planning. My professors drilled into us Best Practices, when my programming assignments in college got dinged a whole grade for taking "short cuts". I’ve realized over the years that this due diligence up front saved me a lot of time on projects, because taking the time to make your code readable and not cramming the most functionality into a single line – especially when learning new languages or syntax – is a life saver. Once you become more proficient, then it can be a matter of better performance to optimize your code.

A few things I’ve learned:

  1. Have a rough draft written that just has the key/value combinations, and use proper indentation. This is what the right side of the editor I mentioned above gives you, but you have to know what your structure looks like before starting.
  2. Substitute a label for any values that are long, descriptive text. You don’t want to be distracted by wrapping lines when trying to get your basic syntax and formatting figured out. (Lines 14, 21, and 22, above).
  3. Write the first and last pairs in each object and array, so you can easily see the bracket/brace matching, and have guides where the rest of your pairs will fit into the final document. You will likely have more pairs in your arrays and objects than I used in my example, you’re looking for readability. Once you get the framework figured out, it is easy to add the rest of your pairs in that framework.
  4. If you have a very long list of arrays and objects, you might stop after laying out 3 of them. Once you are done, you can easily see what the structure looks like and copy repeating portions into your document like a template. It’s the initial structure that got confusing for me as a first timer.
  5. Most examples I saw put the ‘[’ for arrays and ‘{’ for object on separate lines. Doing so reflects that arrays typically hold multiple items, though it will make the text longer (and less likely to fit on one screen) than putting them on the same line. If your data has just one item in the array, you can consolidate them onto one line, like this: "recommendations": [{

This is what the outline would look like:

In this format, the structure is much easier to see. Then it is easy enough to fill in the full details without getting tangled in syntax errors.

Larger projects will have many JSON documents that need to be designed. Having the syntax, editor and a game plan will make this easier to design the documents you wish to use. I hope you have as much fun as I did using JSON!

Have a GREAT day!

Comments