YASON is a Common Lisp library for encoding and decoding data in the JSON interchange format. JSON is used in AJAX applications as a lightweight alternative to XML. YASON has the sole purpose of encoding and decoding data and does not impose any object model on the Common Lisp application that uses it.


The current documentation lives at Github.

Mapping between JSON and CL datatypes

By default, YASON performs the following mappings between JSON and CL datatypes:

object hash-table
:test #'equal
Keys are strings by default, see *parse-object-key-fn*
array list Can be changed to read to vectors, see *parse-json-arrays-as-vectors*
string string JSON escape characters are recognized upon reading. Upon writing, known escape characters are used, but non-ASCII Unicode characters are written as is.
number number Parsed with READ, printed with PRINC. This is not a faithful implementation of the specification.
true t Can be changed to read as TRUE, see *parse-json-booleans-as-symbols*
false nil Can be changed to read as FALSE, see *parse-json-booleans-as-symbols*
null nil

Parsing JSON data

JSON data is always completely parsed into an equivalent in-memory representation. Upon reading, some translations are performed by default to make it easier for the Common Lisp program to work with the data; see mapping for details. If desired, the parser can be configured to preserve the full semantics of the JSON data read.

Encoding JSON data

YASON provides for two distinct modes to encode JSON data: Applications can either create an in memory representation of the data to be serialized, then have YASON convert it to JSON in one go, or they can use a set of macros to serialze the JSON data element-by-element, thereby having fine grained control over the layout of the generated data.