handling-json-in-common-lisp

name	handling-json-in-common-lisp
description	Use when encoding or decoding JSON, building dictionary/map data, or choosing between hash-tables, alists, and plists in Common Lisp — especially with YASON or serapeum:dict, or when a JSON null check via (null ...) returns the wrong answer.

Handling JSON in Common Lisp

Overview

JSON objects map to hash-tables with string keys, not alists or plists. Build them with serapeum:dict; read with gethash. JSON null is the keyword :null, not CL nil.

When to Use

• Encoding/decoding JSON with YASON
• Building a nested map/dictionary value
• A (null value) check on parsed JSON returns the wrong answer
• Deciding between hash-table / alist / plist for lookup data

Build objects with serapeum:dict

(serapeum:dict "a" 1
               "b" (serapeum:dict "nested" 42))
;; => #<HASH-TABLE :test equal :size 2>

dict returns a hash-table with :test 'equal and string keys — exactly what YASON encodes as a JSON object. Do not use alists or plists for JSON/lookup data:

;; Bad — alist for a JSON object (string keys, O(n) lookup, trips YASON)
'(("a" . 1) ("b" . (("nested" . 42))))

Read with gethash, not assoc

serapeum:dict returns a hash-table, so assoc/cdr silently return nil. Use gethash:

(gethash "a" obj)            ;; good
(cdr (assoc "a" obj :test #'string=))  ;; wrong on a hash-table — returns nil

JSON null is :null, not CL nil

With the round-trip flags below, YASON parses JSON null as the keyword :null and JSON false as nil. Check for null explicitly:

(eq :null (gethash "field" obj))   ;; good
(null (gethash "field" obj))        ;; wrong — returns T for :null's absence handling AND for actual nil/false

YASON round-trip flags

For faithful JSON → Lisp → JSON round-tripping, parse with these flags:

(yason:parse string
             :json-arrays-as-vectors t
             :json-booleans-as-symbols t
             :json-null-as-keyword t)

Without :json-null-as-keyword t, both null and [] collapse ambiguously; nil becomes indistinguishable from JSON false/empty.

Encode without a stream argument inside with-output-to-string*

(yason:with-output-to-string* ()
  (yason:encode obj))            ;; good — no second argument

Passing an explicit stream/nil to yason:encode here suppresses output and returns an empty string.

Common Mistakes

Symptom	Fix
Built a JSON object as '((:a . 1) ...) alist	Use (serapeum:dict "a" 1 ...) — hash-table, string keys
(assoc "k" obj) returns nil on a serapeum:dict	obj is a hash-table — use (gethash "k" obj)
(null x) is T unexpectedly for a JSON null field	JSON null is :null; test with (eq :null x)
null and []/false collide after parse	Parse with :json-null-as-keyword t, :json-booleans-as-symbols t, :json-arrays-as-vectors t
yason:with-output-to-string* returns ""	Don't pass a stream/nil to yason:encode inside it

Related skills

For general package/style of the file holding JSON code: writing-common-lisp. For interactive parse/encode from a live image: using-common-lisp-repl.