Oj gem¶ ↑
A fast JSON parser and Object marshaller as a Ruby gem.
Installation¶ ↑
gem install oj
or in Bundler: gem 'oj'
Documentation¶ ↑
Documentation: www.ohler.com/oj, rubydoc.info/gems/oj
Source¶ ↑
GitHub repo: github.com/ohler55/oj
RubyGems repo: rubygems.org/gems/oj
Follow @peterohler on Twitter for announcements and news about the Oj gem.
Build Status¶ ↑
Release 2.12.14¶ ↑
-
Change the failure mode for objects that can not be serialized such as a socket. Now in compat mode the to_s of the object is placed in the output instead of raising an exception.
Description¶ ↑
Optimized JSON (Oj), as the name implies, was written to provide speed optimized JSON handling. It was designed as a faster alternative to Yajl and other common Ruby JSON parsers. So far it has achieved that, and is about 2 times faster than any other Ruby JSON parser, and 3 or more times faster at serializing JSON.
Oj has several dump
or serialization
modes which control how Ruby Object
s are converted to JSON. These modes are set with the :mode
option in either the default options or as one of the options to the
dump
method. The default mode is the :object
mode.
-
:strict
mode will only allow the 7 basic JSON types to be serialized. Any otherObject
will raise anException
. -
:null
mode replaces anyObject
that is not one of the JSON types with a JSONnull
. -
:object
mode will dump anyObject
as a JSONObject
with keys that match the RubyObject
's variable names without the '@' prefix character. This is the highest performance mode. -
:compat
mode attempts to be compatible with other systems. It will serialize anyObject
, but will check to see if theObject
implements anto_hash
orto_json
method. If either exists, that method is used for serializing theObject
. Sinceas_json
is more flexible and produces more consistent output, it is preferred over theto_json
method. If neither theto_json
orto_hash
methods exists, then the Oj internalObject
variable encoding is used.
To change default serialization mode: ruby Oj.default_options =
{:mode => :compat }
Compatibility¶ ↑
Ruby¶ ↑
Oj is compatible with Ruby 1.8.7, 1.9.2, 1.9.3, 2.0.0, 2.1, 2.2 and RBX. Support for JRuby has been removed as JRuby no longer supports C extensions and there are bugs in the older versions that are not being fixed.
Rails¶ ↑
Although up until 4.1 Rails uses multi_json, an issue in Rails causes
ActiveSupport to fail to make use Oj for JSON handling. There is a
gem to patch
this for Rails 3.2 and 4.0. As of the Oj 2.6.0
release the default behavior is to not use the to_json()
method unless the :use_to_json
option is set. This provides
another work around to the rails older and newer behavior.
The latest ActiveRecord is able to work with Oj by
simply using the line: serialize :my_attr, Oj
In version Rails 4.1, multi_json has been removed, and this patch is
unnecessary and will no longer work. Instead, use the
oj_mimic_json
gem along with
oj
in your Gemfile
to have Oj mimic the JSON gem and be
used in its place by ActiveSupport
JSON handling: gem 'oj' gem
'oj_mimic_json'
Proper Use¶ ↑
Two settings in Oj are useful for parsing but do
expose a vulnerability if used from an untrusted source. Symbolized keys
can cause memory to be filled with previous versions of ruby. Ruby 2.1 and
below does not garbage collect Symbols. The same is true for auto defining
classes in all versions of ruby; memory will also be exhausted if too many
classes are automatically defined. Auto defining is a useful feature during
development and from trusted sources but it allows too many classes to be
created in the object load mode and auto defined is used with an untrusted
source. The Oj.strict_load()
method sets and uses the most
strict and safest options. It should be used by developers who find it
difficult to understand the options available in Oj.
The options in Oj are designed to provide flexibility
to the developer. This flexibility allows Objects to be serialized and
deserialized. No methods are ever called on these created Objects but that
does not stop the developer from calling methods on them. As in any system,
check your inputs before working with them. Taking an arbitrary
String
from a user and evaluating it is never a good idea from
an unsecure source. The same is true for Object
attributes as
they are not more than String
s. Always check inputs from
untrusted sources.
Simple JSON Writing and Parsing Example¶ ↑
require 'oj' h = { 'one' => 1, 'array' => [ true, false ] } json = Oj.dump(h) # json = # { # "one":1, # "array":[ # true, # false # ] # } h2 = Oj.load(json) puts "Same? #{h == h2}" # true
Alternative JSON Processing APIs¶ ↑
Oj offers a few alternative APIs for processing JSON. The fastest one is the Oj::Doc
API.
The Oj::Doc
API takes a completely different approach by
opening a JSON document and providing calls to
navigate around the JSON while it is open. With
this approach, JSON access can be well over 20
times faster than conventional JSON parsing.
The Oj::Saj
and Oj::ScHandler
APIs are callback
parsers that walk the JSON document depth first and
makes callbacks for each element. Both callback parser are useful when only
portions of the JSON are of interest. Performance
up to 20 times faster than conventional JSON is
possible. The API is simple to use but does require a different approach
than the conventional parse followed by access approach used by
conventional JSON parsing.
Links¶ ↑
Performance Comparisons¶ ↑
Oj Strict Mode Performance compares Oj strict mode parser performance to other JSON parsers.
Oj Compat Mode Performance compares Oj compat mode parser performance to other JSON parsers.
Oj Object Mode Performance compares Oj object mode parser performance to other marshallers.
Oj Callback Performance compares Oj callback parser performance to other JSON parsers.
Links of Interest¶ ↑
Fast XML parser and marshaller on RubyGems: rubygems.org/gems/ox
Fast XML parser and marshaller on GitHub: github.com/ohler55/ox
Oj Object Encoding Format describes the OJ Object JSON encoding format.
Need for Speed for an overview of how Oj::Doc was designed.
OjC, a C JSON parser: www.ohler.com/ojc also at github.com/ohler55/ojc