Нотация объектов JavaScript (JSON)

JSON — это лёгкий формат обмена данными.

Значение JSON может быть одним из следующих:

• Текст в двойных кавычках: "foo".

• Число: 1, 1.0, 2.0e2.

• Логическое значение: true, false.

• Null: null.

• Массив: упорядоченный список значений, заключённый в квадратные скобки:

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

• Объект: набор пар имя/значение, заключённый в фигурные скобки; каждое имя представляет собой текст в двойных кавычках; значения могут быть любыми значениями JSON:

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

Массив или объект JSON может содержать вложенные массивы, объекты и скалярные значения любой глубины:

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

Использование модуля JSON

Чтобы сделать модуль JSON доступным в коде, начните с:

require 'json'

Во всех примерах здесь предполагается, что это уже сделано.

Разбор JSON

Разобрать String с данными JSON можно одним из двух способов:

• JSON.parse(source, opts)

• JSON.parse!(source, opts)

где

• source — объект Ruby.

• opts — объект Hash, содержащий параметры, управляющие как допустимым вводом, так и форматированием вывода.

Разница между этими двумя методами заключается в том, что JSON.parse! пропускает некоторые проверки и может быть небезопасным для некоторых данных source; используйте его только для данных из доверенных источников. Для менее надёжных источников используйте более безопасный метод JSON.parse.

Разбор массивов JSON

Если source — массив JSON, JSON.parse по умолчанию возвращает массив Ruby:

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

Массив JSON может содержать вложенные массивы, объекты и скалярные значения любой глубины:

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

Разбор объектов JSON

Если источник — объект JSON, JSON.parse по умолчанию возвращает Hash Ruby:

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

Объект JSON может содержать вложенные массивы, объекты и скалярные значения любой глубины:

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

Разбор скалярных значений JSON

Если источник — скалярное значение JSON (не массив и не объект), JSON.parse возвращает скалярное значение Ruby.

Строка:

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

Целое число:

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

Число с плавающей точкой:

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

Логическое значение:

ruby = JSON.parse('true')
ruby # => true
ruby.class # => TrueClass
ruby = JSON.parse('false')
ruby # => false
ruby.class # => FalseClass

Null:

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

Параметры разбора

Параметры ввода

Параметр max_nesting (Integer) задаёт максимально допустимую глубину вложенности; по умолчанию используется 100; укажите false, чтобы отключить проверку глубины.

При значении по умолчанию, false:

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

Слишком глубокое вложение:

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

Недопустимое значение:

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

Параметр allow_duplicate_key определяет, следует ли игнорировать повторяющиеся ключи в объектах или вызывать ошибку:

Если не указан:

# 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`

Если задано значение ‘true`

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

Если задано значение ‘false` — значение по умолчанию в будущем:

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

Параметр allow_nan (boolean) определяет, разрешены ли NaN, Infinity и MinusInfinity в source; по умолчанию используется false.

При значении по умолчанию, 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]')

Разрешить:

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

Параметр allow_trailing_comma (boolean) определяет, разрешены ли завершающие запятые в объектах и массивах; по умолчанию используется false.

При значении по умолчанию, false:

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

Если включено:

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

Параметры вывода

Параметр freeze (boolean) определяет, будут ли возвращаемые объекты заморожены; по умолчанию используется false.

Параметр symbolize_names (boolean) определяет, должны ли ключи возвращаемого Hash быть символами; по умолчанию используется false (используются String).

При значении по умолчанию, 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}

Использовать символы:

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

Параметр object_class (Class) задаёт класс Ruby для каждого объекта JSON; по умолчанию используется Hash.

При значении по умолчанию, Hash:

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

Использовать класс OpenStruct:

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

Параметр array_class (Class) задаёт класс Ruby для каждого массива JSON; по умолчанию используется Array.

При значении по умолчанию, Array:

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

Использовать класс Set:

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

Параметр create_additions (boolean) определяет, следует ли использовать дополнения JSON при разборе. См. раздел Дополнения JSON.

Генерация JSON

Чтобы сгенерировать String Ruby с данными JSON, используйте метод JSON.generate(source, opts), где

• source — объект Ruby.

• opts — объект Hash, содержащий параметры, управляющие как допустимым вводом, так и форматированием вывода.

Генерация JSON из массивов

Если источник — массив Ruby, JSON.generate возвращает String, содержащий массив JSON:

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

Массив Ruby array может содержать вложенные массивы, хеши и скалярные значения любой глубины:

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

Генерация JSON из хешей

Если источник — Hash Ruby, JSON.generate возвращает String, содержащий объект JSON:

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

Хеш Ruby array может содержать вложенные массивы, хеши и скалярные значения любой глубины:

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"}'

Генерация JSON из других объектов

Если источник не является массивом или хешем, генерируемые данные JSON зависят от класса источника.

Если источник — Integer или Float Ruby, JSON.generate возвращает String, содержащий число JSON:

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

Если источник — String Ruby, JSON.generate возвращает String, содержащий строку JSON (в двойных кавычках):

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

Если источник — true, false или nil, JSON.generate возвращает String, содержащий соответствующий токен JSON:

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

Если источник не относится ни к одному из перечисленных выше типов, JSON.generate возвращает String, содержащий строковое представление источника в формате JSON:

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

Параметры генерации

Параметры ввода

Параметр allow_nan (boolean) определяет, можно ли генерировать NaN, Infinity и -Infinity; по умолчанию используется false.

При значении по умолчанию, 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)

Разрешить:

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

Параметр allow_duplicate_key (boolean) определяет, разрешены ли хеши с повторяющимися ключами или следует вызывать ошибку. По умолчанию выводится предупреждение об устаревании.

При значении по умолчанию (не задан):

Warning[:deprecated] = true
JSON.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}'

При значении false

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

В версии 3.0 значением по умолчанию станет false.

Параметр max_nesting (Integer) задаёт максимально допустимую глубину вложенности в obj; по умолчанию используется 100.

При значении по умолчанию, 100:

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

Слишком глубокое вложение:

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

Параметры экранирования

Параметр script_safe (boolean) определяет, следует ли экранировать '\u2028', '\u2029' и '/', чтобы объект JSON было безопасно вставлять в теги script.

Параметр ascii_only (boolean) определяет, следует ли экранировать все символы за пределами диапазона ASCII.

Параметры вывода

Параметры форматирования по умолчанию создают наиболее компактные данные JSON: в одну строку и без пробелов.

Чтобы создавать данные JSON в более свободном формате с пробельными символами, можно использовать следующие параметры форматирования. См. также JSON.pretty_generate.

• Параметр array_nl (String) задаёт строку (обычно символ новой строки), вставляемую после каждого массива JSON; по умолчанию используется пустой String, ''.

• Параметр object_nl (String) задаёт строку (обычно символ новой строки), вставляемую после каждого объекта JSON; по умолчанию используется пустой String, ''.

• Параметр indent (String) задаёт строку (обычно пробелы), используемую для отступов; по умолчанию используется пустой String, ''; по умолчанию используется пустой String, ''; не действует, если параметры array_nl или object_nl не задают символы новой строки.

• Параметр space (String) задаёт строку (обычно пробел), вставляемую после двоеточия в каждой паре объекта JSON; по умолчанию используется пустой String, ''.

• Параметр space_before (String) задаёт строку (обычно пробел), вставляемую перед двоеточием в каждой паре объекта JSON; по умолчанию используется пустой String, ''.

В этом примере obj сначала используется для генерации кратчайших данных JSON (без пробелов), а затем — со всеми заданными параметрами форматирования:

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

Результат:

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

Дополнения JSON

Обратите внимание: дополнения JSON следует использовать только с доверенными данными; кроме того, они объявлены устаревшими.

Если преобразовать нестандартный объект из Ruby в JSON и обратно, то получится новая строка вместо исходного объекта:

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

Чтобы сохранить исходный объект, можно использовать дополнения JSON. Дополнение представляет собой расширение класса Ruby, благодаря которому:

• JSON.generate сохраняет больше информации в строке JSON.

• JSON.parse, вызванный с параметром create_additions, использует эту информацию для создания соответствующего объекта Ruby.

В этом примере Range преобразуется в JSON, а затем разбирается обратно в Ruby — как без дополнения для 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})
EOT
puts display

Результаты различаются, как показано ниже:

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)

Модуль JSON включает дополнения для некоторых классов. Также можно создавать собственные дополнения. См. раздел Пользовательские дополнения JSON.

Встроенные дополнения

Модуль JSON включает дополнения для некоторых классов. Чтобы использовать дополнение, загрузите его исходный код с помощью require:

• 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'

Чтобы избежать избыточных знаков препинания, в примерах ниже сгенерированный JSON выводится с помощью puts, а не привычного inspect,

BigDecimal:

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

Complex:

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

Date:

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

DateTime:

require 'json/add/date_time'
ruby0 = DateTime.now # 2020-05-02T10:38:13-05:00
json = 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:00
ruby1.class # DateTime

Exception (и его подклассы, включая RuntimeError):

require 'json/add/exception'
ruby0 = Exception.new('A message') # A message
json = JSON.generate(ruby0) # {"json_class":"Exception","m":"A message","b":null}
ruby1 = JSON.parse(json, create_additions: true) # A message
ruby1.class # Exception
ruby0 = RuntimeError.new('Another message') # Another message
json = JSON.generate(ruby0) # {"json_class":"RuntimeError","m":"Another message","b":null}
ruby1 = JSON.parse(json, create_additions: true) # Another message
ruby1.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..2
json = JSON.generate(ruby0) # {"json_class":"Range","a":[0,2,false]}
ruby1 = JSON.parse(json, create_additions: true) # 0..2
ruby1.class # Range

Rational:

require 'json/add/rational'
ruby0 = Rational(1, 3) # 1/3
json = JSON.generate(ruby0) # {"json_class":"Rational","n":1,"d":3}
ruby1 = JSON.parse(json, create_additions: true) # 1/3
ruby1.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) # Customer
ruby0 = 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 # foo
json = JSON.generate(ruby0) # {"json_class":"Symbol","s":"foo"}
ruby1 = JSON.parse(json, create_additions: true) # foo
ruby1.class # Symbol

Time:

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

Пользовательские дополнения JSON

Помимо предоставляемых дополнений JSON, можно создавать собственные дополнения JSON как для встроенных классов Ruby, так и для классов, определённых пользователем.

Вот определённый пользователем класс Foo:

class Foo
  attr_accessor :bar, :baz
  def initialize(bar, baz)
    self.bar = bar
    self.baz = baz
  end
end

А вот дополнение JSON для него:

# Extend class Foo with JSON addition.
class Foo
  # Serialize Foo object with its class name and arguments
  def to_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.
  def self.json_create(object)
    new(*object['a'])
  end
end

Демонстрация:

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})
EOT
puts display

Результат:

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)