Cheshire Documentation

Since version 5.0.0, custom encoding is part of the core namespace. You can register custom encoders for specific Java classes to control how they are serialized. This allows you to use the fast core encoder while providing custom logic for specific types.

Use add-encoder to register a function that takes the object and a jsonGenerator. Use remove-encoder to unregister them.

Common built-in encoder helpers include: encode-nil, encode-number, encode-seq, encode-date, encode-bool, encode-named, encode-map, encode-symbol, and encode-ratio.

(ns myns
  (:require [cheshire.core :refer :all]
            [cheshire.generate :refer [add-encoder encode-str remove-encoder]]))

;; Add a custom encoder for a class
(add-encoder java.awt.Color
             (fn [c jsonGenerator]
               (.writeString jsonGenerator (str c))))

;; Use a helper for common encoding actions
(add-encoder java.net.URL encode-str)

;; Use the encoder
(encode (java.awt.Color. 1 2 3))

;; Remove a custom encoder
(remove-encoder java.awt.Color)

Use parse-string (or the alias decode) to convert JSON strings into Clojure data structures.

Key features:

• Keywords: Pass true as the second argument to return keys as keywords.
• Custom Keyword Coercion: Pass a function as the second argument to munge keywords during parsing.
• Type Specification: In version 2.0.4+, you can pass a function as the third argument to specify how certain fields should be decoded (e.g., converting a JSON array into a Clojure set).

For streams and SMILE, use parse-stream, parsed-seq (lazy), parse-smile, or parsed-smile-seq (lazy SMILE).

;; parse some json
(parse-string "{\"foo\":\"bar\"}")

;; parse some json and get keywords back
(parse-string "{\"foo\":\"bar\"}" true)

;; parse some json and munge keywords with a custom function
(parse-string "{\"foo\":\"bar\"}" (fn [k] (keyword (.toUpperCase k))))

;; parse a stream (keywords option also supported)
(parse-stream (clojure.java.io/reader "/tmp/foo"))

;; parse a stream lazily (keywords option also supported)
(parsed-seq (clojure.java.io/reader "/tmp/foo"))

;; In 2.0.4 and up, specify return types via a function
(decode "{\"myarray\":[2,3,3,2],\"myset\":[1,2,2,1]}" true
        (fn [field-name]
          (if (= field-name "myset")
            #{} 
            [])))
;; => {:myarray [2 3 3 2], :myset #{1 2}}

Use generate-string (or the alias encode) to convert Clojure data structures into a JSON string. Cheshire supports strings, lists, vectors, sets, maps, symbols, booleans, keywords, and various number types.

Common options for generate-string include:

• :pretty: Boolean. If true, enables pretty-printing.
• :date-format: String. Customizes the date format (default is yyyy-MM-dd'T'HH:mm:ss'Z').
• :escape-non-ascii: Boolean. If true, escapes non-ASCII characters (e.g., UTF-8).
• :key-fn: Function. A function used to munge keys during encoding.

If encoding fails, a JsonGenerationException is thrown.

;; generate some json
(generate-string {:foo "bar" :baz 5})

;; generate some JSON with Dates with custom Date encoding
(generate-string {:baz (java.util.Date. 0)} {:date-format "yyyy-MM-dd"})

;; generate some JSON with pretty formatting
(generate-string {:foo "bar" :baz {:eggplant [1 2 3]}} {:pretty true})

;; generate JSON escaping UTF-8
(generate-string {:foo "It costs £100"} {:escape-non-ascii true})

;; generate JSON and munge keys with a custom function
(generate-string {:foo "bar"} {:key-fn (fn [k] (.toUpperCase (name k)))})