Data

Tools

Indexes

Applications

Experiments

Ruby

A summary of data about the Ruby ecosystem.

https://github.com/ruby/json

JSON implementation for Ruby
https://github.com/ruby/json

Keywords

json json-parser ruby

Keywords from Contributors

rubygems activerecord activejob mvc rack documentation-tool rspec ruby-gem sinatra libyaml

Last synced: about 24 hours ago
JSON representation

Repository metadata

JSON implementation for Ruby

README.md

JSON implementation for Ruby

CI

Description

This is an implementation of the JSON specification according to RFC 7159
http://www.ietf.org/rfc/rfc7159.txt .

The JSON generator generate UTF-8 character sequences by default.
If an :ascii_only option with a true value is given, they escape all
non-ASCII and control characters with \uXXXX escape sequences, and support
UTF-16 surrogate pairs in order to be able to generate the whole range of
unicode code points.

All strings, that are to be encoded as JSON strings, should be UTF-8 byte
sequences on the Ruby side. To encode raw binary strings, that aren't UTF-8
encoded, please use the to_json_raw_object method of String (which produces
an object, that contains a byte array) and decode the result on the receiving
endpoint.

Installation

Install the gem and add to the application's Gemfile by executing:

$ bundle add json

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install json

Basic Usage

To use JSON you can

require 'json'

Now you can parse a JSON document into a ruby data structure by calling

JSON.parse(document)

If you want to generate a JSON document from a ruby data structure call

JSON.generate(data)

You can also use the pretty_generate method (which formats the output more
verbosely and nicely) or fast_generate (which doesn't do any of the security
checks generate performs, e. g. nesting deepness checks).

Casting non native types

JSON documents can only support Hashes, Arrays, Strings, Integers and Floats.

By default if you attempt to serialize something else, JSON.generate will
search for a #to_json method on that object:

Position = Struct.new(:latitude, :longitude) do
  def to_json(state = nil, *)
    JSON::State.from_state(state).generate({
      latitude: latitude,
      longitude: longitude,
    })
  end
end

JSON.generate([
  Position.new(12323.234, 435345.233),
  Position.new(23434.676, 159435.324),
]) # => [{"latitude":12323.234,"longitude":435345.233},{"latitude":23434.676,"longitude":159435.324}]

If a #to_json method isn't defined on the object, JSON.generate will fallback to call #to_s:

JSON.generate(Object.new) # => "#<Object:0x000000011e768b98>"

Both of these behavior can be disabled using the strict: true option:

JSON.generate(Object.new, strict: true) # => Object not allowed in JSON (JSON::GeneratorError)
JSON.generate(Position.new(1, 2)) # => Position not allowed in JSON (JSON::GeneratorError)

JSON::Coder

Since #to_json methods are global, it can sometimes be problematic if you need a given type to be
serialized in different ways in different locations.

Instead it is recommended to use the newer JSON::Coder API:

module MyApp
  API_JSON_CODER = JSON::Coder.new do |object, is_object_key|
    case object
    when Time
      object.iso8601(3)
    else
      object
    end
  end
end

puts MyApp::API_JSON_CODER.dump(Time.now.utc) # => "2025-01-21T08:41:44.286Z"

The provided block is called for all objects that don't have a native JSON equivalent, and
must return a Ruby object that has a native JSON equivalent.

It is also called for objects that do have a JSON equivalent, but are used as Hash keys, for instance { 1 => 2},
as well as for strings that aren't valid UTF-8:

coder = JSON::Combining.new do |object, is_object_key|
  case object
  when String
    if !string.valid_encoding? || string.encoding != Encoding::UTF_8
      Base64.encode64(string)
    else
      string
    end
  else
    object
  end
end

Combining JSON fragments

To combine JSON fragments into a bigger JSON document, you can use JSON::Fragment:

posts_json = cache.fetch_multi(post_ids) do |post_id|
  JSON.generate(Post.find(post_id))
end
posts_json.map! { |post_json| JSON::Fragment.new(post_json) }
JSON.generate({ posts: posts_json, count: posts_json.count })

Round-tripping arbitrary types

[!CAUTION]
You should never use JSON.unsafe_load nor JSON.parse(str, create_additions: true) to parse untrusted user input,
as it can lead to remote code execution vulnerabilities.

To create a JSON document from a ruby data structure, you can call
JSON.generate like that:

json = JSON.generate [1, 2, {"a"=>3.141}, false, true, nil, 4..10]
# => "[1,2,{\"a\":3.141},false,true,null,\"4..10\"]"

To get back a ruby data structure from a JSON document, you have to call
JSON.parse on it:

JSON.parse json
# => [1, 2, {"a"=>3.141}, false, true, nil, "4..10"]

Note, that the range from the original data structure is a simple
string now. The reason for this is, that JSON doesn't support ranges
or arbitrary classes. In this case the json library falls back to call
Object#to_json, which is the same as #to_s.to_json.

It's possible to add JSON support serialization to arbitrary classes by
simply implementing a more specialized version of the #to_json method, that
should return a JSON object (a hash converted to JSON with #to_json) like
this (don't forget the *a for all the arguments):

class Range
  def to_json(*a)
    {
      'json_class'   => self.class.name, # = 'Range'
      'data'         => [ first, last, exclude_end? ]
    }.to_json(*a)
  end
end

The hash key json_class is the class, that will be asked to deserialise the
JSON representation later. In this case it's Range, but any namespace of
the form A::B or ::A::B will do. All other keys are arbitrary and can be
used to store the necessary data to configure the object to be deserialised.

If the key json_class is found in a JSON object, the JSON parser checks
if the given class responds to the json_create class method. If so, it is
called with the JSON object converted to a Ruby hash. So a range can
be deserialised by implementing Range.json_create like this:

class Range
  def self.json_create(o)
    new(*o['data'])
  end
end

Now it possible to serialise/deserialise ranges as well:

json = JSON.generate [1, 2, {"a"=>3.141}, false, true, nil, 4..10]
# => "[1,2,{\"a\":3.141},false,true,null,{\"json_class\":\"Range\",\"data\":[4,10,false]}]"
JSON.parse json
# => [1, 2, {"a"=>3.141}, false, true, nil, 4..10]
json = JSON.generate [1, 2, {"a"=>3.141}, false, true, nil, 4..10]
# => "[1,2,{\"a\":3.141},false,true,null,{\"json_class\":\"Range\",\"data\":[4,10,false]}]"
JSON.unsafe_load json
# => [1, 2, {"a"=>3.141}, false, true, nil, 4..10]

JSON.generate always creates the shortest possible string representation of a
ruby data structure in one line. This is good for data storage or network
protocols, but not so good for humans to read. Fortunately there's also
JSON.pretty_generate (or JSON.pretty_generate) that creates a more readable
output:

 puts JSON.pretty_generate([1, 2, {"a"=>3.141}, false, true, nil, 4..10])
 [
   1,
   2,
   {
     "a": 3.141
   },
   false,
   true,
   null,
   {
     "json_class": "Range",
     "data": [
       4,
       10,
       false
     ]
   }
 ]

There are also the methods Kernel#j for generate, and Kernel#jj for
pretty_generate output to the console, that work analogous to Core Ruby's p and
the pp library's pp methods.

Development

Prerequisites

  1. Clone the repository
  2. Install dependencies with bundle install

Testing

The full test suite can be run with:

bundle exec rake test

Release

Update the lib/json/version.rb file.

rbenv shell 2.6.5
rake build
gem push pkg/json-2.3.0.gem

rbenv shell jruby-9.2.9.0
rake build
gem push pkg/json-2.3.0-java.gem

Author

Florian Frank mailto:flori@ping.de

License

Ruby License, see https://www.ruby-lang.org/en/about/license.txt.

Download

The latest version of this library can be downloaded at

Online Documentation should be located at

Owner metadata

GitHub Events

Total
Last Year

Committers metadata

Last synced: 3 days ago

Total Commits: 1,419
Total Committers: 121
Avg Commits per committer: 11.727
Development Distribution Score (DDS): 0.708

Commits in past year: 266
Committers in past year: 26
Avg Commits per committer in past year: 10.231
Development Distribution Score (DDS) in past year: 0.462

Name Email Commits
Florian Frank f****i@p****e 415
Jean Boussier j****r@g****m 351
Hiroshi SHIBATA h****t@r****g 119
Nobuyoshi Nakada n****u@r****g 82
Étienne Barrié e****e@g****m 45
Charles Oliver Nutter h****s@h****m 38
Scott Myron s****n@g****m 26
Benoit Daloze e****p@g****m 23
Yusuke Endoh m****e@r****g 19
Kenta Murata m****n@m****p 18
BurdetteLamar b****r@y****m 17
NARUSE, Yui n****e@a****p 14
Zachary Scott e@z****o 13
Marc-Andre Lafortune g****b@m****a 10
Vipul A M v****d@g****m 10
Aaron Patterson t****e@r****g 10
kares s****f@k****g 9
Daniel Luz d****v@m****m 7
Watson w****8@g****m 7
tompng t****n@g****m 7
Michael Mac-Vicar m****r@g****m 6
Takashi Kokubun t****n@g****m 5
Sho Hashimoto s****t@g****m 5
MSP-Greg G****s@g****m 4
Olle Jonsson o****n@g****m 4
Per Lundberg p****g@e****m 4
GrantBirki g****e@g****m 4
eno e****o@o****g 4
Shota Fukumori (sora_h) s****4@g****m 4
Ryan Davis r****y@z****m 4
and 91 more...

Committer domains:

Issue and Pull Request metadata

Last synced: 3 days ago

Total issues: 205
Total pull requests: 462
Average time to close issues: over 2 years
Average time to close pull requests: 2 months
Total issue authors: 165
Total pull request authors: 68
Average comments per issue: 3.5
Average comments per pull request: 1.81
Merged pull request: 351
Bot issues: 0
Bot pull requests: 2

Past year issues: 27
Past year pull requests: 153
Past year average time to close issues: 1 day
Past year average time to close pull requests: 3 days
Past year issue authors: 25
Past year pull request authors: 28
Past year average comments per issue: 4.0
Past year average comments per pull request: 1.35
Past year merged pull request: 111
Past year bot issues: 0
Past year bot pull requests: 2

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/ruby/json

Top Issue Authors

  • headius (9)
  • mperham (7)
  • byroot (7)
  • HoneyryderChuck (3)
  • eregon (3)
  • myronmarston (3)
  • mernen (3)
  • nurse (3)
  • vakuum (2)
  • david22swan (2)
  • jterapin (2)
  • Wardrop (2)
  • nvasilevski (2)
  • ghost (2)
  • hsbt (2)

Top Pull Request Authors

  • byroot (103)
  • casperisfine (95)
  • hsbt (34)
  • samyron (31)
  • nobu (25)
  • etiennebarrie (25)
  • eregon (19)
  • radiospiel (12)
  • headius (10)
  • tompng (9)
  • GrantBirki (6)
  • k0kubun (5)
  • peterzhu2118 (4)
  • robinetmiller (4)
  • vakuum (3)

Top Issue Labels

  • bug (15)
  • fixed (11)
  • new feature (9)
  • jruby (7)
  • rfc (3)
  • worksforme (3)
  • 3rd party bug (1)
  • duplicate (1)

Top Pull Request Labels

  • github_actions (2)
  • documentation (2)
  • new feature (2)
  • bug (2)
  • dependencies (2)
  • fixed (1)

Package metadata

gem.coop: json

This is a JSON implementation as a Ruby extension in C.

gem.coop: json_pure

This is a JSON implementation in pure Ruby.

  • Homepage: https://ruby.github.io/json
  • Documentation: http://www.rubydoc.info/gems/json_pure/
  • Licenses: Ruby
  • Latest release: 2.8.1 (published over 1 year ago)
  • Last Synced: 2026-04-26T20:01:52.251Z (4 days ago)
  • Versions: 82
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Downloads: 70,211,638 Total
  • Docker Downloads: 549,489,576
  • Rankings:
    • Dependent repos count: 0.0%
    • Dependent packages count: 0.0%
    • Average: 0.147%
    • Docker downloads count: 0.179%
    • Downloads: 0.408%
  • Maintainers (5)
debian-13: ruby-json

  • Homepage: https://ruby.github.io/json
  • Documentation: https://packages.debian.org/trixie/ruby-json
  • Licenses: other
  • Latest release: 2.9.1+dfsg-1 (published 3 months ago)
  • Last Synced: 2026-03-14T18:10:32.321Z (about 2 months ago)
  • Versions: 1
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
    • Dependent repos count: 0.0%
    • Dependent packages count: 0.0%
    • Average: 0.205%
    • Forks count: 0.268%
    • Stargazers count: 0.55%
rubygems.org: json

This is a JSON implementation as a Ruby extension in C.

rubygems.org: json_pure

This is a JSON implementation in pure Ruby.

  • Homepage: https://ruby.github.io/json
  • Documentation: http://www.rubydoc.info/gems/json_pure/
  • Licenses: Ruby
  • Latest release: 2.8.1 (published over 1 year ago)
  • Last Synced: 2026-04-28T03:01:18.501Z (3 days ago)
  • Versions: 82
  • Dependent Packages: 599
  • Dependent Repositories: 28,645
  • Downloads: 70,223,276 Total
  • Docker Downloads: 549,489,576
  • Rankings:
    • Dependent packages count: 0.076%
    • Dependent repos count: 0.21%
    • Docker downloads count: 0.232%
    • Downloads: 0.361%
    • Average: 0.773%
    • Forks count: 1.496%
    • Stargazers count: 2.261%
  • Maintainers (5)
proxy.golang.org: github.com/ruby/json

  • Homepage:
  • Documentation: https://pkg.go.dev/github.com/ruby/json#section-documentation
  • Licenses: other
  • Latest release: v2.19.4+incompatible (published 12 days ago)
  • Last Synced: 2026-04-26T20:01:52.685Z (4 days ago)
  • Versions: 102
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
    • Dependent packages count: 5.442%
    • Average: 5.624%
    • Dependent repos count: 5.807%
rubygems.org: ed-precompiled_json

This is a JSON implementation as a Ruby extension in C.

  • Homepage: https://github.com/ruby/json
  • Documentation: http://www.rubydoc.info/gems/ed-precompiled_json/
  • Licenses: Ruby
  • Latest release: 2.15.1 (published 7 months ago)
  • Last Synced: 2026-04-26T20:01:51.094Z (4 days ago)
  • Versions: 3
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Downloads: 1,074 Total
  • Rankings:
    • Forks count: 1.459%
    • Stargazers count: 2.129%
    • Dependent packages count: 14.231%
    • Average: 30.696%
    • Dependent repos count: 43.59%
    • Downloads: 92.073%
  • Maintainers (1)
gem.coop: ed-precompiled_json

This is a JSON implementation as a Ruby extension in C.

  • Homepage: https://github.com/ruby/json
  • Documentation: http://www.rubydoc.info/gems/ed-precompiled_json/
  • Licenses: Ruby
  • Latest release: 2.15.1 (published 7 months ago)
  • Last Synced: 2026-04-26T20:01:51.101Z (4 days ago)
  • Versions: 3
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Downloads: 1,074 Total
  • Rankings:
    • Dependent repos count: 0.0%
    • Dependent packages count: 0.0%
    • Average: 33.154%
    • Downloads: 99.463%
  • Maintainers (1)

Dependencies

Gemfile rubygems
  • all_images ~> 0
  • rake >= 0
  • test-unit >= 0
.github/workflows/ci.yml actions
  • actions/checkout v2 composite
  • ruby/setup-ruby v1 composite
json.gemspec rubygems
.github/workflows/sync-ruby.yml actions
  • actions/checkout v6 composite
  • actions/create-github-app-token v2 composite
  • convictional/trigger-workflow-and-wait v1.6.5 composite

Score: 34.76163820066454