Note: Changed the license to the Apache License.


The attached database (json.nsf) contains LotusScript classes for parsing and creating JSON text. These classes are contained in five script libraries: ls.snapps.JSONArray, ls.snapps.JSONObject, ls.snapps.JSONReader, ls.snapps.JSONWriter, and ls.snapps.JSONWrapperConverters. The JSONArray and JSONObject classes are wrapper classes that are used by the JSONReader class. There are two versions of the wrapper classes as detailed below. Additional information can be found in the "Help - About This Database" document.

These classes are based on the specification detailed at This includes handling escaped characters and numbers as specified. It is noted below, but the JSONWriter class outputs dates in the following format: yyyy/mm/dd hh:mm:ss UTC+|-hh:mm. This is so that JavaScript can easily convert the text into a Date object.


This class provides a way to parse JSON text into either a JSONObject or JSONArray object or some combination. However, it will always return some type of custom object (if the JSON is valid). Both the JSONObject and JSONArray classes have an Items property. You can put the value of the returned object Items property into a variant and then step through the results. See the ls.snapps.JSONReader library for additional documentation.

Public Method :

-Parse (JSON string)

  This method returns either a JSONArray or a JSONObject or some combination. <br/>


This class provides two ways of outputing JSON text. The first is to pass an array, list, NotesDocument, NotesDocumentCollection, NotesView, NotesViewEntryCollection, or NotesViewEntry to the ToJSON method. This will render the object as JSON. If the object is a type of view object, the output will be taken from the column values. The output data is basically the same as the properties/values of NotesViewEntry. If the object is a document, its output follows the NotesDocument properties/values. However, there are several properties to change how data should be output (see below).

See the ls.snapps.JSONWriter library for additional documentation.

NOTE: For NotesDocuments, all field data is placed into the "Items" object. Field names are set to lowercase. The value of the field is in an array called "Values". The datatype is put in "Type".

      &quot;Items&quot;:{&quot;field1&quot;:{&quot;Values&quot;:[&quot;my value&quot;],&quot;Type&quot;:&quot;TEXT&quot;}} <br/>

NOTE: Date output format: yyyy/mm/dd hh:mm:ss UTC+|-hh:mm

Output examples:

Single document (default):


 {&quot;Authors&quot;:[&quot;CN=Troy Reimer\/O=SNA&quot;],...,&quot;Items&quot;:{&quot;field1&quot;: ...}}<br/>


Single document (OutputAsArray = true):


 {&quot;Authors&quot;:[&quot;CN=Troy Reimer\/O=SNA&quot;],...,&quot;Items&quot;:{&quot;field1&quot;: ...}}<br/>


Multiple documents (default):


 &quot;unid1&quot;:{&quot;Authors&quot;:[&quot;CN=Troy Reimer\/O=SNA&quot;],...,&quot;Items&quot;:{&quot;field1&quot;:...}},<br/>
 &quot;unid2&quot;:{&quot;Authors&quot;:[&quot;CN=Troy Reimer\/O=SNA&quot;],...,&quot;Items&quot;:{&quot;field1&quot;:...}}<br/>


Multiple documents (OutputAsArray = true):


 {&quot;Authors&quot;:[&quot;CN=Troy Reimer\/O=SNA&quot;],...,&quot;Items&quot;:{&quot;field1&quot;: ...}},<br/>
 {&quot;Authors&quot;:[&quot;CN=Troy Reimer\/O=SNA&quot;],...,&quot;Items&quot;:{&quot;field1&quot;: ...}}<br/>


This class also provides an pseudo-object oriented way of creating JSON text. Each public method returns a string with the JSON text requested. It generates an error if arrays and objects are not begun and ended in the correct order. The first method called must be either BeginArray or BeginObject. The AppendValue method accepts only scalar values.

Public Properties :

-IncludeRichTextItems (boolean, default is True)

   Excludes RichTextItem values if set to false.<br/>

-OuputAsArray (boolean, default is False)

   Outputs the JSON as an array instead of as an associative array (see above)<br/>

-OutputViewAsDocuments(boolean, default is False)

   Outputs documents found in the view as NotesDocuments instead of as NotesViewEntries<br/>

-TruncateRichText (long)

   Sets the number of characters to output from RichTextItems. <br/>

Public Methods :

-AppendJSON(JSON string)

   Assumes the input text is valid JSON and appends it to the end of the JSON string being built<br/>


   Appends the input value to the JSON string<br/>


   Begins an array (i.e. &quot;[&quot;)<br/>

-BeginCallbackFunction(Function name)

   Begins the JavaScript callback function input<br/>


   Begins an object (i.e. &quot;{&quot;)<br/>


   Ends an array (i.e. &quot;]&quot;)<br/>


   Ends the callback function<br/>


   Ends an object (i.e. &quot;}&quot;)<br/>


   Appends the name of a key to the JSON string<br/>


   Sets the fields to output from a NotesDocument object<br/>

-ToJSON(Array | List | NotesDocument | NotesDocumentCollection | View | NotesViewEntryCollection | NotesViewEntry)

   Converts the input into a JSON string <br/>

Wrapper classes

The following wrapper classes are used by the JSONReader class to parse the JSON string into Lotuscript objects. The classes below are defined in the ls.snapps.JSONArray, ls.snapps.JSONObject libraries. The ls.snapps.JSONWrapperConverters library defines both classes and allows you to convert the object back to a JSON string. This is accomplished internally by including the ls.snapps.JSONWriter in the converters library. If you need lighter weight versions of the classes, you can use the ones in the ls.snapps.JSONObject and ls.snapps.JSONArray libraries.


This is a wrapper class used by the JSONReader to represent an array. If you use the JSONArray class defined in the ls.snapps.JSONWrapperConverters library, you can convert the JSONArray back to a JSON string using the ToJSON method.

Public Properties :


  Returns a count of the number of items in the array<br/>


  Returns the items in the array as a Variant <br/>

Public Methods :


  Adds the input value to the JSONArray<br/>


  Remove the item of the input index from the JSONArray<br/>

-ReplaceItemValue(Index, Value)

  Replaces the item in the JSONArray at the input Index with the input Value<br/>

-ToJSON only available in the ls.class.JSONWrapperConverters library

  Returns the JSONArray as a JSON string<br/>


This is a wrapper class used by the JSONReader to represent an object. The name/value pairs are stored internally in a List variable. If you use the JSONObject class defined in the ls.snapps.JSONWrapperConverters library, you can convert the JSONObject back to a JSON string using the ToJSON method.

Public Properties:


  Number of items in the list<br/>


  Returns the items as a List <br/>

Public Methods:

-AddItem(Name, Value)

  Adds the input value to the JSONObject<br/>


  Returns the value of the specified item<br/>


  Removes the named item from the JSONObject<br/>

-ReplaceItemValue(Name, Value)

  Replaces the named item in the JSONObject List with the input value<br/>

-ToJSON only available in the ls.class.JSONWrapperConverters library

  Returns the JSONObject as a JSON string