Home

Awesome

data.json

JSON parser/generator to/from Clojure data structures.

Key goals:

Releases and Dependency Information

This project follows the version scheme MAJOR.MINOR.PATCH where each component provides some relative indication of the size of the change, but does not follow semantic versioning. In general, all changes endeavor to be non-breaking (by moving to new names rather than by breaking existing names).

Latest stable release is 2.5.0

CLI/deps.edn dependency information:

org.clojure/data.json {:mvn/version "2.5.0"}

Leiningen dependency information:

[org.clojure/data.json "2.5.0"]

Maven dependency information:

<dependency>
  <groupId>org.clojure</groupId>
  <artifactId>data.json</artifactId>
  <version>2.5.0</version>
</dependency>

Other versions:

Usage

API Documentation

Example usage:

(ns example
  (:require [clojure.data.json :as json]))

To convert to/from JSON strings, use json/write-str and json/read-str:

(json/write-str {:a 1 :b 2})
;;=> "{\"a\":1,\"b\":2}"

(json/read-str "{\"a\":1,\"b\":2}")
;;=> {"a" 1, "b" 2}

Note that these operations are not symmetric: converting Clojure data into JSON is lossy.

Converting Key/Value Types

You can specify a :key-fn to convert map keys on the way in or out:

(json/read-str "{\"a\":1,\"b\":2}"
               :key-fn keyword)
;;=> {:a 1, :b 2}

(json/write-str {:a 1 :b 2}
                :key-fn #(.toUpperCase %))
;;=> "{\"A\":1,\"B\":2}"

(json/read-str "{\"a\":1,\"b\":2}"
               :key-fn #(keyword "com.example" %))
;;=> {:com.example/a 1, :com.example/b 2}

You can specify a :value-fn to convert map values on the way in or out. The value-fn will be called with two arguments, the key and the value, and it returns the updated value.

(defn my-value-reader [key value]
  (if (= key :date)
    (java.sql.Date/valueOf value)
    value))

(json/read-str "{\"number\":42,\"date\":\"2012-06-02\"}"
               :value-fn my-value-reader
               :key-fn keyword) 
;;=> {:number 42, :date #inst "2012-06-02T04:00:00.000-00:00"}

Be aware that :value-fn only works on maps (JSON objects). If your root data structure is, for example, a vector of dates, you will need to pre- or post-process it outside of data.json. clojure.walk may be useful for this.

Order of key-fn / value-fn

If you specify both a :key-fn and a :value-fn when reading, the value-fn is called after the key has been processed by the key-fn.

The reverse is true when writing:

(defn my-value-writer [key value]
  (if (= key :date)
    (str (java.sql.Date. (.getTime value)))
    value))

(json/write-str {:number 42, :date (java.util.Date. 112 5 2)}
                :value-fn my-value-writer
                :key-fn name) 
;;=> "{\"number\":42,\"date\":\"2012-06-02\"}"

Reading/Writing a Stream

You can also read JSON directly from a java.io.Reader with json/read and write JSON directly to a java.io.Writer with json/write.

More

Other options are available. Refer to the API Documentation for details.

Developer Information

Change Log

Copyright and License

Copyright (c) Stuart Sierra, Rich Hickey, and contributors. All rights reserved. The use and distribution terms for this software are covered by the Eclipse Public License 1.0 (https://opensource.org/license/epl-1-0/) witch can be found in the file epl-v10.html at the root of this distribution. By using this software in any fashion, you are agreeing to be bound by the terms of this license. You must not remove this notice, or any other, from this software.