MultiJSON

Lots of Ruby libraries parse JSON and everyone has their favorite JSON coder. Instead of choosing a single JSON coder and forcing users of your library to be stuck with it, you can use MultiJSON instead, which will simply choose the fastest available JSON coder. Here's how to use it:

require "multi_json"

MultiJSON.parse('{"abc":"def"}')                        #=> {"abc" => "def"}
MultiJSON.parse('{"abc":"def"}', symbolize_names: true) #=> {abc: "def"}
MultiJSON.generate({abc: "def"})                       # convert Ruby back to JSON
MultiJSON.generate({abc: "def"}, pretty: true)         # encoded in a pretty form (if supported by the coder)

[!IMPORTANT] 1.21.0 renames the public API to match Ruby stdlib JSON. The canonical verbs are now MultiJSON.parse / MultiJSON.generate, and the canonical module is MultiJSON (all-caps). The legacy MultiJson constant, MultiJSON.load / MultiJSON.dump, :symbolize_keys, and friends still work but emit one-time deprecation warnings and will be removed in 2.0.0. Run your app with ruby -W:deprecated to surface them; the warnings are tagged with the :deprecated category so you can silence the whole set with Warning[:deprecated] = false. See Deprecated in 1.21.0 for the full list.

MultiJSON.parse returns nil for nil, empty, and whitespace-only inputs instead of raising, so a missing or blank payload is observable as a nil return value rather than an exception. When parsing invalid JSON, MultiJSON will throw a MultiJSON::ParseError. MultiJSON::DecodeError and MultiJSON::LoadError are aliases for backwards compatibility.

begin
  MultiJSON.parse("{invalid json}")
rescue MultiJSON::ParseError => exception
  exception.data    #=> "{invalid json}"
  exception.cause   #=> JSON::ParserError: ...
  exception.line    #=> 1 (for adapters that report a location, e.g. Oj or the json gem)
  exception.column  #=> 2
end

Drop-in replacement for stdlib `JSON`

MultiJSON mirrors the surface of Ruby's stdlib JSON so most call sites swap in with a one-line change:

- require "json"
+ require "multi_json"

- JSON.parse(text, symbolize_names: true)
+ MultiJSON.parse(text, symbolize_names: true)

- JSON.generate(object, pretty: true)
+ MultiJSON.generate(object, pretty: true)

Method names and the common options line up with stdlib so existing pretty-print calls and option keys keep working without changes:

stdlib `JSON`	`MultiJSON`	Status
`JSON.parse(str)`	`MultiJSON.parse(str)`	✓
`JSON.generate(obj)`	`MultiJSON.generate(obj)`	✓
`pretty: true`	`pretty: true`	✓
`symbolize_names: true`	`symbolize_names: true`	✓

Deprecated in 1.21.0

The module constant and primary verbs were renamed to match Ruby stdlib JSON.parse / JSON.generate and the JSON spec (RFC 8259). The old names still work in 1.x but now emit a one-time deprecation warning; they will be removed in 2.0.0.

Deprecated	Use instead
`MultiJson` (constant)	`MultiJSON` (all-caps)
`MultiJSON.load(str)`	`MultiJSON.parse(str)`
`MultiJSON.dump(obj)`	`MultiJSON.generate(obj)`
`MultiJSON.load_options=`	`MultiJSON.parse_options=`
`MultiJSON.load_options`	`MultiJSON.parse_options`
`MultiJSON.dump_options=`	`MultiJSON.generate_options=`
`MultiJSON.dump_options`	`MultiJSON.generate_options`
`symbolize_keys:` option	`symbolize_names:` option

The MultiJson constant (CamelCase) continues to work as a thin delegator; every method call, constant lookup, and rescue clause routes through MultiJSON transparently.

[!TIP] The recommended upgrade path to 2.0 is: pin ~> 1.21 first, run ruby -W:deprecated against your app or test suite to surface every deprecation, migrate each call site to the canonical name, then bump to ~> 2.0. The 2.0 release deletes the deprecated aliases entirely, so the warnings during 1.21.x are your map.

ParseError instance has cause reader which contains the original exception. It also has data reader with the input that caused the problem, and line/column readers populated for adapters whose error messages include a location (Oj and the json gem). Adapters that don't include one (Yajl, fast_jsonparser) leave both nil.

Tuning the options cache

MultiJSON memoizes the merged option hash for each parse/generate call so identical option hashes don't trigger repeated work. The cache is bounded — defaulting to 1000 entries per direction — and applications that generate many distinct option hashes can raise the ceiling at runtime:

MultiJSON::OptionsCache.max_cache_size = 5000

max_cache_size must be a positive integer; 0, negative values, and non-integers raise ArgumentError.

Lowering the limit only takes effect for new inserts; existing cache entries are left in place until normal eviction trims them below the new ceiling. Call MultiJSON::OptionsCache.reset if you want to evict immediately.

The use method, which sets the MultiJSON adapter, takes either a symbol or a class (to allow for custom JSON parsers) that responds to both .load and .dump at the class level.

When MultiJSON fails to load the specified adapter, it'll throw MultiJSON::AdapterError which inherits from ArgumentError.

Writing a custom adapter

A custom adapter is any class that responds to two class methods plus defines a ParseError constant:

class MyAdapter
  ParseError = Class.new(StandardError)

  def self.load(string, options)
    # parse string into a Ruby object, raising ParseError on failure
  end

  def self.dump(object, options)
    # serialize object to a JSON string
  end
end

MultiJSON.use(MyAdapter)

ParseError is required: MultiJSON.parse rescues MyAdapter::ParseError to wrap parse failures in MultiJSON::ParseError, and an adapter that omits the constant raises MultiJSON::AdapterError on the first parse attempt instead of producing a confusing NameError.

For more, inherit from MultiJSON::Adapter to pick up shared option merging, the defaults :load, ... / defaults :dump, ... DSL, and the blank-input short-circuit. The built-in adapters in lib/multi_json/adapters/ are working examples.

[!NOTE] The adapter contract methods on the adapter class itself stay named .load / .dump in 1.21.x (and the defaults :load, ... / defaults :dump, ... DSL keys match). The 2.0 release renames them to .parse / .generate to align with the public API; if you ship a custom adapter, you'll need to rename those methods (and the defaults keys) when you upgrade.

MultiJSON tries to have intelligent defaulting. If any supported library is already loaded, MultiJSON uses it before attempting to load others. When no backend is preloaded, MultiJSON walks its preference list and uses the first one that loads successfully. The list is split per platform — JRuby's available adapter set differs from MRI's, and the bundled benchmark suite ranks json_gem ahead of fast_jsonparser/oj/yajl on Ruby 3.4+. CI re-runs the benchmark and fails if the observed ranking diverges from the table below.

rank	MRI / TruffleRuby	JRuby
1	The JSON gem	`jrjackson`
2	`fast_jsonparser`	The JSON gem
3	`oj`	`gson`
4	`yajl-ruby`	—

A dash means the adapter isn't usable on that runtime: fast_jsonparser, oj, and yajl-ruby are MRI/TruffleRuby C extensions with no JRuby builds; jrjackson and gson are JRuby-only. The JSON gem is a Ruby default gem, so it's always available as a last-resort fallback on any supported Ruby. If you have a workload where a different backend is faster, set it explicitly with MultiJSON.use(:your_adapter).

Gem Variants

MultiJSON ships as two platform-specific gems. Bundler and RubyGems automatically select the correct variant for your Ruby implementation:

	`ruby` platform (MRI)	`java` platform (JRuby)
Runtime dependency	none	concurrent-ruby `~> 1.2`
`fast_jsonparser` adapter	✓
`oj` adapter	✓
`yajl` adapter	✓
`json_gem` adapter	✓	✓
`gson` adapter		✓
`jr_jackson` adapter		✓
`OptionsCache` thread-safe store	`Hash` + `Mutex`	`Concurrent::Map`

Supported Ruby Versions

This library aims to support and is tested against the following Ruby implementations:

Ruby 3.2
Ruby 3.3
Ruby 3.4
Ruby 4.0
JRuby 10.0 (targets Ruby 3.4 compatibility)
TruffleRuby 33.0 (native and JVM)

If something doesn't work in one of these implementations, it's a bug.

This library may inadvertently work (or seem to work) on other Ruby implementations, however support will only be provided for the versions listed above.

If you would like this library to support another Ruby version, you may volunteer to be a maintainer. Being a maintainer entails making sure all tests run and pass on that implementation. When something breaks on your implementation, you will be responsible for providing patches in a timely fashion. If critical issues for a particular implementation exist at the time of a major release, support for that Ruby version may be dropped.

Versioning

This library aims to adhere to Semantic Versioning 2.0.0. Violations of this scheme should be reported as bugs. Specifically, if a minor or patch version is released that breaks backward compatibility, that version should be immediately yanked and/or a new version should be immediately released that restores compatibility. Breaking changes to the public API will only be introduced with new major versions. As a result of this policy, you can (and should) specify a dependency on this gem using the Pessimistic Version Constraint with two digits of precision. For example:

spec.add_dependency 'multi_json', '~> 1.0'