Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

JSON Encoder/Decoder for PicoLisp

GitHub release Dependency Build status

This library can be used to parse and serialize (encode/decode) JSON strings in pure PicoLisp.


NEW: Please read to learn more about PicoLisp and this (v3) JSON library.

Please read to learn more about PicoLisp and the older (v2) JSON library.

  1. Requirements
  2. Getting Started
  3. Usage
  4. Examples
  5. Testing
  6. Alternatives
  7. Contributing
  8. Changelog
  9. License


  • PicoLisp 32-bit v3.1.11 to v20.6 (tested)
  • PicoLisp 64-bit v17.12 to v20.6 (tested)
  • PicoLisp 64-bit pil21 (tested)

BREAKING CHANGE since v4.0.0: Namespaces have been completely removed, and all function names are now prefixed with json- (see Changelog).

Getting Started

This library has been rewritten in pure PicoLisp and contains no external dependencies.

These FFI bindings require the Parson C library, compiled as a shared library

  1. Include json.l in your project
  2. Try the examples below


Public functions:

  • (json-decode arg1 arg2) parses a JSON string or file
    • arg1 String: the JSON string or filename you want to decode
    • arg2 Flag (optional): a flag (T or NIL) indicating to parse a file if set
  • (json-encode arg1) serializes a list into a JSON string
    • arg1 List: a PicoLisp list which will be converted to a JSON string

JSON-PicoLisp data type table

JSON PicoLisp Example
Number Number 25 <-> 25
String String "hello" <-> "hello"
Null Transient null Symbol null <-> 'null
Boolean Transient true or false Symbol true <-> 'true
Array List with T in cdar {"array":[1,2,3]} <-> '(("array" T 1 2 3))
Object Cons pair {"hello":"world"} <-> '(("hello" . "world"))


  • To disallow duplicate Object keys: (on *Json_prevent_duplicate_keys). Default allows duplicate Object keys.
  • A successful result will return a list.
  • Failures return NIL, store the error message in *Msg, and print the error message to STDERR (standard error).
  • Keys are in car, values are in cdr.
  • When the 2nd item in the list is T, the rest of the list represents a JSON array.
  • When the 2nd item in the list is a cons pair, it represents a JSON object.
  • Supports Unicode characters as "\uNNNN" where N is a hexadecimal digit.

JSON Specification

This library conforms to the ECMA-404 The JSON Data Interchange Standard, except for the following semantic exceptions:

  • [Numbers] Scientific (floating point, fractional, exponential) numbers (ex: 3.7e-5) are not accepted. They must be provided as strings (ex: "3.7e-5").


(json-decode String)

(load "json.l")

(json-decode "{\"Hello\":\"World\"}")

-> (("Hello" . "World"))

(json-decode Filename T)

The same function is used for parsing JSON strings and files. Simply append T as the last argument if you want to parse a file.

(load "json.l")

(json-decode "test.json" T)

-> (("first" . "John")
    ("last" . "Doe")
    ("age" . 25)
    ("registered" . true)
    ("interests" T "Reading" "Mountain Biking")
    ("favorites" ("color" . "blue") ("sport" . "running"))
    ("utf string" . "lorem ipsum")
    ("utf-8 string" . "あいうえお")
    ("surrogate string" . "lorem�ipsum�lorem") )

(json-encode List)

(load "json.l")

(json-encode '(("Hello" . "World")))

-> "{\"Hello\":\"World\"}"

(json-decode InvalidString)

(json-decode "{\"Hello\":invalid}")
"Invalid Object 'invalid', must be '[' OR '{' OR string OR number OR true OR false OR null"

-> NIL


This library comes with full unit tests. To run the tests, type:

make check


The following are alternatives also written in pure PicoLisp. They are limited by pipe/read syscalls.


If you find any bugs or issues, please create an issue.

If you want to improve this library, please make a pull-request.



MIT License

Copyright (c) 2015-2020 Alexander Williams, Unscramble