Meet the Functions

There are 6 JSON functions available in FileMaker 16:

• JSONSetElement - Adds or modifies an element in a JSON document at the supplied key, index or path. The new value, and the value's data type, are passed as the 3rd and 4th arguments.

• JSONDeleteElement - Deletes an element at the supplied key, index, or path.

• JSONGetElement - Returns an element at the supplied key, index, or path.

• JSONListKeys - Lists all the keys or array indexes at the supplied key, index, or path.

• JSONListValues - Lists all the values at the supplied key, index, or path.

• JSONFormatElements - Formats a JSON document so it's easier to read (i.e. it separates key-value pairs onto different lines, and adds indentation based on the nesting structure). Very useful when you are troubleshooting JSON.

Keys, Indexes, and Paths (Aka Parsing JSON)

Understanding these three are critical to a happy life with JSON, as they are needed for every function. The real power is in paths, but to understand paths, you must know how to use keys and indexes.

Keys & Indexes

Keys and indexes are pretty much what they say on the tin: supply a JSON function a key and it'll return the element associated with the key. And supply a function an array index, and it'll return the element associated with that index.

Let's check out a couple examples. Assuming we start with this contact JSON document in a $json variable

{
     "firstName" : "John",
     "lastName" : "Doe",
     "address" :
     [
         {
              "type" : "Billing",
              "city" : "Indianapolis",
              "state" : "IN"
         },
         {
              "type" : "Shipping",
              "city" : "Cincinnati",
              "state" : "OH"
         }
     ]
}

to get the last name of the contact, we would use the function JSONGetElement( ) with the lastName key

JSONGetElement( $json ; "lastName" )

which gives us

Doe

For array indexes, supply the array's key, and then the index of the array element you want in brackets. In our example JSON, to get the contact's shipping address, we would use JSONGetElement with the address key and an index of 1 (indexes start at 0, a deviation from most of FileMaker, but consistent with the JSON standard):

JSONGetElement( $json ; "address[1]" )

which results in

{
    "type" : "Shipping",
    "city" : "Cincinnati",
    "state" : "OH"
}

Paths

Now that we've gotten introduced to keys and indexes, let's take a look at paths. Paths are an ordered list of keys and indexes separated by dots that tell FileMaker the exact element you want in a JSON document, which is necessary if there are multiple elements in the same document with the same key, or if you want an element inside an array. Paths start at the top of the document and end at the element you want.

Let's say we wanted to get the city of the contact's shipping address. To do that all in one function call, we would need to use the path "address[1].city". Address is the first element from the top of the doc that leads us toward the city we're looking for, the shipping address is in index 1 of the address array, and we want the city element of that address object. In FileMaker speak, the function call is

JSONGetElement( $json ; "address[1].city" )

which gives us

Cincinnati

Creating JSON

You only need one function to create or modify a JSON document: JSONSetElement( ). And now that we have some familiarity with keys, indexes and paths, the JSONSetElement( ) function will make a lot more sense. Let's see it in action.

To create the example contact JSON document using JSONSetElement( ), we'll enlist the use of paths that tell FileMaker at which part of the JSON document to create the new elements, along with the bracket notation to allow us to perform multiple JSONSetElement()s in one call, just like the Substitute( ) function:

JSONSetElement( "{}" ;
    [ "firstName" ; "John" ; JSONString ] ;
    [ "lastName" ; "Doe" ; JSONString ] ;
    [ "address[0].type" ; "Billing" ; JSONString ] ;
    [ "address[0].city" ; "Indianapolis" ; JSONString ] ;
    [ "address[0].state" ; "IN" ; JSONString ] ;
    [ "address[1].type" ; "Shipping" ; JSONString ] ;
    [ "address[1].city" ; "Cincinnati" ; JSONString ] ;
    [ "address[1].state" ; "OH" ; JSONString ]
)

Contrast that to this, the non-bracketed version

JSONSetElement(
    JSONSetElement(
        JSONSetElement(
            JSONSetElement(
                JSONSetElement(
                    JSONSetElement(
                        JSONSetElement(
                            JSONSetElement( "{}" ;
                                "firstName" ; "John" ; JSONString ) ;
                                "lastName" ; "Doe" ; JSONString ) ;
                                "address[0].type" ; "Billing" ; JSONString ) ;
                                "address[0].city" ; "Indianapolis" ; JSONString ) ;
                                "address[0].state" ; "IN" ; JSONString ) ;
                                "address[1].type" ; "Shipping" ; JSONString ) ;
                                "address[1].city" ; "Cincinnati" ; JSONString ) ;
                                "address[1].state" ; "OH" ; JSONString
)

The bracket notation is much easier to read. And faster to write. A win-win.

Some Items to Note about the Functions

• Avoid null JSON documents. Avoid passing null JSON documents to the parsing functions - the functions will return an error. For example
  
  

  JSONGetElement( "" ; "lastName" )

  Gives back error
  

  ? * Line 1, Column 1
    Syntax error: value, object or array expected.
  * Line 1, Column 1
    A valid JSON document must be either an array or an object value.

  Instead, pass an empty object {} or an empty array [].

• Use explicit data types in JSONSetElement( ). While this is personal preference, you should explicitly state the data type in JSONSetElement( ) calls. Not only does this ensure FileMaker doesn't accidentally convert values to wrong data types, but explicit types make code easier to read than blank arguments.

• Use JSONListKeys() to get an array's size. While there's no function to directly get an array's size, you can do this using JSONListKeys() in tandem with ValueCount( ). For example, to get the count of addresses for our example contact JSON, doing this

  ValueCount( JSONListKeys( $json ; "address" ) )

  gives our answer

  2

New Standard for Multiple Script Parameters

The crux of multiple parameter passing in scripts is being able to create key-value pairs, which is JSON's bread and butter. No more need for dictionary or associative list custom functions - all parameter passing can now be done with the JSON functions. We updated our free template, FM Quickstart, to use JSON for parameter passing, instead of our alist custom functions. We hope the rest of the community embraces JSON as a standard for parameters. It'll make working in, reading and understanding other developers' code much easier.

Conclusion

With the advent of JSON functions, FileMaker developers now have the ability to natively create and parse JSON for REST APIs, multiple script parameter passing, and more. Check out our other articles on FileMaker 16 for more information about all the new and exciting capabilities we have at our disposal with this release of FileMaker. Please contact us if you would like help taking advantage of FileMaker's new JSON functions.