CL-JSON

Q&A

What does CL-JSON do?

CL-JSON provides an encoder of Lisp objects to JSON format and a corresponding decoder of JSON data to Lisp objects. Both the encoder and the decoder are highly customizable; at the same time, the default settings ensure a very simple mode of operation, similar to that provided by YASON or ST-JSON. CL-JSON is well tested and the automated testcases includes the JSON_checker tests.

What is JSON?

JSON is a language independent text format for data-interchange. It has very good open-source and commercial support in many languages. JSON is especially convenient in web applications, since it is a subset of the literal object notation of ECMAScript. A technique called JSONP can be used to do cross-domain Ajax.

Why not use XML instead?

Some find JSON lighter and more simple, see this comparison.

Why not use s-expressions instead?

• Many people find parentheses difficult, but brackets and braces easy. That has led to many implementations of JSON. There is no format based on s-expressions implemented in over 20 languages (yet!).

• A simple and very fast JSON parser in JavaScript looks like this:

  eval('(' + aJSONText + ')')

  Even a seasoned lisper may find it difficult to make a shorter JavaScript parser for s-expressions.

How do I download CL-JSON?

A Darcs repository is available.

darcs get http://common-lisp.net/project/cl-json/darcs/cl-json

The latest release can be downloaded here.

You can also install it by asdf-install.

History has shown that the darcs version is probably better than the latest release.

History

• 2006 First version by Henrik Hjelte.
• 2007-2008 Stable version 0.3.1, no known bugs.
• 2009 Major update by Boris Smilga, adding lots of features. Version 0.4.0

Status

No know bugs.

A bit faster decoder performance in 0.3 version, a darcs repo is available (old version).

User Guide

The default encoder / decoder

The basic functionality is provided by the two functions encode-json and decode-json (all Lisp names in this Manual are available in the package JSON). Under the default semantics they implement the following mapping between Lisp and JSON values:

If stream is omitted it defaults to *json-output* for the encoder, *json-input* for the decoder. The initial values of these variables are synonym streams to *standard-output* and *standard-input* respectively.

(json:encode-json
  '#( ((foo . (1 2 3)) (bar . t) (baz . #\!))
      "quux" 4/17 4.25))

[{"foo":[1,2,3],"bar":true,"baz":"!"},"quux",0.23529412,4.25]

NIL

Some parameters which influence the encoding and decoding of symbols are:

(with-input-from-string
    (s "{\"foo\": [1, 2, 3], \"bar\": true, \"baz\": \"!\"}")
  (json:decode-json s))

((:FOO 1 2 3) (:BAR . T) (:BAZ . "!"))

(with-input-from-string
    (s "{\"foo\": [1, 2, 3], \"bar\": true, \"baz\": \"!\"}")
  (let ((json:*json-symbols-package* 'json-test))
    (json:decode-json s)))    

((JSON-TEST::FOO 1 2 3) (JSON-TEST::BAR . T) (JSON-TEST::BAZ . "!"))

(with-input-from-string
    (s "{\"foo\": [1, 2, 3], \"bar\": true, \"baz\": \"!\"}")
  (let ((json:*json-symbols-package* nil))
    (json:decode-json s)))

((FOO 1 2 3) (BAR . T) (BAZ . "!"))

The last two variables are initially bound to #'camel-case-to-lisp and #'lisp-to-camel-case, respectively. For a description of these functions, see Camel case translation below.

Note also that the format of Lisp floats decoded from JSON input is controlled by the system variable *read-default-float-format* in the same manner as for the Lisp reader. (But cf. Error handling.)

CL-JSON also provides the following shortcut functions:

The CLOS decoder

It is possible to switch CL-JSON into a mode where Arrays are decoded to Lisp vectors rather than lists, and Objects are decoded to CLOS objects in the manner described below. Switching between this mode (“CLOS semantics”) and the default “list semantics” is done using the following functions:

[function] set-decoder-simple-clos-semantics

[function] set-decoder-simple-list-semantics

Either semantics can be made to hold temporarily in a dynamic environment while body is being executed:

[macro] with-decoder-simple-clos-semantics &body body

[macro] with-decoder-simple-list-semantics &body body

As a general rule, under the CLOS semantics a JSON Object datum D is decoded to an instance F of an anonymous class K. Such a class does not have a name which could be used as a method specializer, however, the user can always assume that K is a subclass of fluid-object and an instance of the metaclass fluid-class; that it has at least the slots named by the keys in D (which are decoded to symbols in the usual manner); and that in F these slots are bound to Lisp images of the corresponding JSON Values, and any other slot is unbound:

(json:with-decoder-simple-clos-semantics
  (let ((json:*json-symbols-package* nil))
    (let ((x (json:decode-json-from-string
               "{\"foo\": [1, 2, 3], \"bar\": true,
                 \"baz\": \"!\"}")))
      (with-slots (foo bar baz) x
        (values x foo bar baz)))))

#<AN INSTANCE OF ANONYMOUS FLUID-CLASS>

#(1 2 3)

T

"!"

Beyond this, CL-JSON provides a means for the remote party to specify the class (or the superclasses) of the decoded CLOS object. This is done by supplying the JSON Object with appropriate metadata, called that Object's prototype. The prototype is the Member of the Object whose key matches *prototype-name*—more precisely, whose key decodes to a symbol S such that (string= (symbol-name S) (symbol-name json:*prototype-name*)).

Note: The default prototype name, prototype has been chosen so that it would not, in all likelihood, interfere with programs' naming schemes in a JavaScript remote party. As this name has special meaning within JavaScript, it is unlikely that it would be used for a user-level member. Users of CL-JSON are, of course, free to assign another name that better suits their own needs.

The Value of the prototype must be either a String, or an Object whose (undecoded) keys include "lispPackage", "lispClass", and "lispSuperclasses". All Members with other keys are ignored. The Value for any of "lispPackage", "lispClass", and "lispSuperclasses" may be null which is equivalent to omitting that Member. A prototype S which is a String (rather than an Object) is equivalent to a prototype that has only the Member "lispClass":S. An Object altogether lacking a prototype is equivalent to it having a prototype with all the three meaningful members omitted. With the foregoing exceptions, the Values for "lispPackage" and "lispClass" should be Strings, and the Value for "lispSuperclasses" an Array of Strings.

The Value for "lispPackage" is decoded as symbol and passed to find-package to obtain a package, P. The Value for "lispClass", Members of the Value for "lispSuperclasses", and the keys of the encompassing Object are then decoded as symbols in the package P. (If "lispPackage" is null or missing, they are interned according to the generic rule, i. e. in *json-symbols-package*.)

If the prototype has a "lispClass" member, its decoded value must name an existing class K. The encompassing Object, D, is then decoded to an instance of K. The Values of all Members of D whose keys, when decoded, yield names of slots in K are assigned to those slots. All other Members are discarded. Also, if K has a slot whose name is the same as *prototype-name* that slot shall be bound to an instance of prototype which describes the prototype in the JSON Object.

(in-package cl-user)

#<PACKAGE "COMMON-LISP-USER">

(defclass sample () (foo bar))

#<STANDARD-CLASS SAMPLE>

(json:with-decoder-simple-clos-semantics
  (let ((x (json:decode-json-from-string
            "{\"foo\": [1, 2, 3], \"bar\": true, \"baz\": \"!\",
              \"prototype\": {\"lispPackage\": \"clUser\",
                              \"lispClass\": \"sample\"}}")))
      (with-slots (foo bar) x
        (values x (class-of x) foo bar (slot-exists-p x 'baz)))))

#<A SAMPLE>

#<STANDARD-CLASS SAMPLE>

#(1 2 3)

T

NIL

By way of exception, if the decoded value for "lispClass" is common-lisp:hash-table, common-lisp:cons, or common-lisp:list then the encompassing Object shall be decoded, respectively, to a hash table, an association list, or a property list with the keys and values decoded from the keys and values of the encompassing Object. (The prototype member itself shall be discarded.)

(let ((json:*json-symbols-package* 'cl-user))
 (json:with-decoder-simple-clos-semantics
   (let ((x (json:decode-json-from-string
             "{\"foo\": [1, 2, 3], \"bar\": true, \"baz\": \"!\",
               \"prototype\": \"hashTable\"}")))
     (loop for v being each hash-value of x
       collect v))))

("!" #(1 2 3) T) ; or in another order

(json:with-decoder-simple-clos-semantics
  (json:decode-json-from-string
    "{\"foo\": [1, 2, 3], \"bar\": true, \"baz\": \"!\",
      \"prototype\": {\"lispPackage\": \"jsonTest\",
                      \"lispClass\": \"list\"}}"))

(JSON-TEST::FOO #(1 2 3) JSON-TEST::BAR T JSON-TEST::BAZ "!")

If the prototype has no "lispClass" but has "lispSuperclasses", the Value of the latter is decoded as a list of symbols which must name existing classes L₁, ... L_n, n ≥ 0. The encompassing Object, D, is then decoded to a fluid object F whose class K has all the classes L₁, ... L_n as its direct superclasses. Unless any of the classes L₁, ... L_n is a subclass of fluid-object, K shall be additionally a direct subclass of fluid-object. Slots corresponding to all Members of D (except the prototype itself) shall be bound in F.

(defclass sample-2 ()
  ((frob :initform 'xyzzy)))

#<STANDARD-CLASS SAMPLE-2>

(json:with-decoder-simple-clos-semantics
  (let ((json:*json-symbols-package* nil))
    (let ((x (json:decode-json-from-string
               "{\"foo\": [1, 2, 3], \"bar\": true, \"baz\": \"!\",
                 \"prototype\":
                    {\"lispSuperclasses\": [\"sample2\"]}}")))
      (with-slots (foo frob) x
        (values x foo frob)))))

#<AN INSTANCE OF ANONYMOUS FLUID-CLASS>

#(1 2 3)

XYZZY

If the prototype has both "lispClass" and "lispSuperclasses", the latter member is disregarded.

[standard class] prototype (precedence list: prototype, standard-object, t)

Properties of fluid objects

Fluid objects are quite like standard objects in most respects. However, any fluid object has fluid-class as its metaclass, and missing slots in such fluid instances are not distinguished from unbound slots. Namely, if F is a fluid instance of class K, and R is a slot name such that (slot-exists-p F R) gives nil then:

• (slot-boundp F R) gives nil as well (instead of raising an error);
• (slot-value F R) signals an error of type unbound-slot;
• (slot-makunbound F R) does nothing and returns F;
• for any Lisp value X, (setf (slot-value F R) X) adds the slot R to the class K and then sets its value in F to X.

[standard class] fluid-object (precedence list: fluid-object, standard-object, t)

[standard class] fluid-class (precedence list: fluid-class, standard-class, class, standard-object, t)

The CLOS decoder maintains a separate fluid class for each combination of superclasses in prototypes sent in by remote parties. I. e., if the prototypes of two incoming JSON Objects D₁ and D₂ have "lispSuperclasses" members whose values decode to non-equal lists of symbols then the fluid objects F₁ and F₂ decoded from D₁ and D₂ shall belong to different fluid classes. This behaviour is implemented by the generic function make-object.

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.

Security considerations

Make-object also allows to implement security restrictions in an environment where uncontrolled class instantiation may have undesirable side effects. Ordinarily, nothing prevents the CLOS decoder from processing an incoming datum like

{"prototype": {"lispPackage": "worldDestruction",
               "lispClass": "tickingBomb"},
 "timeout": 10,
 "setOffImmediatelyOnInstantiation": true}

If a careless and/or malevolent remote party manages to sneak in such a request the calamitous results will not be late in coming. However, as the decoding of every input Object eventually involves a call to make-object, a safeguard may take the form simply of a method of that generic function:

(define-condition json-security-violation (error)
  ((bindings :reader json-security-violation-bindings :initarg :bindings)
   (class :reader json-security-violation-class :initarg :class))
  (:report
   (lambda (sv stream)
     (with-slots (bindings class) sv
       (format stream "Incoming JSON Object ~S in the class ~S ~
                       violates security restrictions."
               (json:encode-json-to-string bindings)
               class)))))

JSON-SECURITY-VIOLATION

(defmethod json:make-object :before
    (bindings (class (eql world-destruction:ticking-bomb))
     &optional superclasses)
  (error 'json-security-violation :bindings bindings :class class))

#<STANDARD-METHOD JSON:MAKE-OBJECT …
        :BEFORE (T (EQL WORLD-DESTRUCTION:TICKING-BOMB))>

(json:with-decoder-simple-clos-semantics 
  (json:decode-json-from-string
    "{\"prototype\": {\"lispPackage\": \"worldDestruction\",
                      \"lispClass\": \"tickingBomb\"},
      \"timeout\": 10,
      \"setOffImmediatelyOnInstantiation\": true}"))

Error in JSON:MAKE-OBJECT: Incoming JSON Object …
        "{\"timeout\":10,\"setOffImmediatelyOnInstantiation\":true}" …
        in the class WORLD-DESTRUCTION:TICKING-BOMB …
        violates security restrictions.

By using multiple methods with carefully adjusted specializers and qualifiers the user shall be able to create arbitrarily sophisticated security policies.

Customizing the decoder

More arbitrary changes to decoder semantics can be made via the customization API. It is an event-driven API not unlike SAX: certain variables can be set (or dynamically bound) to handler functions which are invoked, in sequence, as the parser encounters various syntactic elements of JSON on the input stream. JSON well-formedness is checked by the underlying parser, while the handlers are free to dispose of the (known clean) data in any way the user may find fit.

Handlers fall into three overall categories: constructors, which can be further subdivided into atomic constructors and aggregate constructors; aggregate initializers; and member handlers. An atomic constructor is invoked when the parser encounters an atomic datum (Number or Boolean), is passed the token which constitutes the datum, and is supposed to return the Lisp value that corresponds to the datum. An aggregate initializer is invoked when the parser encounters the beginning of an aggregate datum (String, Array or Object). Similarly, an aggregate constructor is invoked at the end of a well-formed aggregate datum, and is supposed to return the Lisp value that corresponds to the whole aggregate. A member handler is invoked when the parser reads past a member of an Array, or a key or value of an Object; it is passed the value which the constructor for that member datum had freshly returned. Handlers for Characters of Strings are somewhat specific in that they are passed characters rather than decoded values but otherwise they fall neatly with member handlers. The value of the last constructor to return is also the return value of decode-json.

As a trivial example, if every handler has the value of (constantly t), the decoder semantics is that of a simple validator: it returns t if JSON input is well-formed, and signals error otherwise (see also under Error handling).

Macros which set or bind handlers (and other customization parameters) take their arguments in the form of property lists where each customizaion parameter is indicated by its distinctive keyword. E. g., :integer and :boolean are the respective indicator keywords for the variables *integer-handler* and *boolean-handler*. Accordingly, the macro form (json:bind-custom-vars (:boolean X :integer Y) Z) expands to (let ((json:*boolean-handler* X) (json:*integer-handler* Y)) Z). Descriptions of customization parameters below always specify the corresponding keyword, and descriptions of macro APIs use the parameter name customizations whereever a property list is expected.

The following parameters identify the constructor handlers for atomic data:

For Strings, three handlers (an initializer, a member handler, and a constructor) are used:

Note that escape sequences in Strings are resolved by the underlying decoder, and a *string-char-handler* normally receives nothing but characters. However, limitations of the Lisp implementation running CL-JSON can prevent it from resolving a perfectly well-formed escape sequence (e. g., in CMUCL which does not support Unicode). Situations of this kind are discussed below in the section Error handling.

For Arrays, three handlers are used as well:

For Objects, it is the same thing except that there are two member handlers, one for keys and another one for values, invoked alternately:

If the user wished to map JSON structure to Lisp structure, with only these 13 handlers he would have to maintain cumbersome stacking infrastructure, pushing at the beginning and popping at the end of every aggregate datum. CL-JSON has a means to circumvent this hindrance: the user is given an option to indicate any number of dynamic variables V₁, ... V_n as having aggregate scope. This has the effect that the ensemble of handlers invoked for any particular aggregate datum on the input are called in a dynamic environment where the names V₁, ... V_n are bound to fresh locations. Hence, an aggregate-scope variable can be initialized by an initializer handler, updated by member handlers, and finally used to calculate the return value of the constructor. If several aggregate data are nested, the handlers for interior data work on their own copy of the variable without fear of clobbering the value of the same for exterior data. Handler code can be thus written in terms of individual levels rather than complex nested structures.

Aggregate-scope variables on inner levels initially inherit their values from the immediately outer level, so it is possible to pass information down from level to level. In the following example, the variable count is reset to 0 at the beginning of every aggregate, while level is incremented from outer to inner levels.

(defparameter level -1
  "Level of nesting in JSON structure.")

LEVEL

(defparameter count -1
  "Count of members in JSON structure.")

COUNT

(defun format-with-indent (control &rest args)
  (format t "~&~0,1,V,V@A~?" level #\Tab "" control args))

FORMAT-WITH-INDENT

(defun report-atom (token)
  (format-with-indent "~Ctoken: ~S~%" #\Tab token)
  'atom)

REPORT-ATOM

(defun report-push ()
  (incf level)
  (setq count 0)
  (format-with-indent "beginning of aggregate~%"))

REPORT-PUSH

(defun report-member (member)
  (format-with-indent "~:R member: ~A~%"
                      (incf count) member))

REPORT-MEMBER

(defun report-pop ()
  (format-with-indent "end of aggregate~%")
  (list 'aggregate count))

REPORT-POP

(json:bind-custom-vars
    (:integer              #'report-atom
     :real                 #'report-atom
     :boolean              #'report-atom
     :beginning-of-array   #'report-push
     :array-member         #'report-member
     :end-of-array         #'report-pop
     :beginning-of-string  #'report-push
     :string-char          #'report-atom
     :end-of-string        #'report-pop
     :beginning-of-object  #'report-push
     :object-key           (constantly t)
     :object-value         #'report-member
     :end-of-object        #'report-pop
     :aggregate-scope      (list 'level 'count))
  (json:decode-json-from-string
    "{\"foo\": [10, 20, 50], \"bar\": true}"))

beginning of aggregate

	beginning of aggregate

		token: #\f

		token: #\o

		token: #\o

	end of aggregate

	beginning of aggregate

		token: "10"

	first member: ATOM

		token: "20"

	second member: ATOM

		token: "50"

	third member: ATOM

	end of aggregate

first member: (AGGREGATE 3)

	beginning of aggregate

		token: #\b

		token: #\a

		token: #\r

	end of aggregate

	token: "true"

second member: ATOM

end of aggregate

(AGGREGATE 2)

Further, it is possible to re-bind variables while parsing some kinds of aggregate data but not the others:

When using one of the standard semantics, the following parameter allows to determine the type of sequence to which Arrays are decoded. The default value is list for the list semantics, and vector for the CLOS semantics.

Finally, the user can change the decoder function for member data of the current aggregate. The name *internal-decoder* is included in the default list of *aggregate-scope-variables* under both predefined semantics, and so this variable can be assigned locally without affecting the decoding of the outer levels of data. If it is set outside of any handler, the value is used to decode all members of top-level aggregates.

The following macros can be used to construct decoder functions acceptable as values of *internal-decoder*:

The following example demonstrates how a simplified version of the macro json-bind can be written with the help of *internal-decoder*.

(defmacro simple-json-bind ((&rest vars) stream &body body)
  (let ((cur-dec (gensym))
        (key-handler
         `(lambda (json-string)
            (let ((lisp-string
                   (funcall json:*json-identifier-name-to-lisp*
                            json-string)))
              ;; On recognizing a variable name, the key handler sets
              ;; the value handler to be a function which,
              ;; in its turn, assigns the decoded value to the
              ;; corresponding variable.  If no variable name matches
              ;; the key, the value handler is set to skip the value.
              (json:set-custom-vars
                  :object-value
                    (cond
                      ,@(loop for var in vars
                          collect
                           `((string= lisp-string ,(symbol-name var))
                             (lambda (value)
                               (setq ,var value))))
                      (t (constantly t))))))))
    `(let ((,cur-dec (json:current-decoder))
           ,@vars)
       (json:bind-custom-vars
           (:internal-decoder ,cur-dec
            :beginning-of-object (constantly t)
            :object-key ,key-handler
            :end-of-object (constantly t))
         (json:decode-json ,stream))
       ,@body)))

SIMPLE-JSON-BIND

(pprint
 (macroexpand-1
  '(simple-json-bind (foo bar) s
     (format t "Foo is ~A.~%Bar is ~A.~%" foo bar))))

(LET ((#:G762 (JSON:CURRENT-DECODER))

      FOO BAR)

  (JSON:BIND-CUSTOM-VARS

      (:INTERNAL-DECODER #:G762

       :BEGINNING-OF-OBJECT (CONSTANTLY T)

       :OBJECT-KEY

         (LAMBDA (JSON-STRING)

           (LET ((LISP-STRING

                  (FUNCALL JSON:*JSON-IDENTIFIER-NAME-TO-LISP*

                           JSON-STRING)))

             (JSON:SET-CUSTOM-VARS

                 :OBJECT-VALUE

                   (COND ((STRING= LISP-STRING "FOO")

                          (LAMBDA (VALUE) (SETQ FOO VALUE)))

                         ((STRING= LISP-STRING "BAR")

                          (LAMBDA (VALUE) (SETQ BAR VALUE)))

                         (T (CONSTANTLY T))))))

       :END-OF-OBJECT (CONSTANTLY T))

    (JSON:DECODE-JSON S))

  (FORMAT T "Foo is ~A.~%Bar is ~A.~%" FOO BAR))

(json:with-decoder-simple-list-semantics
  (with-input-from-string
      (s "{\"foo\": [1, 2, 3], \"baz\": {\"foo\": \"!\"},
           \"bar\": true}")
    (simple-json-bind (foo bar) s
      (format t "Foo is ~A.~%Bar is ~A.~%" foo bar))))

Foo is (1 2 3).

Bar is T.

NIL

Customizing the encoder

Encoding being much more user-driven than decoding, the customization API for the encoder boils down to just a few macros and functions, geared to generating aggregate data. They implement a sequential producer which emits JSON data upon user request, rather than in the course of traversing Lisp data structures. As with encode-json, the optional stream argument in these macros and functions defaults to *json-output*.

(defpackage foo (:use) (:export #:foo #:bar #:baz))

#<PACKAGE "FOO">

(defvar foo:foo '(1 2 3))

FOO:FOO

(defvar foo:bar "!")

FOO:BAR

(defun foo:bar ()
  foo:bar)

FOO:BAR

(json:with-array ()
  (json:as-array-member ()
    (json:with-object ()
      (do-external-symbols (sym (find-package "FOO"))
        (json:as-object-member (sym)
          (json:with-object ()
            (if (boundp sym)
                (let ((value (symbol-value sym)))
                  (json:encode-object-member 'val value)))
            (if (fboundp sym)
                (json:encode-object-member 'fun t))))))))

[{"bar":{"val":"!","fun":true},"baz":{},"foo":{"val":[1,2,3]}}]

NIL

Camel case translation

The aim of the functions described in this section is to provide a reasonable mapping between identifier naming conventions—from JavaScript to Lisp and back again. Names are regarded as consisting of pieces that, in Lisp, are always uppercase and joined with hyphens, and in JavaScript (and other C-like languages), either joined with underscores or capitalized and joined solid. Plus signs are used in Lisp to mark constants, which corresponds to the all-caps convention in C-like languages.

[function] camel-case-to-lisp string

[function] lisp-to-camel-case string

The functions are not strictly inverse. While (lisp-to-camel-case (camel-case-to-lisp S)) is string= to S for every S which is a valid JavaScript identifier name, (camel-case-to-lisp (lisp-to-camel-case R)) is not guaranteed to preserve R even if R is a valid Lisp identifier name. The use of camel-case-to-lisp and lisp-to-camel-case is best explained by some examples:

(json:lisp-to-camel-case "HELLO-KEY")

"helloKey"

(json:camel-case-to-lisp "HiStartsWithUpperCase")

"*HI-STARTS-WITH-UPPER-CASE"

(json:camel-case-to-lisp "joined_by_underscore")

"JOINED--BY--UNDERSCORE"

(json:camel-case-to-lisp "JSONAllCapitals")

"+JSON+-ALL-CAPITALS"

(json:lisp-to-camel-case "+TWO-WORDS+")

"TWO_WORDS"

(json:camel-case-to-lisp "camelCase_Mixed_4_PARTS")

"CAMEL-CASE--*MIXED--+4-PARTS+"

Error handling

The standard encoder does not cover the complete set of Lisp data types: structures, functions, complex numbers, and cons pairs which are not lists and not members of a valid alist are only some of the unencodable data types. Attempting to encode any such data results in an error.

Whenever an unencodable-value-error is signalled, CL-JSON provides a restart called substitute-printed-representation which, if invoked, prints a representation of the offending datum to a string (with *print-escape* bound to nil) and encodes that string instead of the datum.

(defstruct frob xyzzy)

FROB

(handler-bind
    ((json:unencodable-value-error
      (lambda (err)
        (declare (ignore err))
        (invoke-restart 'json:substitute-printed-representation))))
  (json:encode-json
    '(#S(frob) ((foo . #C(1 1)) (bar . (baz . quux))))))

["#S(FROB :XYZZY NIL)",{"foo":"#C(1 1)","bar":"(BAZ . QUUX)"}]

NIL

The encoder also signals an error if any macro or function for encoding Members of aggregates (such as as-object-member) is called outside of dynamic environment established by with-array or with-object, or in inappropriate environment.

More numerous are situations in which an error is caused by input to the decoder. The most straightforward case is when data sent in by the remote party is not well-formed JSON. This results in a json-syntax-error being signalled. (Some syntax errors, e. g. missing right brackets, result in end-of-file instead.)

[condition] json-syntax-error (precedence list: json-syntax-error, simple-error, simple-condition, stream-error, error, serious-condition, condition, t)

However, even well-formed JSON is not guaranteed to decode. Two common kinds of error situations result from implementation restrictions on character codes and on floating-point reals. If the decoder encounters in a JSON string an escape sequence \uXXXX where XXXX is the hexadecimal presentation of a number N which either exceeds the implementation's char-code-limit or for which code-char returns nil, then the following condition is signalled:

[condition] no-char-for-code (precedence list: no-char-for-code, error, serious-condition, condition, t)

In this situation a handler for no-char-for-code may invoke the following restarts:

substitute-char char

Continue the execution as if the given char, rather than the escaped char, had been read.

pass-code

Continue the execution using the code itself in place of the character. The code is subsequently passed to the *string-char-handler*, so using this restart only has sense if the handler groks character codes (the standard handler doesn't).

Likewise, the underlying Lisp system can fail to handle floats which are not representable in the current *read-default-float-format* (e. g. 2.065e444 is non-representable even in the long-float format in most contemporary Lisps). If such a datum is encountered in JSON input, an arithmetic-error is signalled. CL-JSON provides three restarts to correct such cases:

bignumber-string &optional prefix

Instead of number, use a string which is the concatenation of prefix and the number token that caused the error. The default value for prefix is "BIGNUMBER:".

rational-approximation

Parse the number token into parts, read them as integers, and combine the integers using only rational operations. Use the resulting rational number in place of float. (E. g., 2.065e444 would be converted to the value of the expression (* (+ 2 (* 65 (expt 10 -3))) (expt 10 444)).)

placeholder value

Use value in place of the float. E. g., one might wish to use :infinity if the error in question is a float-overflow.

The CLOS decoder can run into errors due to invalid data in a prototype:

• If a prototype is neither an Object nor a String, or if a Member of a prototype Object does not have the correct type of Value (null or String for "lispPackage" and "lispClass", null or Array of Strings for "lispSuperclasses"), a type-error is signalled.
• If a prototype specifies a non-null package name which does not name a registered package, a package-error is signalled.
• If a prototype specifies a non-null class name or a Member of the superclasses Array which does not name an existing class, a cell-error is signalled.

Utilities

JSON-Bind

By “object hierarchy”, we understand a tree of nested JSON Objects (without intervening Arrays). Structured keys are symbols whose names consist of parts separated by periods and serve as paths into this tree. In an Object D, one-part name S (without any periods) refers to the Value E whose corresponding key R is such that (string= (funcall *json-identifier-to-lisp* R) S). If E is also an Object, the path S.T refers to the same sub-datum within D which T refers to within E. If any part of the structured name fails to match a member key at its level of object nesting, or if any non-final part of the structured name refers to a non-Object, then that variable shall be bound to nil in the scope of json-bind.

(let ((dentition
       "{\"DugongDugon\":
          {\"upper\":
            {\"incisors\":2, \"canines\":0,
             \"premolars\":3, \"molars\":3},
           \"lower\":
            {\"incisors\":3, \"canines\":1,
             \"premolars\":3, \"molars\":3}},
         \"Notoryctes\":
          {\"upper\":
            {\"incisors\":4, \"canines\":1,
             \"premolars\":2, \"molars\":4},
           \"lower\":
            {\"incisors\":3, \"canines\":1,
             \"premolars\":3, \"molars\":4}},
         \"DasypusHybridus\":
          {\"upper\":6, \"lower\":8}}"))
  (json:with-decoder-simple-list-semantics
    (json:json-bind (*notoryctes.lower.incisors
                     *dugong-dugon.lower.incisors
                     *notoryctes.lower
                     *dasypus-hybridus)
        dentition
      (flet ((count-teeth (jaw)
              (* (loop for (k . v) in jaw summing v) 2)))
        (format t "Armadillos have ~D teeth.~%"
                (count-teeth *dasypus-hybridus))
        (format t "Marsupial moles have ~D teeth in the lower jaw.~%"
                (count-teeth *notoryctes.lower)))
      (let ((delta
              (- *notoryctes.lower.incisors
                 *dugong-dugon.lower.incisors)))
        (format t "Marsupial moles have ~[less~;as many~;more~] ~
                   lower incisors ~:[than~;as~] dugongs.~%"
                (1+ (signum delta)) (zerop delta))))))

Armadillos have 28 teeth.

Marsupial moles have 22 teeth in the lower jaw.

Marsupial moles have as many lower incisors as dugongs.

NIL

JSON-RPC

JSON-RPC is a lightweight remote procedure call protocol similar to XML-RPC. CL-JSON contains some code that implements the version 1.1 Working draft of the JSON-RPC specification (available as Working Draft 7 August 2006). Just plug it into your http server of choice. See the file json-rpc and the package JSON-RPC.

JSONP

JSONP or JSON with Padding is a technique that allows cross-domain function calls. A remote function call looks like this: your javascript code insert a "script" html tag to the page you are visiting. The url of this script tag is your remote server. You also send the name of a callback function to the server as a query string parameter. The browser expects the script tag to retrieve some javascript code from your server. The JSON reponse from your can be turned into a proper javascript function call statement by prepending the name of the callback function first and then wrapping the JSON chunk inside a pair of parentheses. CL-JSON doesn't have any special code to do JSONP, it is more an issue of simple coding with your web server.

Mailing Lists

• cl-json-devel
  for developers and users.
• cl-json-announce
  for announcements.

License

Copyright © 2006-2008 Henrik Hjelte.
Copyright © 2008 Hans Hübner.

This work is licensed under the terms of the MIT / X Consortium license, reproduced below. Mr. Hübner's copyright applies to the code of the streaming API borrowed from his program YASON and transferred under this license with his permission.