The Unofficial Poster Child for Notes and Domino

    JSON and LotusScript: The Basics

    Robert Baehr  November 29 2024 04:31:31 AM
    Greetings:

    The purpose of this post is to provide an overview of JSON to provide a common ground for subsequent posts on JSON and LotusScript.   See the     Business Case for an overview of why this is important.

    Important Terms Used Here:
    • Provider:  This is the source of the data that will be transferred.
    • Consumer: This is the target web application that will accept the data from the Provider.  It is important to note that the Consumer defines the Schema of the JSON data.
    • Schema:  Defined by the Consumer, this is the definition of the JSON data format.  The Provider must obtain the the Schema and understand it in order to process the data correctly and completely.


    For starters, consider the following Domino document that will be used for reference.
    Domino Field Name Value(s) Notes
    vehicleType CAR A single valued text field
    vehicleColorOptions RED
    BLUE
    GREEN     		A multi-valued text field
    vehicleStyle TWO DOOR
    FOUR DOOR     		A multi-valued text field
    vehicleReleaseDate 01/01/2024 A date/time field







    WHAT IS JSON:

    JSON is an acronym for JavaScript Object Notation.  It is a standard which permits the transfer of data from a host system (the provider) to a target system (the consumer) over HTTP/S.  Therefore, it is typically found in web applications.  The "JavaScript" in JSON is merely because the structure of JSON resembles the syntax of JavaScript.   That's where the similarities end.

    The biggest takeaway is that the consumer 'defines' the JSON schema.  Before diving into JSON, make sure that the consumer documents their schema, for if there is a mismatch between what the provider sends and the consumer expects, failure will result.


    The NAVIGATOR:

    Like the Domino form acts as a container for a single record (document) of data, the Navigator is the container for a JSON record.   The definition of a Navigator is the open and closed squiggly brackets ( {} ), as shown below:

    {
    <>
    }



    NAME/VALUE PAIRS:

    Each construct in JSON is made of of name/value pairs, where the name and the value are separated by a colon ( : ), as shown below.

    "name" : "value"

    It is important to understand that the "value" of a name/value par can be any standard data type (strung, number, boolean, date, etc.).  It can also be a JSON Object or JSON Array (covered later).

    Multiple name/value pairs are separated by a comma ( , ), which is short for "but wait, there's more data to process".   The exception is the last name/value pair - it does not end with a comma because there is no more data to process.  

    For example, using the Domino document above, we can view this data in JSON format, as shown:
    Start the Navigator: {
    Add a Name/Value Pair "vehicleType" with the value of "CAR".  Note the trailing comma - there are more Name/Value Pairs to process: "vehicleType" : "CAR",
    Add a Name/Value Pair "vehicleColorOptions" with the value of "BLUE".  Note the absence of a trailing comma - there are no more Name/Value Pairs to process: "vehicleColorOptions" : "BLUE"
    End the navigator: }







    JSON OBJECTS:

    A JSON object is a name/value pair whose data comprises of one or more constructs enclosed in squiggly brackets ( {} ).   In its simplest form, an Object is defined as follows:

    "objectName" : { <> }

    Returning to the sample Domino document, the following could represent the vehicleStyle field:
    Start the Navigator: {
    Add a Name/Value Pair "vehicleType" with the value of "CAR".  Note the trailing comma - there are more Name/Value Pairs to process: "vehicleType" : "CAR",
    Add a Name/Value Pair "vehicleColorOptions" with the value of "BLUE".  Note the trailing comma - there are more Name/Value Pairs to process: "vehicleColorOptions" : "BLUE" ,
    Add a Name/Value pair "vehicleStyle" that is an object containing two Name/Value pairs as members.  Note that "coupe" has a trailing comma, while "sedan" does not: "vehicleStyle" :
    {
    "coupe" : "TWO DOOR",
    "sedan" : "FOUR DOOR"
    }
    End the navigator: }






    JSON ARRAYS:

    A JSON Array is a name/value pair whose data comprises of one or more constructs enclosed in square brackets ( [] ).   In its simplest form, an Array is defined as follows:

    "arrayName" : [ <> ]

    Returning to the sample Domino document, the following could represent the vehicleColor field:
    Start the Navigator: {
    Add a Name/Value Pair "vehicleType" with the value of "CAR".  Note the trailing comma - there are more Name/Value Pairs to process: "vehicleType" : "CAR",
    Add a Name/Value Pair "vehicleColorOptions" that is an array with the values of "BLUE","RED","GREEN".  Note the trailing comma after BLUE and RED, but none after GREEN.  There is one after the ], because there are more name/value pairs to process: "vehicleColorOptions" :
    ]
    "BLUE",
    "RED",
    "GREEN
    ],
    Add a Name/Value pair "vehicleStyle" that is an object containing two Name/Value pairs as members.  Note that "coupe" has a trailing comma, while "sedan" does not: "vehicleStyle" :
    {
    "coupe" : "TWO DOOR",
    "sedan" : "FOUR DOOR"
    }
    End the navigator: }



    HOW TO CONSTRUCT THE JSON DATA RECORD:


    Imagine having to create these constructs from scratch, keeping track of every squiggly bracket, square bracket, and comma.   While it has been done, it can be time consuming, frustrating, and, depending on the Schema definition, just short of a nightmare.


    That's were the LotusScript JSON classes come in - they allow you to construct JSON data records while doing all the housekeeping for you.


    SUMMARY:




    Image:JSON and LotusScript: The Basics

    I hope that "JSON and LotusScript: The Basics" was useful.   Now it is time to move on to the next part in this series - "JSON and LotusScript: The JSON Navigator".



    Cheers!


    Robert Baehr

    The Unofficial Poster Child for Notes and Domino