Serialism, a Common Clojure Serialization API

Serialism is a tiny Clojure library that serializes and deserializes values into popular formats based on provided content type.

Supported formats:

JSON
SMILE (binary JSON)
Text
Clojure reader forms

It is possible to extend the libray to any other format thanks to Clojure multimethods.

Serialism is heavily influenced by how automatic value serialization is implemented in Welle, a Clojure Riak client.

Project Goals

Serialism tries to provide an extensible serialization library that supports multiple formats behind a single API.

Project Maturity

Serialism is not a young project and the ideas behind it have proven itself in Welle.

Artifacts

Serialism artifacts are released to Clojars. If you are using Maven, add the following repository definition to your pom.xml:

<repository>
  <id>clojars.org</id>
  <url>http://clojars.org/repo</url>
</repository>

The Most Recent Release

With Leiningen:

[clojurewerkz/serialism "1.3.0"]

With Maven:

<dependency>
  <groupId>clojurewerkz</groupId>
  <artifactId>serialism</artifactId>
  <version>1.3.0</version>
</dependency>

Documentation & Examples

Serialism is a tiny library. All key functions are in the clojurewerkz.serialism.core namespace:

clojurewerkz.serialism.core/serialize
clojurewerkz.serialism.core/deserialize

(ns megacorp.myservice
  (:require [clojurewerkz.serialism.core :as s]))

;;
;; Serialization
;;

;; serialize a string to a byte array
(s/serialize "some data" :bytes)
(s/serialize "some data" s/octet-stream-content-type)

;; serialize a Clojure data structure to JSON
(s/serialize {:library "Serialism"} :json)
(s/serialize {:library "Serialism"} s/json-content-type)
(s/serialize {:library "Serialism"} s/json-utf8-content-type)

;; serialize a Clojure data structure to SMILE (binary JSON)
(s/serialize {:library "Serialism"} :smile)
(s/serialize {:library "Serialism"} s/smile-content-type)

;; serialize a Clojure data structure to Clojure reader forms
(s/serialize {:library "Serialism"} :clojure)
(s/serialize {:library "Serialism"} s/clojure-content-type)


;;
;; Deserialization
;;

;; deserialize a string to a text
(s/deserialize "some data" :bytes)
(s/deserialize "some data" s/octet-stream-content-type)

;; deserialize a byte array to a text
(s/deserialize (.getBytes "some data" "UTF-8") :text)
(s/deserialize (.getBytes "some data" "UTF-8") s/text-content-type)

;; serialize a Clojure data structure to JSON
(s/deserialize "{\"language\":\"Clojure\",\"library\":\"serialism\",\"authors\":[\"Michael\"]}"
               :json)
(s/deserialize "{\"language\":\"Clojure\",\"library\":\"serialism\",\"authors\":[\"Michael\"]}"
               s/json-content-type)
(s/deserialize "{\"language\":\"Clojure\",\"library\":\"serialism\",\"authors\":[\"Michael\"]}"
               s/json-utf8-content-type)

;; serialize a Clojure data structure to SMILE (binary JSON)
(s/deserialize bytes-in-the-smile-format :smile)
(s/deserialize bytes-in-the-smile-format s/smile-content-type)

;; serialize a Clojure data structure to Clojure reader forms
(s/deserialize "#=(clojure.lang.PersistentArrayMap/create {:language \"Clojure\", :library \"serialism\", :authors [\"Michael\"]})"
               :clojure)
(s/deserialize "#=(clojure.lang.PersistentArrayMap/create {:language \"Clojure\", :library \"serialism\", :authors [\"Michael\"]})"
               s/clojure-content-type)

Both of these functions are multimethods that can be extended to support other formats (e.g. MessagePack, Kryo or custom formats built with Gloss).

Supported Clojure versions

Serialism requires Clojure 1.6+.

Community

Serialism has a mailing list. Feel free to join it and ask any questions you may have.

To subscribe for announcements of releases, important changes and so on, please follow @ClojureWerkz on Twitter.

Continuous Integration Status

Serialism Is a ClojureWerkz Project

Serialism is part of the group of Clojure libraries known as ClojureWerkz, together with Monger, Welle, Langohr, Elastisch, Neocons, Quartzite, and several others.

Development

serialism uses Leiningen 2. Make sure you have it installed and then run tests against supported Clojure versions using

lein all test

Then create a branch and make your changes on it. Once you are done with your changes and all tests pass, submit a pull request on Github.

License

Double licensed under the Eclipse Public License (the same as Clojure) or the Apache Public License 2.0.