Review of CL JSON Libraries UPDATED 15 May 2023

Consider a JSON string with unicode characters. The JSON data string is the first row in each table.

• (1) Did not handle the unicode char codes
• (2) Repeated the unicode char codes

In the following table, we show the results of attempting to decode unicode with surrogate pairs

Conclusion: If you may have surrogate pairs in your JSON data, you might want to stick to com.inuoe.jzon, jonathan, json-streams, jsown, shasht, st-json or yason.

Contrary to some people's belief systems that boolean logic encompasses everything, there is a meaningful difference between "false" and "unknown". Null ≠ nil. For that matter, I subscribe to the belief that (not true) is not the same as the empty set. JSON's null and empty arrays can track the differences between false, null and empty array. When translating back and forth between CL and JSON, it is important to be able to keep those distinction. Thank you, com.gigamonkeys.json, com.inuoe.jzon, shasht and st-json for getting them correct right out of the box and thank you to jonathan and yason for giving me the ability to get there with setting a variable.

• (1) The cl-boost author notes in his README that "it is not possible to distinguish between false, null, or []. And, I have personally never found this to be problematic." Obviously your experience may vary. My experience is that they show meaningful differences between "false" and "unknown". I think his position is stronger if the question is solely between nil and [].
• (2) When reading a JSON object with nil and null, json-streams provides no value for the cons cell which represents the JSON value false. I would have expected the cons cell to have a value of nil.
• (3) When called with :object-as :plist, the nil is explicit: ("1" T "2" NIL "3" nil)
• (4) Jonathan called with jonathan:*null-value* set to :null. Yason called with yason:*parse-json-null-as-keyword* set to t or passing the keyword parameter :json-nulls-as-keyword t to yason:parse

The following table shows how the various libraries try to decode a JSON object with an empty array as the value. Com.gigamonkeys, com.inuoe.jzon, json-lib and shasht are the clearest representation of the original JSON.

Now looking at all four types within a JSON array:

• (1) Jonathan called with jonathan:*null-value* set to :null. Yason called with yason:*parse-json-null-as-keyword* set to t or passing the keyword parameter :json-nulls-as-keyword t to yason:parse

• (1) Yason called with additional keyword parameter :json-arrays-as-vectors t

For the JSON object examples, we will be using the following simple JSON string:

(defparameter *address-1* "{
  \"name\": \"George Washington\",
  \"birthday\": \"February 22, 1732\",
  \"address\": \"Mount Vernon, Virginia, United States\"
}"

• (1) All four libraries that decode a JSON object to a CL hash use strings as hash keys by default. All four will allow you to optionally use keywords instead. Shasht and yason allow you to decode a JSON object to alists or plists instead of hashes.

For nested object examples, we will be using the following simple JSON object:

(defparameter *nested-address-1* "{
  \"first_name\": \"George\",
  \"last_name\": \"Washington\",
  \"birthday\": \"1732-02-22\",
  \"address\": {
    \"street_address\": \"3200 Mount Vernon Memorial Highway\",
    \"city\": \"Mount Vernon\",
    \"state\": \"Virginia\",
    \"country\": \"United States\"
  }
}")

Boost-json will decode the JSON nested object to a CLOS object class called boost-json:json-object.

(boost-json:json-decode *nested-address-1*)
#<BOOST-JSON:JSON-OBJECT
{"first_name":"George","last_name":"Washington","birthday":"1732-02-22","address":#}>

It appears like you need to call (json-getf obj keyword) in order to act as an accessor. E.g.

(let ((data (boost-json:json-decode *nested-address-1*)))
  (setf (boost-json:json-getf data "first_name") "Michael")
  data)
#<BOOST-JSON:JSON-OBJECT
{"first_name":"Michael","last_name":"Washington","birthday":"1732-02-22","address":#}>

cl-json can decode and convert them to a cl-json:fluid-class CLOS object. You do need to at least temporarily set the change the decoder to use simple-clos-semantics and set the *json-symbols-package* to nil. (Note, this is thread unsafe unless you have pre-created. Per the documentation: "To maintain the mapping between lists of superclass names and fluid classes, the decoder maintains a class registry. Thus, using fluid objects makes the CLOS decoder essentially thread-unsafe. (If every incoming JSON Object is guaranteed to have a prototype with a "lispClass" member then there are no fluid objects and thread safety is ensured.) If the user wishes to employ fluid objects in a threaded environment it is advisable to wrap the body of entry-point functions in with-local-class-registry.")

First, looking at the simpler version, notice you need to specify the slots in the fluid-class object:

(cl-json:with-decoder-simple-clos-semantics
 (setf cl-json:*json-symbols-package* nil)
 (let ((x (cl-json:decode-json-from-string *address-1*)))
   (with-slots (name birthday address) x
     (values x name birthday address)))))
#<#<JSON:FLUID-CLASS COMMON-LISP:NIL {100F765713}> {100FB22513}>
"George Washington"
"February 22, 1732"
"Mount Vernon, Virginia, United States"

Now looking at the nested version, we need to note that by default cl-json will convert the underscores in the JSON keys to double hyphens in the slot names.

(cl-json:with-decoder-simple-clos-semantics
 (setf cl-json:*json-symbols-package* nil)
 (let ((x (cl-json:decode-json-from-string *nested-address-1*)))
   (with-slots (first--name last--name birthday address) x
     (values x first--name last--name birthday address)))))
#<#<JSON:FLUID-CLASS COMMON-LISP:NIL {100F765713}> {10107CF9E3}>
"George"
"Washington"
"1732-02-22"
#<#<JSON:FLUID-CLASS COMMON-LISP:NIL {100F765713}> {10107CF6F3}>

Because we have a nested class, we would need drill down and specify the slots for the sub-object as well:

(cl-json:with-decoder-simple-clos-semantics
 (setf cl-json:*json-symbols-package* nil)
 (let ((x (cl-json:decode-json-from-string *nested-address-1*)))
   (with-slots (first--name last--name birthday address) x
     (with-slots (street--address city state country) address
       (values x first--name last--name birthday address city))))))
#<#<JSON:FLUID-CLASS COMMON-LISP:NIL {100F765713}> {1010E69B93}>
"George"
"Washington"
"1732-02-22"
#<#<JSON:FLUID-CLASS COMMON-LISP:NIL {100F765713}> {1010E698A3}>
"Mount Vernon"

If you have defined your classes, trivial-json-codec does make it easy to decode JSON data directly to a vector of your classes. Suppose we have a simple person class:

(defclass person ()
  ((name
    :initarg :name :initform "Sabra"
    :accessor name)
   (eye-colour :initarg :eye-colour
    :initform "brown"
    :accessor eye-colour)))

If we have a vector of JSON objects which are all data for a person class, we can automatically build a vector of persons by specifying the class we want to use:

(let ((data
        (trivial-json-codec:deserialize-json
         "[{\"name\":\"Claudia\",\"eye-colour\":\"blue\"},
           {\"name\":\"Johann\",\"eye-colour\":\"brown\"}]"
         :class (find-class 'person))))
  (name (aref data 1)))
"Johann"

There is no magic if the JSON array has objects of different types.

Using '(("A" . 1) ("B" . 2) ("C" . 3)) as the sample data

• (1) Fail - the JSON arrays are invalid. They have ',.' rather than ','
• (2) You may be able to write a new method to handle dotted.
• (3) Only if (setf shasht:*write-alist-as-object* t), which is not the default. Otherwise it generates an error.
• (4) If the alist has dotted cons cells, jsown and st-json triggered unhandled memory faults with SBCL 2.1.11-x86-64-linux, CCL version 1.12.1 LinuxX8664 and ecl-version 21.2.1. This appears to be because jsown and st-json have optimized the code and assumed that all lists will be proper lists. The assumption obviously fails in the context of dotted cons cells.
• (5) You would need to use lower level components of json-streams. See json-streams-encoding.
• (6) This is a regression

Now we change the data slightly, still using dotted pairs, but with a nested list as the value in one pair: Using '(("foo" . "bar") ("baz" . ((1 2 3) (4 5 6)))) as the sample data.

• (1) Fail - the JSON arrays are invalid. They have ',.' rather than ','
• (2) You may be able to write a new method to handle dotted.
• (3) This error is generated if shasht:*write-alist-as-object* is nil (the default).
• (3a) If shasht:*write-alist-as-object* is t (not the default).
• (4) If the alist has dotted cons cells, jsown and st-json triggered unhandled memory faults with SBCL 2.1.11-x86-64-linux, CCL version 1.12.1 LinuxX8664 and ecl-version 21.2.1. This appears to be because jsown and st-json have optimized the code and assumed that all lists will be proper lists. The assumption obviously fails in the context of dotted cons cells.
• (5) You would need to use lower level components of json-streams. See json-streams-encoding.
• (6) This is a regression

Notice the difference in the successful results. cl-json and yason's result of {"foo":"bar","baz":[[1,2,3],[4,5,6]]} is what I would have expected. jonathan tried to force a key value pair into the second alist value. {"foo":"bar","baz":{"1":[2,3],"4":[5,6]}}.

Using '(("A" 1) ("B" 2) ("C" 3)) as the sample data.

Note difference in results. Some libraries return arrays, others return objects. Some libraries return key:[value] pairs, others return two member arrays.

• (1) Using json-stringify caused the alist used as data to fall through etypecase expression demanding a json-streams:json-array. That means that you have to fall back to more complicated calls. See json-streams-encoding.
• (2) Before recent changes, com.inuoe.jzon would have returned {"A":[1],"B":[2],"C":[3]}

Let's make the value portion of the alist another alist. Now using '(("foo" "bar") ("baz" ((1 2 3) (4 5 6)))) as the sample data. The results may or may not be what you want, so look at them carefully.

• (1) You would need to use lower level components of json-streams. See json-streams-encoding.
• (2) Before recent changes, com.inuoe.jzon would have returned {"foo":["bar"],"baz":[[[1,2,3],[4,5,6]]]}

Yason:encode-alist and jonathan return JSON objects with key pairs; the rest try to return arrays. jonathan seem to be trying to force a key value pair into the baz values when I do not think this is probably what you want. Yason's heuristics return the same result. Let's change the data slightly and just look at these two libraries again.

Boost-json loses the first value in the vector. Json-streams and st-json do not handle the vector. All the other libraries pass, although some get excited about the floating point number.

Using #("A" 1 2.3) as sample data.

• (1) You would need to use lower level components of json-streams. See json-streams-encoding.
• (2) You need to write your own st-json::write-json-element function for arrays. Possibly something like:

(defmethod write-json-element ((element vector) stream)
  (declare #.*optimize*)
  (write-char #\[ stream)
  (loop :for val :across element
          :for first := t :then nil
          :unless first :do (write-char #\, stream)
          :do (write-json-element val stream))
  (write-char #\] stream))

See st-json-encoding.

Again boost-json, json-streams and st-json fail. The rest pass.

Using #*10110 as the sample data.

• (1) You would need to use lower level components of json-streams. See json-streams-encoding.
• (2) Error: Can not write object of type (SIMPLE-BIT-VECTOR 5) as JSON. You can resolve this by writing your own method for handling symbols. See st-json-encoding.

The following example uses a very simple nested array:

#(#("Dublin" "Cork" "Limerick") #("Berlin" "Frankfurt" "Munich"))

• (1) You would need to use lower level components of json-streams. See json-streams-encoding.
• (2) Error: Can not write object of type (SIMPLE-BIT-VECTOR 5) as JSON. You can resolve this by writing your own method for handling symbols. See st-json-encoding.

Just to see what happens if we give the libraries a two dimensional array, let's use #2A((1.0 1.0) (1.0 1.0) (1.0 1.0)) as the sample data.

Jsown and shasht are the only libraries to handle a two dimensional array without the user having to write additional methods.

• (1) You would need to use lower level components of json-streams. See json-streams-encoding.
• (2) You can resolve this by writing your own method for handling symbols. See st-json-encoding.

Using (alexandria:plist-hash-table '("foo" 1 "bar" (7 8 9)) :test #'equal) as the sample data:

• (1) The hash table encoding is fine. In this example com.gigamonkeys.json is treating the list which is a hash table value as a plist and trying to create key:value pairs.
• (2) You would need to use lower level components of json-streams. See json-streams-encoding.
• (3) May be able to resolve this with writing your own method.

Using (alexandria:plist-hash-table '(:foo 1 :bar (7 8 9)) :test #'eq) as the sample data: Again, see what gigamonkeys is doing with respect to trying to treat the list as key:value pairs.

• (1) The symbol must be a keyword symbol or com.gigamonkeys.json will error out. As noted above, it is also trying to treat the embedded list as key:value pairs rather than an array.
• (2) If the symbols were not keywords, json-lib would return "{null: 1, null: [7, 8, 9]}"
• (3) You would need to use lower level components of json-streams. See json-streams-encoding.
• (4) You will need to write your own method to handle symbols in this situation
• (5) May be able to resolve this with writing your own method.
• (6) There is no applicable method for the generic function when called with arguments :symbol

In the first easy test, the only surprises were jonathan reversing the order of the elements in the JSON object and I do not know what trivial-json-codec is doing with the angle brackets in the JSON object test.

• (1) trivial-json-codec is really intended as a parser (one way) from JSON to CL, not really serializing to JSON.
• (2) Ignoring the reversed order issue, consider the following from jonathan. We decode a JSON object as an alist. Jonathan returns an alist with dotted pairs. E.g.

(jonathan:parse "{\"a\":1,\"b\":2}" :as :alist)
(("b" . 2) ("a" . 1))

If we then pass that to jonathan:to-json, it throws an error because jonathan does not handle alists with dotted pairs. I am only calling this out because jonathan expressly provides you with the ability to return a JSON object as a dotted pair alist, but then cannot handle it going back the other direction.

Everyone passes when dealing with the easy array with no nulls involved.

• (1) I was surprised that cl-json failed here by returning a JSON array instead of a JSON object. This is flagged on the homepage as issue 22.

Now we make it a bit trickier with the following JSON string, decoded and then encoded it to see if we got back the original. This has trickier bits because of the unicode, exponent and false and null. The results are pretty much what you would expect.

"{\"key1\":\"value\\n\",\"key2\":1,\"key3\":[\"Hello \\u2604\",1.2e-34 ,true,false,null]}"

• (1) unicode expanded to the appropriate character which I will treat as a success
• (2) You need to pass :json-booleans-as-symbols t to the yason parse function as a keyword argument in order to get false and it will come out as a YASON:FALSE symbol
• (3) Exponent expanded to a decimal which I could argue is a success. Your call.
• (4) trivial-json-codec is really intended as a parser (one way) from JSON to CL, not really serializing to JSON.
• (5) both false and null are converted to [], but they are different concepts.

• (1) Up to you whether you want to treat the exponent expanded to a decimal as a pass or fail

This batch of JSON strings whould be accepted by all libraries. The only libraries to meet that standard are com.inuoe.jzon and com.gigamonkeys.json. Almost all the rest came "reasonably" close.

• (1) If *read-default-float-format* is set to 'single-float, there will be decoding failures on [123e65], [123e45], [123.456e78],
• (2) Failed on [123.456e78] even with *read-default-float-format* is set to 'double-float
• (3) rejected files with duplicate keys. This can be resolved by passing the keyword parameter :duplicate-key-check nil
• (4) Failed on lonely numbers (an integer or negative real not within a JSON array or JSON object)
• (5) Failed on [[] ], [0e+1], [1E+2], [1e+2], { "min": -1.0e+28, "max": 1.0e+28 }

This batch of JSON strings were designed to find the under-specified holes in the JSON specification. As such, libraries could accept or reject the strings without being out of compliance with the standard. For purposes of the following table, I only tested files that could be read as encoded in utf-8.

What I found troubling was that jonathan and jsown all hung on one or more of these strings.

• (1) hang on i_number_real_underflow [123e-10000000]

Only three libraries did not hang or trigger stack exhaustion on strings designed to open thousands of beginning nested arrays or objects. Those are com.inuoe.jzon, json-lib and json-streams. All three have a limit and refused to exceed the limit.

• (1) n_structure_open_array_object.json, n_structure_100000_opening_arrays.json
• (2) n_structure_open_array_object.json

The following charts are reading from stream rather than from string (so a slightly smaller list of libraries) and jonathan choked on both files being read into the stream, so it is excluded as well. We see the same comparative results when reading from stream as when we read from strings.

Please note the direction of the arrows in the following table.

Boost-json has different functions for decoding from strings (json-decode) or streams (json-read). JSON arrays are decoded to CL lists and JSON objects are decoded to a CLOS object with slot-value names interned in the boost-json package.

I find its handling of nil and false a bit confusing. Consider the following examples:

(boost-json:json-decode "[false]")
(NIL)

(boost-json:json-decode "{\"A\":false}")
#<BOOST-JSON:JSON-OBJECT {"A":null}>

Within an array, JSON's 'false' is converted to CL nil, but within a JSON object, JSON's 'false' is convert to CL :null. Why?

We also have a symmetry problem with respect to JSON's 'false'. See the following:

(boost-json:json-encode
 (boost-json:json-decode "{\"A\":false}"))
{"A":null}

The starting point with 'false' got converted to null.

Boost-json does not handle unicode surrogate pairs if you care about that sort of thing.

On the plus side, boost-json was one of two libraries which could encode a pathname.

On the neutral side, data types like char, local-time:timestamps and structs would require you to write an encoding method to handle them if you have them.

On the "choose your data structures carefully side",

• Encoding hash-tables succeeds if the hash-table keys are strings, fails if they are symbols
• Encoding vectors results in invalid results, generally losing the first value in the array. Sample output on a simple nested array looked like: [,"Cork","Limerick"][,[,"Frankfurt","Munich"]]

• Boost-json will try to encode alists as JSON arrays of array. It will generate invalid JSON if the alisp has dotted pairs.

  (boost-json:json-encode '(("A" . 1) ("B" . 2) ("C" . 3)))
  [["A",. 1],["B",. 2],["C",. 3]]
  

  If the array is not dotted pairs, boost-json will give you arrays of arrays.

  (boost-json:json-encode '(("A"  1) ("B"  2) ("C"  3)))
  [["A",1],["B",2],["C",3]]
  

From the standpoint of symmetry or round-tripping, going from JSON->CL->JSON it only fails on dealing with 'false'.

It had more problems going from CL->JSON->CL. In some tests it triggered an error with an expected #\N, in others nil came back as nul and it could lose the first value in vectors.

There were two general security issues we considered: (1) interning keywords and (2) issues with malformed data.

Boost-json did not exhibit the first issue in the same way that e.g. cl-json does. However, it does decode JSON objects to a CLOS object with slot-value names interned in the boost-json package.

With respect to the second issue, boost-json properly rejected 145 malformed test cases but accepted 28. Some of those malformed test cases which were accepted actually triggered stack exhaustion by opening too many levels of JSON open arrays and not closing them or similar types of issues.

Boost-json accepted 95 of the 95 test cases that are considered "must accept". If *read-default-float-format* is set to 'single-float, it would refuse to accept: [123e65], [123e45] and [123.456e78].

It accepted 13 of the 17 test cases considered to be part of the gray area of the JSON specification - you could accept or reject.

See Benchmarking

• json-decode - Convert a JSON string into a Lisp object.
• json-encode - Encodes a Lisp value into a stream.
• json-read - decode from a stream
• json-enable-reader-macro - enable json-object-reader macro
• json-object
• json-object-members
• json-getf - Find an member's value in a JSON object.
• json-setf - Assign a value to a key in a JSON object.

Please note the direction of the arrows in the following table.

• (1) This is cl-json's default mode. Using cl-json:with-decoder-simple-clos-semantics or cl-json:simple-clos-semantics will switch cl-json into a mode where JSON arrays are decoded to cl vectors rather than lists, and JSON objects are decoded to CLOS objects rather than alists.

Cl-json uses different functions to decode from a string (decode-json-from-string x) v. decoding from a stream (decode-json x).

It converts JSON's 'null' to NIL, which I disagree with. It also fails to deal with unicode surrogate pairs if you care about those.

JSON objects are converted to alists with dotted pairs which is unusual for the rest of the libraries.

Basic encoding functionality is provided by the generic function encode-json. This can be customised with an entire series of macros as listed in the documentation. cl-json's basic encoding function returns an object when handed an alist and returns an array when handed a plist. When handed a list of plists or list of alists, encode-json will return an array but the list of plists returned an array of arrays and the list of alists returned an array of objects.

cl-json provides a function to encode the alist properly as key:value, but my samples do not show any difference between cl-json:encode-json and cl-json:encode-json-alist. It will encode a dotted alist as a JSON object with key:value pairs. It will encode a proper list alist as an array of arrays.

(cl-json:encode-json '(("A" . 1) ("B" . 2) ("C" . 3)))
{"A":1,"B":2,"C":3}

(cl-json:encode-json '(("A" 1) ("B" 2) ("C" 3)))
[["A",1],["B",2],["C",3]]

On the plus side,

• cl-json was the only library to handle encoding char out of the box.

On the "be care side:

• As you might expect, plists are treated the same as plain lists and will lose their key-value connections. If you want to keep the key-value connections, you can either convert the list to an alist or hash-table or use the cl-json:encode-json-plist function.

On the "slightly additional work" side:

• Encoding structures, pathnames and timestamps would require writing a specialized method

On the not-so-plus side:

• It encodes nil as null. You can use the helper library cl-json-helper to encode nil as "false".

From the standpoint of symmetry or round-tripping, going from JSON->CL->JSON, it only fails on dealing with false.

Similarly, going from CL->JSON->CL, you would need to deal with the fact that :NULL got converted to "null".

There were two general security issues we considered: (1) interning keywords and (2) issues with malformed data.

With respect to the first issue, Cl-json flags the issue and provides the function safe-json-intern - which will throw an error if the keyword to be interned does not already exist in the *json-symbols-package*. - so at least you are warned and provided with an alternative.

With respect to the second issue, cl-json properly rejected 153 malformed test cases but accepted 20. Some of those malformed test cases which were accepted actually triggered stack exhaustion by opening too many levels of JSON open arrays and not closing them or similar types of issues.

cl-json accepted 95 of the 95 test cases that are considered "must accept". If *read-default-float-format* is set to 'single-float, it would refuse to accept: [123e65], [123e45] and [123.456e78].

It accepted 13 of the 17 test cases considered to be part of the gray area of the JSON specification - you could accept or reject.

See Benchmarking

1. Error Conditions Cl-json has several error conditions, some of them recoverable and some of them not recoverable. These include "unrecoverable-value-error", "json-syntax-error", "no-char-for-code", "cell-error" "type-error", errors for calling functions in the wrong environment and others. Please read the user-manual for more details.
2. Cl-json has a converter from camel case to "lisp" (i.e., kebab case) and back again.
3. Cl-json has a lot of other capabilities. The documentation is excellent and you should seriously consider the security considerations section of the user manual if you are going to be decoding uncontrolled JSON objects.

• *aggregate-scope-variables*
• *array-member-handler*
• *array-scope-variables*
• *beginning-of-array-handler*
• *beginning-of-object-handler*
• *beginning-of-string-handler*
• *boolean-handler*
• *end-of-array-handler*
• *end-of-object-handler*
• *end-of-string-handler*
• *identifier-name-to-key* - Designator for a function which, during decoding, maps the *json-identifier-name-to-lisp* -transformed key to the value it will have in the result object.
• *integer-handler*
• *internal-decoder*
• *json-array-type*
• *json-identifier-name-to-lisp* - Designator for a function which maps string (a JSON Object key) to string (name of a Lisp symbol).
• *json-input* - The default input stream for decoding operations.
• *json-output* - The default output stream for encoding operations.
• *json-symbols-package* - The package where JSON Object keys etc. are interned. Default keyword, nil = use current package.
• *lisp-identifier-name-to-json* - Designator for a function which maps string (name of a Lisp symbol) to string (e. g. JSON Object key).
• *object-key-handler*
• *object-scope-variables*
• *object-value-handler*
• *prototype-name*
• *real-handler*
• *string-char-handler*
• *string-scope-variables*
• *use-strict-json-rules* - If non-nil, signal error on unrecognized escape sequences in JSON Strings. If nil, translate any such sequence to the char after slash.
• as-array-member - BODY should be a program which encodes exactly one JSON datum to STREAM. AS-ARRAY-MEMBER ensures that the datum is properly formatted as a Member of an Array, i. e. separated by comma from any preceding or following Member.
• as-object-member - BODY should be a program which writes exactly one JSON datum to STREAM. AS-OBJECT-MEMBER ensures that the datum is properly formatted as a Member of an Object, i. e. preceded by the (encoded) KEY and colon, and separated by comma from any preceding or following Member.
• bignumber-string
• bind-custom-vars
• camel-case-to-lisp - Take a camel-case string and convert it into a string with Lisp-style hyphenation.
• clear-class-registry - Reset the *CLASS-REGISTRY* to NIL.
• current-decoder - Capture current values of custom variables and return a custom decoder which restores these values in its dynamic environment.
• custom-decoder - Return a function which is like DECODE-JSON called in a dynamic environment with the given CUSTOMIZATIONS.
• decode-json - Read a JSON Value from STREAM and return the corresponding Lisp value.
• decode-json-from-source - Decode a JSON Value from source using the value of decoder (default 'decode-json) as decoder function. If the source is a string, the input is from this string; if it is a pathname, the input is from the file that it names; otherwise, a stream is expected as source.
• decode-json-from-string - Read a JSON Value from json-string and return the corresponding Lisp value.
• decode-json-strict - Same as decode-json, but allow only Objects or Arrays on the top level, no junk afterwards.
• encode-array-member - Encode OBJECT as the next Member of the innermost JSON Array opened with WITH-ARRAY in the dynamic context. OBJECT is encoded using the ENCODE-JSON generic function, so it must be of a type for which an ENCODE-JSON method is defined.
• encode-json - Write a JSON representation of OBJECT to STREAM and return NIL.
• encode-json-alist - Write the JSON representation (Object) of alist to stream (or to json-output). Return nil.
• encode-json-alist-to-string - Return the JSON representation (Object) of alist as a string
• encode-json-plist - Write the JSON representation (Object) of plist to stream (or to json-output). Return nil.
• encode-json-plist-to-string - Return the JSON representation (Object) of plist as a string.
• encode-json-to-string - Return the JSON representation of object as a string.
• encode-object-member - Encode KEY and VALUE as a Member pair of the innermost JSON Object opened with WITH-OBJECT in the dynamic context. KEY and VALUE are encoded using the ENCODE-JSON generic function, so they both must be of a type for which an ENCODE-JSON method is defined. If KEY does not encode to a String, its JSON representation (as a string) is encoded over again.
• fluid-class - A class to whose instances arbitrary new slots may be added on the fly.
• fluid-object
• json-bind
• json-bool - Intended for the JSON-EXPLICT-ENCODER. Converts a non-nil value to a value (:true) that creates a JSON true value when used in the explict encoder. Or (:false).
• json-decode
• json-enable-reader-macro
• json-encode
• json-getf
• json-intern - Intern STRING in the current *JSON-SYMBOLS-PACKAGE*.
• json-object
• json-object-members
• json-or-null - Intended for the JSON-EXPLICT-ENCODER. Returns a non-nil value as itself, or a nil value as a JSON null-value
• json-read
• json-setf
• json-syntax-error - Signal a JSON-SYNTAX-ERROR condition
• lisp-to-camel-case - Take a string with Lisp-style hyphentation and convert it to camel case. This is an inverse of CAMEL-CASE-TO-LISP.
• make-object - If CLASS is not NIL, create an instance of that class. Otherwise, create a fluid object whose class has the given SUPERCLASSES (null list by default). In either case, populate the resulting object using BINDINGS (an alist of slot names and values).
• make-object-prototype - Return a PROTOTYPE describing the OBJECT's class or superclasses, and the package into which the names of the class / superclasses and of the OBJECT's slots are to be interned.
• no-char-for-code
• pass-code
• placeholder
• prototype - A PROTOTYPE contains metadata for an object's class in a format easily serializable to JSON: either the name of the class as a string or (if it is anonymous) the names of the superclasses as a list of strings; and the name of the Lisp package into which the names of the class's slots and the name of the class / superclasses are to be interned.
• rational-approximation
• safe-json-intern - The default json-intern is not safe. Interns of many unique symbols could potentially use a lot of memory. An attack could exploit this by submitting something that is passed through cl-json that has many very large, unique symbols. This version is safe in that respect because it only allows symbols that already exists.
• set-custom-vars
• set-decoder-simple-clos-semantics - Set the decoder semantics to the following:
  • Strings and Numbers are decoded naturally, reals becoming floats.
  • The literal name true is decoded to T, false and null to NIL.
  • Arrays are decoded to sequences of the type *JSON-ARRAY-TYPE*.
  • Objects are decoded to CLOS objects. Object keys are converted by the function *JSON-IDENTIFIER-NAME-TO-LISP*. If a JSON Object has a field whose key matches *PROTOTYPE-NAME*, the class of the CLOS object and the package wherein to intern slot names are inferred from the corresponding value which must be a valid prototype. Otherwise, a FLUID-OBJECT is constructed whose slot names are interned in *JSON-SYMBOLS-PACKAGE*
• set-decoder-simple-list-semantics - Set the decoder semantics to the following:
  • Strings and Numbers are decoded naturally, reals becoming floats.
  • The literal name true is decoded to T, false and null to NIL.
  • Arrays are decoded to sequences of the type *JSON-ARRAY-TYPE*.
  • Objects are decoded to alists. Object keys are converted by the function *JSON-IDENTIFIER-NAME-TO-LISP* and then interned in the package *JSON-SYMBOLS-PACKAGE*.
• simplified-camel-case-to-lisp - Insert - between lowercase and uppercase chars. Ignore _ + * and several consecutive uppercase.
• stream-array-member-encoder - Return a function which takes an argument and encodes it to STREAM as a Member of an Array. The encoding function is taken from the value of ENCODER (default is #'ENCODE-JSON).
• stream-object-member-encoder - Return a function which takes two arguments and encodes them to STREAM as a Member of an Object (String : Value pair)
• substitute-char
• substitute-printed-representation
• unencodable-value-error - Signal an UNENCODABLE-VALUE-ERROR
• unknown-symbol-error
• use-explicit-encoder
• use-guessing-encoder
• with-array - Open a JSON Array, run BODY, then close the Array. Inside the BODY, AS-ARRAY-MEMBER or ENCODE-ARRAY-MEMBER should be called to encode Members of the Array.
• with-custom-decoder-level - Execute BODY in a dynamic environment such that, when nested structures are decoded, the outermost level is decoded with the given custom handlers (CUSTOMIZATIONS) whereas inner levels are decoded in the usual way
• with-decoder-simple-clos-semantics - Execute BODY in a dynamic environement where the decoder semantics is such as set by SET-DECODER-SIMPLE-CLOS-SEMANTICS.
• with-decoder-simple-list-semantics - Execute BODY in a dynamic environement where the decoder semantics is such as set by SET-DECODER-SIMPLE-LIST-SEMANTICS.
• with-explicit-encoder
• with-guessing-encoder
• with-local-class-registry - Run BODY in a dynamic environment where *CLASS-REGISTRY* is a temporary local list. If :INHERIT is non-null, the local registry shall initially have the same content as the exterior *CLASS-REGISTRY*, otherwise it shall be NIL.
• with-object - Open a JSON Object, run BODY, then close the Object. Inside the BODY, AS-OBJECT-MEMBER or ENCODE-OBJECT-MEMBER should be called to encode Members of the Object.
• with-shadowed-custom-vars
• with-substitute-printed-representation-restart - Establish a SUBSTITUTE-PRINTED-REPRESENTATION restart for OBJECT and execute BODY.

Please note the direction of the arrows.

Com.gigamonkeys.json only takes strings as inputs. It does not handle unicode surrogate pairs. On the plus side, it handles NULL issues correctly.

As noted in the mapping table above, JSON objects will be decoded as plists (or nested plists). Consider the following example of decoding a nested JSON object:

(com.gigamonkeys.json:parse-json "{
  \"first_name\": \"George\",
  \"last_name\": \"Washington\",
  \"birthday\": \"1732-02-22\",
  \"address\": {
    \"street_address\": \"3200 Mount Vernon Memorial Highway\",
    \"city\": \"Mount Vernon\",
    \"state\": \"Virginia\",
    \"country\": \"United States\"
  }
}")

("first_name" "George" "last_name" "Washington" "birthday" "1732-02-22"
 "address"
 ("street_address" "3200 Mount Vernon Memorial Highway" "city" "Mount Vernon"
  "state" "Virginia" "country" "United States"))

Arrays are decoded to vectors.

There were a few surprises looking at what com.gigamonkeys.json would encode and not encode.

• It encodes keyword symbols, but not other symbols.
• It actually hangs on encoding chars and CLOS objects, which I found strange. Most of the other libraries generated errors.
• Attempting to encode a pathname also results in hanging
• nil encodes to {} (yes, empty object)
• Like some other libraries, it cannot deal with alists directly. Consider using alexandria:alist-hash-table to convert the alist to a hash table.
• On the other hand, in reversal from some of the other libraries, com.gigamonkeys.json will assume a plain list is a plist, returning a JSON object with key-value pairs. If the length of the list is odd, the final value in the list will be treated as a key and an empty set will be inserted as the value.

Let's take a closer look at the encoding functions. As noted previously, com.gigamonkeys.json will assume a plain list is a plist, returning a JSON object with key-value pairs. In the examples below, that means that since it is given a three value list, the third value is assumed to be the second key in an object and the value then is an empty set.

From the standpoint of symmetry or round-tripping, going from JSON->CL->JSON, it did not have any issues.

As you might have expected given its ignoring lists, going from CL->JSON->CL resulted in failure with tests starting with lists. If you started from an array, nil turned into {}, and it could get a little excited about how many decimal points it would return with respect to a float.

There were two general security issues we considered: (1) interning keywords and (2) issues with malformed data. com.gigamonkeys.json did not exhibit the first issue.

With respect to the second issue, com.gigamonkeys.json accepted many malformed test cases which triggered stack exhaustion by opening too many levels of JSON open arrays and not closing them or similar types of issues.

com.gigamonkeys.json accepted all 95 test cases that are considered "must accept".

It accepted 14 of the 17 test cases considered to be part of the gray area of the JSON specification - you could accept or reject.

See Benchmarking

• *object-type*
• json - The top-level function for converting Lisp objects into a string in the JSON format. It can convert any object that can be converted to a json-exp via the to-json generic function.
• json-stringify - Convert object directly to a JSON representation as a string. Default methods are provided for strings, symbols (which must be keywords), and numbers but there may be situations where it is appropriate to define new methods on this function. In general, however, it is probably better to define a method on to-json to convert the object to a sexp that can be rendered as JSON.
• parse-json - Parse JSON text into Lisp objects. Hash tables are used to represent Javascript objects and vectors to represent arrays.
• to-json - Generic function that can convert an arbitrary Lisp object to a json-exp, i.e. a sexp that can then be rendered as JSON. To make an arbitrary class convertable to JSON, add a method to this generic function that generates a json-exp.
• write-json - Write data to stream in JSON format.

com.inuoe.jzon can encode to either a stream or string. E.g.:

(com.inuoe.jzon:stringify '("A" "b" 4 3.2 9/4) :stream *standard-output*)
["A","b",4,3.2,2.25]

(com.inuoe.jzon:stringify '("A" "b" 4 3.2 9/4))
"[\"A\",\"b\",4,3.2,2.25]"

Additional Keyword Parameters for Stringify

• :pretty If true, output pretty-formatted JSON
• :coerce-element A function for coercing 'non-native' values to JSON.
• :coerce-key A function for coercing key values to strings.

On the plus side,

• It automatically handles standard CLOS objects and also allows you to specialize.
• It is one of only two libraries which can encode a structure

On the "pay attention to your data structures" side: Recent change: com.inuoe.jzon:stringify will no longer encode an alist as a JSON object. In dropping its heuristics, com.inuoe.jzon has, at least temporarily, lost the ability to handle dotted pairs.

From the standpoint of symmetry or round-tripping, going from JSON->CL->JSON, it did not have any issues. It struggled a bit more with respect to going from CL->JSON->CL. The first test had a starting point of:

((:NAME "George Washington") (:BIRTHDAY "February 22, 1732")
                             (:ADDRESS "Mount Vernon, Virginia, United States"))

and a result (adjusted to get the elements out of the hash-table) of:

(("address" . #("Mount Vernon, Virginia, United States"))
 ("birthday" . #("February 22, 1732")) ("name" . #("George Washington")))

So we went from undotted alist to dotted alist where each value was an array instead of a string. The second test started with an array instead of an alist and com.inuoe.jzon handled it with the one caveat that :NULL turned into "NULL".

There were two general security issues we considered: (1) interning keywords and (2) issues with malformed data. com.inuoe.jzon did not exhibit the first issue.

With respect to the second issue, com.inuoe.jzon rejected all the malformed test cases. It was one of four packages which allowed you to limit the depths to which it would dive in nested JSON objects and, therefore, did not trigger the stack exhaustion exhibited by most of the other packages.

com.inuoe.jzon accepted all 95 test cases that are considered "must accept".

It accepted 7 of the 17 test cases considered to be part of the gray area of the JSON specification - you could accept or reject.

See Benchmarking

• coerce-element - Coerce "element" into a "json-element", using "coerce-key" in cases the result is a hash-table.
• coerce-key - Coerce "key" into a string designator, or "nil" if "key" is an unsuitable key.
• coerced-fields - Return a list of key definitions for "element". A key definition is a three-element list of the form (name value type). Name is the key name and will be coerced if not already a string. Value is the value, and will be coerced if not a json-element. Type is a type for the key, in order to handle ambiguous "nil" interpretations.
• json-atom - a type definition including t, nil, null, real and string
• json-element - a type definition including json-atoms, vectors and hash-tables
• json-eof-error - a json-parse-error
• json-error - a simple condition
• json-parse-error - a json-error condition
• parse - Read a JSON value from `in', which may be a vector, a stream, or a pathname. Keyword parameters: :maximum-depth controls the maximum depth of the object/array nesting. :allow-comments controls whether or not single-line // comments are allowed. :key-fn is a function of one value which 'pools' object keys, or null for the default pool.
• stringify - Serialize "element" into JSON. Returns a fresh string if "stream" is nil, nil otherwise. ":stream" like the "destination" in "format" ":pretty" if true, pretty-format the output ":coerce-element" is a function of two arguments, and is used to coerce an unknown value to a "json-element" ":coerce-key" is a function of one argument, and is used to coerce object keys into non-nil string designators. See "coerce-element" and "coerce-key".

Please note the direction of the arrows in the following table.

• (1) Jonathan can parse a JSON object into plists (the default), alists, hash-tables or a "JSON object" by passing different keyword parameters to the parse function.

The basic encoding function is jonathan:to-json. Jonathan can return either a string or octets.

(jonathan:to-json '(:name "Common Lisp" :born 1984 :impls (SBCL KCL))
         :octets t)
#(123 34 78 65 77 69 34 58 34 67 111 109 109 111 110 32 76 105 115 112 34 44 34
  66 79 82 78 34 58 49 57 56 52 44 34 73 77 80 76 83 34 58 91 34 83 66 67 76 34
  44 34 75 67 76 34 93 125)

When encoding alists or plists or jsown "objects", jonathan requires extra keyword parameters like :from :alist (or :plist, :jsown)

(jonathan:to-json '((a 1) (b 2)) :from :alist)
"{\"A\":[1],\"B\":[2]}"

While to-json can handle a plist without any additional parameters, to-json will throw an error if handed an alist without warning. This gets resolved by adding the additional keyword parameters :from :alist

(jonathan:to-json '((A . 1) (B . 2) (C . 3)) :from :alist)
"{\"A\":1,\"B\":2,\"C\":3}"

Jonathan expects simple-strings, so if your data source does not produce simple strings, you may have to massage the input to get there. Similarly, attempting to encode a char or a pathname will trigger an error. You should be able to methods that would handle them. The same situation arises with respect to encoding structs.

Now consider what happens when jonathan tries to encode alists with dotted pairs:

(jonathan:to-json '(("foo" . "bar") ("baz" . ((1 2 3) (4 5 6)))) :from :alist)

"{\"foo\":\"bar\",\"baz\":{\"1\":[2,3],\"4\":[5,6]}}"

and now without dotted pairs.

(jonathan:to-json '(("foo" "bar") ("baz"  ((1 2 3) (4 5 6)))) :from :alist)
"{\"foo\":[\"bar\"],\"baz\":[{\"1\":[2,3],\"4\":[5,6]}]}"

In both situations, jonathan is trying to force key:value pairs into places you would not expect.

From the standpoint of symmetry or round-tripping, going from JSON->CL->JSON, jonathan reversed the order of the list and converted both falsee and null to [].

Going from CL->JSON->CL, it is not symmetric if the alists have dotted pairs. The array test resulted in getting the array converted into a list and :NULL was converted to nil.

There were two general security issues we considered: (1) interning keywords and (2) issues with malformed data. Jonathan has the first issue.

With respect to the second issue, jonathan properly rejected 128 out of 173 malformed test cases. Unfortunately it was one of the packages that accepted malformed JSON data that would trigger stack exhaustion.

jonathan accepted 94 of the 95 test cases that are considered "must accept". It signaled an overflow when trying to decode "[123.456e78]".

It accepted 9 out of the 17 test cases considered to be part of the gray area of the JSON specification - you could accept or reject. It actually hung when trying to decode the underflow number [123e-10000000].

See Benchmarking

• %to-json - Write obj as JSON string.
• %write-char - Write character to *stream*.
• %write-string - Write string to *stream*.
• *empty-array-value* - LISP value of [].
• *empty-object-value* - LISP value of {}.
• *false-value* - LISP value of false.
• *from* - Default value of from used by #'to-json.
• *null-value* - LISP value of null.
• *octets* - Default value of octets used by #'to-json.
• <jonathan-error> - Base condition of jonathan-errors.
• <jonathan-incomplete-json-error>
• <jonathan-not-supported-error>
• <jonathan-unexpected-eof-error>
• <jonathan-without-tail-surrogate-error>
• compile-encoder - Compile encoder
• parse - Convert JSON String to LISP object.
• to-json - Convert LISP object to JSON String.
• with-array - Make writing array safe.
• with-object - Make writing object safe.
• with-output - Bind *stream* to stream.
• with-output-to-string - Output *stream* as string.
• write-item - Write item of array.
• write-key - Write key part of object.
• write-key-value - Write key and value of object.
• write-value - Write value part of object.

Json-lib parses utf-8 encoding JSON strings (and not streams). So if you are reading a JSON encoded file, you would need to specify in the input stream conversions that utf-8 be used. E.g.

(json-lib:parse (alexandria:read-file-into-string "file.json"
                                                  :external-format :utf8))

As with many of the libraries, it decodes a JSON 'null' as NIL. It also fails to handle unicode surrogate pairs if you care about that.

According to the README, the json-lib parser uses whitespace presence, regardless of commas, as a delimiting marker.

Json-lib will encode to strings, not streams. Some idiosyncrasies are noted in the following points:

• It encodes keyword symbols, but other symbols get encoded to "null"
  • It encodes a char to "null". You could write a method to handle char
  • Ratios are encoded as "null"
  • Attempting to encode a CLOS object or pathname returned "null".
  • In encoding a hash-table, json-lib will be successful if the hash-table keys are strings or keyword symbols. If the keys are other symbols, the key will be rendered as "null".

From the standpoint of symmetry or round-tripping, going from JSON->CL->JSON, json-lib lost the unicode character in the middle of a string and converted false to null.

Going from CL->JSON->CL, it took an input of alists and converted it to vectors of vectors with keywords symbols being turned into strings. In the second test it took an array input and the only hiccup was converting :NULL to "null".

There were two general security issues we considered: (1) interning keywords and (2) issues with malformed data. json-lib did not exhibit the first issue.

With respect to the second issue, json-lib rejected 110 out of 173 malformed test cases. It was one of four packages which allowed you to limit the depths to which it would dive in nested json objects and, therefore, did not trigger the stack exhaustion exhibited by most of the other packages.

json-lib accepted 95 of the 95 test cases that are considered "must accept". If *read-default-float-format* is set to 'single-float, it would refuse to accept: [123e65], [123e45] and [123.456e78].

It accepted 12 of the 17 test cases considered to be part of the gray area of the JSON specification - you could accept or reject.

See Benchmarking

Json-lib has conversion functions lisp-to-snakecase, snakecase-to-lisp and lisp-to-camelcase. These will only be applied to keyword symbols.

• encode-string
• parse - Given an encoded utf-8 JSON string, returns a cl structure or value. If use-keywords-for-keys is T, then hash table keys will be constructed as keywords. If an object-key-handler lambda/function is provided, this will be called for each object key and the result value used for the specific object key. By default the limit is 1000 for structural depth, but this can be set with the keyword max-depth. Exponent representation in serialized form is limited to a length of 2 to prevent huge values causing slow downs and other issues in the conversion process.
• stringify - Converts the given data structure to a stringified JSON form, suitable for serialization and other uses. An optional function can be passed for case encoding of native lisp keyword structures. If a function for unencodable-items is provided, this function will be called, and should return a JSON compliant string representing the encoded items. If no value is provided for unencodable-items, the JSON null value is used.

This is the default mapping. Do you see a distinct lack of data structures on the CL side? See the discussion under Json-streams Encoding for more info.

(1) This is a cons and not a CLOS object.

Generally speaking json-streams does what you would expect with respect to decoding. As you might expect, given the name, it can handle either stream or string input. However, consider parsing the two following JSON strings. The first is a JSON object which includes a JSON array and the second is just an array::

(json-streams:json-parse "{\"A\":false,\"B\":[false]}")
(:OBJECT ("A") ("B" :ARRAY NIL))

(json-streams:json-parse "[\"B\",false]")
(:ARRAY "B" NIL)

Both of the results are CONS. I do not know what I was expecting, but it probably was not that.

I found json-streams frustrating when it comes to simple, straightforward encoding. You cannot just pass CL data to it and assume that it will work.

• (1) A fell through ETYPECASE expression. Wanted one of ((OR STRING REAL) (MEMBER T NIL) (MEMBER :NULL) JSON-STREAMS:JSON-ARRAY JSON-STREAMS:JSON-OBJECT).

So how do you actually use stringify? Well,

• (1) A fell through ETYPECASE expression. Wanted one of ((OR STRING REAL) (MEMBER T NIL) (MEMBER :NULL) JSON-STREAMS:JSON-ARRAY JSON-STREAMS:JSON-OBJECT).

In case you were wondering, json-stringify json-stringify-multiple and JSON-stringify-single are regular functions. You cannot just write a new method to deal with a new datatype. They take a type json-object, json-array or json-string defined as:

(deftype json-object ()
  '(cons (member :object) t))

From the standpoint of symmetry or round-tripping, going from JSON->CL->JSON, json-streams had no issues.

Going from CL->JSON->CL, it failed (as you might expect) with both the alist input and the vector input because you would need to write a new method for dealing with either one.

There were two general security issues we considered: (1) interning keywords and (2) issues with malformed data. json-streams did not exhibit the first issue.

With respect to the second issue, json-streams rejected all 173 malformed test cases. It was one of four packages which allowed you to limit the depths to which it would dive in nested JSON objects and, therefore, did not trigger the stack exhaustion exhibited by most of the other packages.

Without additional parameters, json-streams accepted 93 of 95 test cases that are considered "must accept". The rejected test cases were files with duplicate keys and those would have been accepted by passing the keyword parameter :duplicate-key-check nil.

It accepted 1 of the 17 test cases considered to be part of the gray area of the JSON specification - you could accept or reject.

See Benchmarking

As mentioned above, there are no doc-strings for json-streams' exported symbols.

• call-with-json-output
• json-array
• json-close
• json-error
• json-input-stream
• json-object
• json-output-alist
• json-output-boolean
• json-output-member
• json-output-null
• json-output-plist
• json-output-stream
• json-output-value
• json-parse
• json-parse-error
• json-parse-multiple
• json-read
• json-stream
• json-stream-position
• json-string
• json-stringify
• json-stringify-multiple
• json-write
• json-write-error
• make-json-input-stream
• make-json-output-stream
• most-negative-json-integer
• most-positive-json-integer
• with-json-array
• with-json-member
• with-json-object
• with-json-output
• with-open-json-stream

Please note the direction of the arrows in the following table.

This is where jsown really shines. Jsown is by far the fastest decoder. It not only decodes, it also makes it easy to pull out elements of the json-object (at least at the first level of the object).

One thing that was interesting was that jsown is the only library to decode JSON floats to CL ratios.

As a minor annoyance, parsing strings that have form feeds get translated to line feeds.

When reading JSON objects, jsown converts their content to the most lispy translation of what was in there. As such, JSON's false will be translated to nil, which coincidentally also be the translation of JSON's []. JSON's null is also translated to nil.

As you can tell from the default mapping table, JSON arrays are decoded to lists and JSON objects decoded to cons cells:

(jsown:parse "[1, \"a\"]")
(1 "a")

(jsown:parse "{\"foo\": \"alpha\", \"bar\":3.2}")
(:OBJ ("foo" . "alpha") ("bar" . 16/5))

(to-json x) is a generic function which you can specialize on your own types. This allows you to nest lisp objects in a jsown object and serialize them in a suitable way.

(to-json* x) is the non-generic function variant of the same thing. It isn't as smart, but it is faster.

Encoding chars, pathnames, CLOS objects, structs and other data structures not listed in the default mapping above will require that you write a new to-json method to handle that particular datatype.

On the plus side, jsown is the one of the two libraries (the other is shasht) which can handle multi-dimensional arrays

When writing to JSON, lisp's nil is translated to the empty JSON list []. You can write JSON's false by writing lisp's keywords :false or :f.

(jsown:to-json (jsown:new-js ("items" nil) ("falseIsEmptyList" :f) ("success" t)))

"{\"items\":[],\"falseIsEmptyList\":false,\"success\":true}"

As you can tell from the default mapping table, lists and vectors are automatically encoded to JSON arrays and hash-tables are encoded to JSON objects. As alists are considered lists of lists, an alist will return an array of arrays. Plists are treated the same as plain lists and will lose their key-value connections.

(jsown:to-json '(("a" "alpha") ("b" "beta")))
"[[\"a\",\"alpha\"],[\"b\",\"beta\"]]"

You can specify that JSON returns an object. The following call to to-json wraps the alist in another list headed by :obj and returns a JSON object.

(jsown:to-json '(:obj (("a" "alpha") ("b" "beta"))))
 "{\"(a alpha)\":[[\"b\",\"beta\"]]}"

If jsown tries to encode an alist which has dotted cons cells, jsown triggered unhandled memory faults with SBCL 2.1.11-x86-64-linux, CCL version 1.12.1 LinuxX8664 and ecl-version 21.2.1. This appears to be because jsown has optimized the code and assumed that all lists will be proper lists. The assumption obviously fails in the context of dotted cons cells.

When to-json is called, jsown will internally call to-json each step of the way. This has a performance downside, yet it seems to provide the least surprises in the output. If you need more performance, jsown* offers that, at the cost of flexibility.

If you are constructing JSON objects, consider using the jsown:new-js and jsown:extend-js functions.jsown:js-new has a clean and clear interface for building content. It works together with jsown:extend-js if you need to split up the object creation.

Jsown has a setf-expander on (setf jsown:val) which automatically creates a jsown-object if no such object was available at the designated place. An example should clarify:

(let (doc)
  (setf (jsown:val (jsown:val (jsown:val doc "properties") "color") "paint") "red")
  (jsown:to-json doc))

"{\"properties\":{\"color\":{\"paint\":\"red\"}}}"

It turns out to be a handy little feature when you need to build deeply nested JSON documents.

From the standpoint of symmetry or round-tripping, going from JSON->CL->JSON, jsown had no issues except for dealing with false and null.

Going from CL->JSON->CL was more problematic. Keyword symbols became strings, :NULL became nil, a float was converted to a ratio and where the input started as an array, it returned a list.

There were two general security issues we considered: (1) interning keywords and (2) issues with malformed data. Jsown did not exhibit the first issue. With respect to the second issue, jsown rejected 102 out of 173 malformed test cases. Unfortunately some of those malformed JSON data strings did trigger the stack exhaustion exhibited by most of the other packages.

jsown accepted 93 of the 95 test cases that are considered "must accept". It failed on lonely numbers (an integer or negative real not within a JSON array or JSON object).

It accepted 9 of the 17 test cases considered to be part of the gray area of the JSON specification - you could accept or reject.

See Benchmarking

Issue 27 on GitHub claims an unhandled memory fault on the following bad JSON string in SBCL 2.0.8, but I do not see that with CCL, clisp or SBCL 2.1.11, so this issue may have been fixed.

(jsown:parse "{\"foo\": a}")

• *parsed-empty-list-value* - value to emit when parsing a JSON empty list '[]'
• *parsed-false-value* - value to emit when parsing JSON's 'false'
• *parsed-null-value* - value to emit when parsing JSON's 'null'
• *parsed-true-value* - value to emit when parsing JSON's 'true'
• as-js-bool - returns <value> as a boolean value (in jsown format)
• as-js-null - returns <value> with nil being javascript's null (in jsown format).
• build-key-container - Builds an internal structure to speed up the keywords which you can read. This should be used when the keywords needed are not known at compiletime, but you still want to parse those keywords of a lot of documents.
• do-json-keys - Macro - Iterates over the JSON key-value pairs
• empty-object - Returns an empty object which can be used to build new objects upon
• extend-js - Macro - fills in a bunch of jsown values for obj. each spec should contain a list with the first element being the string which represents the key and the second being the form which evaluates to the value to which the key should be set
• filter - Fancy filtering for jsown-parsed objects. spec can be one of the following:
  • [object] key to find. will transform into (jsown:val value key)
  • [cl:map] use this modifier with an [object] modifier after it, to filter all elements in the list.
• json-encoded-content - escribes a JSON object whos content is serialized already
• keyp - Returns non-nil iff <object> has key <key>
• keywords - Returns a list of all the keywords contained in the object
• new-js - Macro - creates a new empty object and fills it is per jsown-values
• parse - Reads a JSON object from the given string, with the given keywords being the keywords which are fetched from the object. All parse functions assume <string> is not an empty JSON object. (string/= string \"{}\")
• parse-with-container - Parses the keywords which have been specified in the container from the JSON string json-string. For most cases you can just use the parse function without a special key container. This is only here to support some cases where the building of the key container takes too much time. See #'parse for the normal variant. See #'build-key-container for a way to build new keyword containers.
• remkey - Removes key from object
• to-json - Writes the given object to JSON in a generic way.
• to-json* - Converts an object in internal jsown representation to a string containing the JSON representation
• val - Returns the value of the given key in object
• val-safe - Returns the value of <key> in <object> if <object> existed, or nil if it did not. A second value is returned which indicates whether or not the key was found.
• with-injective-reader - Rebinds *parsed--value so that reading JSON documents is injective and converting them back to JSON yields roughly the same document as the original. Rebinds: *parsed-true-value* => :true, *parsed-false-value* => :false, *parsed-null-value* => :null

Please note the direction of the arrows in the following table.

The following subsections are from the README:

To quote from the README: The primary interface to parsing and reading JSON is the read-json function.

(read-json &optional input-stream-or-string (eof-error-p t) eof-value single-value-p)

The argument input-stream-or-string can be an stream, a string to read from, or nil to use *standard-input*. The arguments eof-error-p and eof-value have the same affect as they do in the CL function read. If the single-value-p argument is true then the input to read-json is assumed to be a single value, which means that extra tokens at the end will cause an error to be generated.

There are a number of dynamic variables that will influence the parsing of JSON data.

• common-lisp:*read-default-float-format* — Controls the floating-point format that is to be used when reading a floating-point number.
• *read-default-true-value* — The default value to return when reading a true token. Initially set to t.
• *read-default-false-value* — The default value to return when reading a false token. Initially set to nil.
• *read-default-null-value* — The default value to return when reading a null token. Initially set to :null.
• *read-default-array-format* — The default format to use when reading an array. Current supported formats are :vector or :list. Initially set to :vector.
• *read-default-object-format* — The default format to use when reading an object. Current supported formats are :hash-table, :alist or :plist. Initially set to :hash-table.

There is also a keyword variant read-json* which will set the various dynamic variables from supplied keywords.

(read-json* :stream nil
            :eof-error t
            :eof-value nil
            :single-value nil
            :true-value t
            :false-value nil
            :null-value :null
            :array-format :vector
            :object-format :hash-table
            :float-format 'single-float)

The primary interface to serializing and writing JSON is the write-json function.

(write-json value &optional (output-stream t))

On the plus side, shasht was one of two libraries which could encode a pathname or a struct. It also is one of the few libraries that can encode CLOS objects out of the box:

(shasht:write-json (make-instance 'person))
{
  "NAME": "Sabra",
  "EYE-COLOUR": "brown"
}

Local-time:timestamps were encoded as {"DAY": 7990, "SEC": 0, "NSEC": 0}, so if you wanted them to be in any particular javascript time representation, you would have to write a specialized method.

As you might expect, plists are treated the same as plain lists and will lose their key-value connections. If you want to use plists, you will need to convert to a hash table first.

There are a number of dynamic variables that will influence the serialization of JSON data.

• common-lisp:*print-pretty* — If true then a simple indentation algorithm will be used.
• *write-indent-string* — The string to use when indenting objects and arrays. Initially set to #\space.
• *write-ascii-encoding* — If true then any non ASCII values will be encoded using Unicode escape sequences. Initially set to nil.
• *write-true-values* — Values that will be written as a true token. Initially set to '(t :true).
• *write-false-values* — Values that will be written as a false token. Initially set to '(nil :false).
• *write-null-values* — Values that will be written as a null token. Initially set to (:null).
• *write-alist-as-object* — If true then undotted assocation lists will be written as an object. Initially set to nil.
• *write-plist-as-object* — If true then property lists will be written as an object. Initially set to nil.

Consider the following:

(setf common-lisp:*print-pretty* nil)
(shasht:write-json '(("foo" . "bar") ("baz" . ((1 2 3) (4 5 6)))))
[["foo"; Evaluation aborted on #<TYPE-ERROR expected-type: LIST datum: "bar">.

Now if we set shasht:*write-alist-as-object* t,

(setf common-lisp:*print-pretty* nil)
(setf shasht:*write-alist-as-object* t)
(shasht:write-json '(("foo" . "bar") ("baz" . ((1 2 3) (4 5 6)))))

{"foo":"bar","baz":{1:[2,3],4:[5,6]}}

The actual serialization of JSON data is done by the generic function print-json-value which can be specialized for additional value types.

(print-json-value value output-stream)

There is also a keyword variant write-json* which will set the various dynamic variables from supplied keywords.

(write-json* value :stream t
                   :ascii-encoding nil
                   :true-values '(t :true)
                   :false-values '(nil :false)
                   :null-values '(:null)
                   :empty-array-values '(:empty-array)
                   :empty-object-values '(:empty-object)
                   :alist-as-object nil
                   :plist-as-object nil
                   :pretty nil
                   :indent-string "  ")

In order to facilitate extending the serialization facilities of shasht there are a number of helper functions available. To aid in the printing of JSON strings there is the following.

(write-json-string value output-stream)

In order to ease the serialization of objects and arrays there is with-json-object and with-json-array. Both of these macros take an output stream as the first argument then enable indentation and automatic handling of all delimiter tokens. Inside the body of with-json-object the function (print-json-key-value key value output-stream) should be used to output a key value pair. Inside the body of with-json-array the function (print-json-value value output-stream) should be used to output a single value. Example usage can be seen in the source code.