JavaScript Object Notation (JSON)¶↑

JSON is a lightweight data-interchange format.

A JSON value is one of the following:

• Double-quoted text:"foo".

• Number:1,1.0,2.0e2.

• Boolean:true,false.

• Null:null.

• Array: an ordered list of values, enclosed by square brackets:

  ["foo",1,1.0,2.0e2,true,false,null]

• Object: a collection of name/value pairs, enclosed by curly braces; each name is double-quoted text; the values may be any JSON values:

  {"a":"foo","b":1,"c":1.0,"d":2.0e2,"e":true,"f":false,"g":null}

A JSON array or object may contain nested arrays, objects, and scalars to any depth:

{"foo": {"bar":1,"baz":2},"bat": [0,1,2]}[{"foo":0,"bar":1}, ["baz",2]]

Using Module JSON¶↑

To make module JSON available in your code, begin with:

require'json'

All examples here assume that this has been done.

Parsing JSON¶↑

You can parse a String containing JSON data using either of two methods:

• JSON.parse(source, opts)

• JSON.parse!(source, opts)

where

• source is a Ruby object.

• opts is a Hash object containing options that control both input allowed and output formatting.

The difference between the two methods is thatJSON.parse! omits some checks and may not be safe for somesource data; use it only for data from trusted sources. Use the safer methodJSON.parse for less trusted sources.

Parsing JSON Arrays¶↑

Whensource is a JSON array,JSON.parse by default returns a Ruby Array:

json ='["foo", 1, 1.0, 2.0e2, true, false, null]'ruby =JSON.parse(json)ruby# => ["foo", 1, 1.0, 200.0, true, false, nil]ruby.class# => Array

The JSON array may contain nested arrays, objects, and scalars to any depth:

json ='[{"foo": 0, "bar": 1}, ["baz", 2]]'JSON.parse(json)# => [{"foo"=>0, "bar"=>1}, ["baz", 2]]

Parsing JSON Objects¶↑

When the source is a JSON object,JSON.parse by default returns a Ruby Hash:

json ='{"a": "foo", "b": 1, "c": 1.0, "d": 2.0e2, "e": true, "f": false, "g": null}'ruby =JSON.parse(json)ruby# => {"a"=>"foo", "b"=>1, "c"=>1.0, "d"=>200.0, "e"=>true, "f"=>false, "g"=>nil}ruby.class# => Hash

The JSON object may contain nested arrays, objects, and scalars to any depth:

json ='{"foo": {"bar": 1, "baz": 2}, "bat": [0, 1, 2]}'JSON.parse(json)# => {"foo"=>{"bar"=>1, "baz"=>2}, "bat"=>[0, 1, 2]}

Parsing JSON Scalars¶↑

When the source is a JSON scalar (not an array or object),JSON.parse returns a Ruby scalar.

String:

ruby =JSON.parse('"foo"')ruby# => 'foo'ruby.class# => String

Integer:

ruby =JSON.parse('1')ruby# => 1ruby.class# => Integer

Float:

ruby =JSON.parse('1.0')ruby# => 1.0ruby.class# => Floatruby =JSON.parse('2.0e2')ruby# => 200ruby.class# => Float

Boolean:

ruby =JSON.parse('true')ruby# => trueruby.class# => TrueClassruby =JSON.parse('false')ruby# => falseruby.class# => FalseClass

Null:

ruby =JSON.parse('null')ruby# => nilruby.class# => NilClass

Parsing Options¶↑

Input Options¶↑

Optionmax_nesting (Integer) specifies the maximum nesting depth allowed; defaults to100; specifyfalse to disable depth checking.

With the default,false:

source ='[0, [1, [2, [3]]]]'ruby =JSON.parse(source)ruby# => [0, [1, [2, [3]]]]

Too deep:

# Raises JSON::NestingError (nesting of 2 is too deep):JSON.parse(source, {max_nesting:1})

Bad value:

# Raises TypeError (wrong argument type Symbol (expected Fixnum)):JSON.parse(source, {max_nesting::foo})

Optionallow_duplicate_key specifies whether duplicate keys in objects should be ignored or cause an error to be raised:

When not specified:

# The last value is used and a deprecation warning emitted.JSON.parse('{"a": 1, "a":2}') => {"a" => 2}# warning: detected duplicate keys in JSON object.# This will raise an error in json 3.0 unless enabled via `allow_duplicate_key: true`

When set to ‘true`

# The last value is used.JSON.parse('{"a": 1, "a":2}') => {"a" => 2}

When set to ‘false`, the future default:

JSON.parse('{"a": 1, "a":2}') => duplicate key at line 1 column 1 (JSON::ParserError)

Optionallow_nan (boolean) specifies whether to allowNaN,Infinity, andMinusInfinity insource; defaults tofalse.

With the default,false:

# Raises JSON::ParserError (225: unexpected token at '[NaN]'):JSON.parse('[NaN]')# Raises JSON::ParserError (232: unexpected token at '[Infinity]'):JSON.parse('[Infinity]')# Raises JSON::ParserError (248: unexpected token at '[-Infinity]'):JSON.parse('[-Infinity]')

Allow:

source ='[NaN, Infinity, -Infinity]'ruby =JSON.parse(source, {allow_nan:true})ruby# => [NaN, Infinity, -Infinity]

Optionallow_trailing_comma (boolean) specifies whether to allow trailing commas in objects and arrays; defaults tofalse.

With the default,false:

JSON.parse('[1,]')# unexpected character: ']' at line 1 column 4 (JSON::ParserError)

When enabled:

JSON.parse('[1,]',allow_trailing_comma:true)# => [1]

Output Options¶↑

Optionfreeze (boolean) specifies whether the returned objects will be frozen; defaults tofalse.

Optionsymbolize_names (boolean) specifies whether returned Hash keys should be Symbols; defaults tofalse (use Strings).

With the default,false:

source ='{"a": "foo", "b": 1.0, "c": true, "d": false, "e": null}'ruby =JSON.parse(source)ruby# => {"a"=>"foo", "b"=>1.0, "c"=>true, "d"=>false, "e"=>nil}

Use Symbols:

ruby =JSON.parse(source, {symbolize_names:true})ruby# => {:a=>"foo", :b=>1.0, :c=>true, :d=>false, :e=>nil}

Optionobject_class (Class) specifies the Ruby class to be used for each JSON object; defaults to Hash.

With the default, Hash:

source ='{"a": "foo", "b": 1.0, "c": true, "d": false, "e": null}'ruby =JSON.parse(source)ruby.class# => Hash

Use class OpenStruct:

ruby =JSON.parse(source, {object_class:OpenStruct})ruby# => #<OpenStruct a="foo", b=1.0, c=true, d=false, e=nil>

Optionarray_class (Class) specifies the Ruby class to be used for each JSON array; defaults to Array.

With the default, Array:

source ='["foo", 1.0, true, false, null]'ruby =JSON.parse(source)ruby.class# => Array

Use class Set:

ruby =JSON.parse(source, {array_class:Set})ruby# => #<Set: {"foo", 1.0, true, false, nil}>

Optioncreate_additions (boolean) specifies whether to use JSON additions in parsing. SeeJSON Additions.

Generating JSON¶↑

To generate a Ruby String containing JSON data, use methodJSON.generate(source, opts), where

• source is a Ruby object.

• opts is a Hash object containing options that control both input allowed and output formatting.

Generating JSON from Arrays¶↑

When the source is a Ruby Array,JSON.generate returns a String containing a JSON array:

ruby = [0,'s',:foo]json =JSON.generate(ruby)json# => '[0,"s","foo"]'

The Ruby Array array may contain nested arrays, hashes, and scalars to any depth:

ruby = [0, [1,2], {foo:3,bar:4}]json =JSON.generate(ruby)json# => '[0,[1,2],{"foo":3,"bar":4}]'

Generating JSON from Hashes¶↑

When the source is a Ruby Hash,JSON.generate returns a String containing a JSON object:

ruby = {foo:0,bar:'s',baz::bat}json =JSON.generate(ruby)json# => '{"foo":0,"bar":"s","baz":"bat"}'

The Ruby Hash array may contain nested arrays, hashes, and scalars to any depth:

ruby = {foo: [0,1],bar: {baz:2,bat:3},bam::bad}json =JSON.generate(ruby)json# => '{"foo":[0,1],"bar":{"baz":2,"bat":3},"bam":"bad"}'

Generating JSON from Other Objects¶↑

When the source is neither an Array nor a Hash, the generated JSON data depends on the class of the source.

When the source is a Ruby Integer or Float,JSON.generate returns a String containing a JSON number:

JSON.generate(42)# => '42'JSON.generate(0.42)# => '0.42'

When the source is a Ruby String,JSON.generate returns a String containing a JSON string (with double-quotes):

JSON.generate('A string')# => '"A string"'

When the source istrue,false ornil,JSON.generate returns a String containing the corresponding JSON token:

JSON.generate(true)# => 'true'JSON.generate(false)# => 'false'JSON.generate(nil)# => 'null'

When the source is none of the above,JSON.generate returns a String containing a JSON string representation of the source:

JSON.generate(:foo)# => '"foo"'JSON.generate(Complex(0,0))# => '"0+0i"'JSON.generate(Dir.new('.'))# => '"#<Dir>"'

Generating Options¶↑

Input Options¶↑

Optionallow_nan (boolean) specifies whetherNaN,Infinity, and-Infinity may be generated; defaults tofalse.

With the default,false:

# Raises JSON::GeneratorError (920: NaN not allowed in JSON):JSON.generate(JSON::NaN)# Raises JSON::GeneratorError (917: Infinity not allowed in JSON):JSON.generate(JSON::Infinity)# Raises JSON::GeneratorError (917: -Infinity not allowed in JSON):JSON.generate(JSON::MinusInfinity)

Allow:

ruby = [Float::NaN,Float::Infinity,Float::MinusInfinity]JSON.generate(ruby,allow_nan:true)# => '[NaN,Infinity,-Infinity]'

Optionallow_duplicate_key (boolean) specifies whether hashes with duplicate keys should be allowed or produce an error. defaults to emit a deprecation warning.

With the default, (not set):

Warning[:deprecated] =trueJSON.generate({foo:1,"foo"=>2 })# warning: detected duplicate key "foo" in {foo: 1, "foo" => 2}.# This will raise an error in json 3.0 unless enabled via `allow_duplicate_key: true`# => '{"foo":1,"foo":2}'

Withfalse

JSON.generate({foo:1,"foo"=>2 },allow_duplicate_key:false)# detected duplicate key "foo" in {foo: 1, "foo" => 2} (JSON::GeneratorError)

In version 3.0,false will become the default.

Optionmax_nesting (Integer) specifies the maximum nesting depth inobj; defaults to100.

With the default,100:

obj = [[[[[[0]]]]]]JSON.generate(obj)# => '[[[[[[0]]]]]]'

Too deep:

# Raises JSON::NestingError (nesting of 2 is too deep):JSON.generate(obj,max_nesting:2)

Escaping Options¶↑

Optionsscript_safe (boolean) specifies wether'\u2028','\u2029' and'/' should be escaped as to make theJSON object safe to interpolate in script tags.

Optionsascii_only (boolean) specifies wether all characters outside the ASCII range should be escaped.

Output Options¶↑

The default formatting options generate the most compact JSON data, all on one line and with no whitespace.

You can use these formatting options to generate JSON data in a more open format, using whitespace. See alsoJSON.pretty_generate.

• Optionarray_nl (String) specifies a string (usually a newline) to be inserted after each JSON array; defaults to the empty String,''.

• Optionobject_nl (String) specifies a string (usually a newline) to be inserted after each JSON object; defaults to the empty String,''.

• Optionindent (String) specifies the string (usually spaces) to be used for indentation; defaults to the empty String,''; defaults to the empty String,''; has no effect unless optionsarray_nl orobject_nl specify newlines.

• Optionspace (String) specifies a string (usually a space) to be inserted after the colon in each JSON object’s pair; defaults to the empty String,''.

• Optionspace_before (String) specifies a string (usually a space) to be inserted before the colon in each JSON object’s pair; defaults to the empty String,''.

In this example,obj is used first to generate the shortest JSON data (no whitespace), then again with all formatting options specified:

obj = {foo: [:bar,:baz],bat: {bam:0,bad:1}}json =JSON.generate(obj)puts'Compact:',jsonopts = {array_nl:"\n",object_nl:"\n",indent:'  ',space_before:' ',space:' '}puts'Open:',JSON.generate(obj,opts)

Output:

Compact:{"foo":["bar","baz"],"bat":{"bam":0,"bad":1}}Open:{  "foo" : [    "bar",    "baz"],  "bat" : {    "bam" : 0,    "bad" : 1  }}

JSON Additions¶↑

Note thatJSON Additions must only be used with trusted data, and is deprecated.

When you “round trip” a non-String object from Ruby to JSON and back, you have a new String, instead of the object you began with:

ruby0 =Range.new(0,2)json =JSON.generate(ruby0)json# => '0..2"'ruby1 =JSON.parse(json)ruby1# => '0..2'ruby1.class# => String

You can use JSONadditions to preserve the original object. The addition is an extension of a ruby class, so that:

• JSON.generate stores more information in the JSON string.

• JSON.parse, called with optioncreate_additions, uses that information to create a proper Ruby object.

This example shows a Range being generated into JSON and parsed back into Ruby, both without and with the addition for Range:

ruby =Range.new(0,2)# This passage does not use the addition for Range.json0 =JSON.generate(ruby)ruby0 =JSON.parse(json0)# This passage uses the addition for Range.require'json/add/range'json1 =JSON.generate(ruby)ruby1 =JSON.parse(json1,create_additions:true)# Make a nice display.display =<<~EOT  Generated JSON:    Without addition:  #{json0} (#{json0.class})    With addition:     #{json1} (#{json1.class})  Parsed JSON:    Without addition:  #{ruby0.inspect} (#{ruby0.class})    With addition:     #{ruby1.inspect} (#{ruby1.class})EOTputsdisplay

This output shows the different results:

Generated JSON:  Without addition:  "0..2" (String)  With addition:     {"json_class":"Range","a":[0,2,false]} (String)Parsed JSON:  Without addition:  "0..2" (String)  With addition:     0..2 (Range)

The JSON module includes additions for certain classes. You can also craft custom additions. SeeCustom JSON Additions.

Built-in Additions¶↑

The JSON module includes additions for certain classes. To use an addition,require its source:

• BigDecimal:require 'json/add/bigdecimal'

• Complex:require 'json/add/complex'

• Date:require 'json/add/date'

• DateTime:require 'json/add/date_time'

• Exception:require 'json/add/exception'

• OpenStruct:require 'json/add/ostruct'

• Range:require 'json/add/range'

• Rational:require 'json/add/rational'

• Regexp:require 'json/add/regexp'

• Set:require 'json/add/set'

• Struct:require 'json/add/struct'

• Symbol:require 'json/add/symbol'

• Time:require 'json/add/time'

To reduce punctuation clutter, the examples below show the generated JSON viaputs, rather than the usualinspect,

BigDecimal:

require'json/add/bigdecimal'ruby0 =BigDecimal(0)# 0.0json =JSON.generate(ruby0)# {"json_class":"BigDecimal","b":"27:0.0"}ruby1 =JSON.parse(json,create_additions:true)# 0.0ruby1.class# => BigDecimal

Complex:

require'json/add/complex'ruby0 =Complex(1+0i)# 1+0ijson =JSON.generate(ruby0)# {"json_class":"Complex","r":1,"i":0}ruby1 =JSON.parse(json,create_additions:true)# 1+0iruby1.class# Complex

Date:

require'json/add/date'ruby0 =Date.today# 2020-05-02json =JSON.generate(ruby0)# {"json_class":"Date","y":2020,"m":5,"d":2,"sg":2299161.0}ruby1 =JSON.parse(json,create_additions:true)# 2020-05-02ruby1.class# Date

DateTime:

require'json/add/date_time'ruby0 =DateTime.now# 2020-05-02T10:38:13-05:00json =JSON.generate(ruby0)# {"json_class":"DateTime","y":2020,"m":5,"d":2,"H":10,"M":38,"S":13,"of":"-5/24","sg":2299161.0}ruby1 =JSON.parse(json,create_additions:true)# 2020-05-02T10:38:13-05:00ruby1.class# DateTime

Exception (and its subclasses including RuntimeError):

require'json/add/exception'ruby0 =Exception.new('A message')# A messagejson =JSON.generate(ruby0)# {"json_class":"Exception","m":"A message","b":null}ruby1 =JSON.parse(json,create_additions:true)# A messageruby1.class# Exceptionruby0 =RuntimeError.new('Another message')# Another messagejson =JSON.generate(ruby0)# {"json_class":"RuntimeError","m":"Another message","b":null}ruby1 =JSON.parse(json,create_additions:true)# Another messageruby1.class# RuntimeError

OpenStruct:

require'json/add/ostruct'ruby0 =OpenStruct.new(name:'Matz',language:'Ruby')# #<OpenStruct name="Matz", language="Ruby">json =JSON.generate(ruby0)# {"json_class":"OpenStruct","t":{"name":"Matz","language":"Ruby"}}ruby1 =JSON.parse(json,create_additions:true)# #<OpenStruct name="Matz", language="Ruby">ruby1.class# OpenStruct

Range:

require'json/add/range'ruby0 =Range.new(0,2)# 0..2json =JSON.generate(ruby0)# {"json_class":"Range","a":[0,2,false]}ruby1 =JSON.parse(json,create_additions:true)# 0..2ruby1.class# Range

Rational:

require'json/add/rational'ruby0 =Rational(1,3)# 1/3json =JSON.generate(ruby0)# {"json_class":"Rational","n":1,"d":3}ruby1 =JSON.parse(json,create_additions:true)# 1/3ruby1.class# Rational

Regexp:

require'json/add/regexp'ruby0 =Regexp.new('foo')# (?-mix:foo)json =JSON.generate(ruby0)# {"json_class":"Regexp","o":0,"s":"foo"}ruby1 =JSON.parse(json,create_additions:true)# (?-mix:foo)ruby1.class# Regexp

Set:

require'json/add/set'ruby0 =Set.new([0,1,2])# #<Set: {0, 1, 2}>json =JSON.generate(ruby0)# {"json_class":"Set","a":[0,1,2]}ruby1 =JSON.parse(json,create_additions:true)# #<Set: {0, 1, 2}>ruby1.class# Set

Struct:

require'json/add/struct'Customer =Struct.new(:name,:address)# Customerruby0 =Customer.new("Dave","123 Main")# #<struct Customer name="Dave", address="123 Main">json =JSON.generate(ruby0)# {"json_class":"Customer","v":["Dave","123 Main"]}ruby1 =JSON.parse(json,create_additions:true)# #<struct Customer name="Dave", address="123 Main">ruby1.class# Customer

Symbol:

require'json/add/symbol'ruby0 =:foo# foojson =JSON.generate(ruby0)# {"json_class":"Symbol","s":"foo"}ruby1 =JSON.parse(json,create_additions:true)# fooruby1.class# Symbol

Time:

require'json/add/time'ruby0 =Time.now# 2020-05-02 11:28:26 -0500json =JSON.generate(ruby0)# {"json_class":"Time","s":1588436906,"n":840560000}ruby1 =JSON.parse(json,create_additions:true)# 2020-05-02 11:28:26 -0500ruby1.class# Time

Custom JSON Additions¶↑

In addition to the JSON additions provided, you can craft JSON additions of your own, either for Ruby built-in classes or for user-defined classes.

Here’s a user-defined classFoo:

classFooattr_accessor:bar,:bazdefinitialize(bar,baz)self.bar =barself.baz =bazendend

Here’s the JSON addition for it:

# Extend class Foo with JSON addition.classFoo# Serialize Foo object with its class name and argumentsdefto_json(*args)    {JSON.create_id=>self.class.name,'a'=> [bar,baz ]    }.to_json(*args)end# Deserialize JSON string by constructing new Foo object with arguments.defself.json_create(object)new(*object['a'])endend

Demonstration:

require'json'# This Foo object has no custom addition.foo0 =Foo.new(0,1)json0 =JSON.generate(foo0)obj0 =JSON.parse(json0)# Lood the custom addition.require_relative'foo_addition'# This foo has the custom addition.foo1 =Foo.new(0,1)json1 =JSON.generate(foo1)obj1 =JSON.parse(json1,create_additions:true)#   Make a nice display.display =<<~EOT  Generated JSON:    Without custom addition:  #{json0} (#{json0.class})    With custom addition:     #{json1} (#{json1.class})  Parsed JSON:    Without custom addition:  #{obj0.inspect} (#{obj0.class})    With custom addition:     #{obj1.inspect} (#{obj1.class})EOTputsdisplay

Output:

Generated JSON:  Without custom addition:  "#<Foo:0x0000000006534e80>" (String)  With custom addition:     {"json_class":"Foo","a":[0,1]} (String)Parsed JSON:  Without custom addition:  "#<Foo:0x0000000006534e80>" (String)  With custom addition:     #<Foo:0x0000000006473bb8 @bar=0, @baz=1> (Foo)