module JSON::Serializable

Overview

The JSON::Serializable module automatically generates methods for JSON serialization when included.

Example

require "json"

class Location
  include JSON::Serializable

  @[JSON::Field(key: "lat")]
  property latitude : Float64

  @[JSON::Field(key: "lng")]
  property longitude : Float64
end

class House
  include JSON::Serializable
  property address : String
  property location : Location?
end

house = House.from_json(%({"address": "Crystal Road 1234", "location": {"lat": 12.3, "lng": 34.5}}))
house.address  # => "Crystal Road 1234"
house.location # => #<Location:0x10cd93d80 @latitude=12.3, @longitude=34.5>
house.to_json  # => %({"address":"Crystal Road 1234","location":{"lat":12.3,"lng":34.5}})

houses = Array(House).from_json(%([{"address": "Crystal Road 1234", "location": {"lat": 12.3, "lng": 34.5}}]))
houses.size    # => 1
houses.to_json # => %([{"address":"Crystal Road 1234","location":{"lat":12.3,"lng":34.5}}])

Usage

Including JSON::Serializable will create #to_json and self.from_json methods on the current class, and a constructor which takes a JSON::PullParser. By default, these methods serialize into a json object containing the value of every instance variable, the keys being the instance variable name. Most primitives and collections supported as instance variable values (string, integer, array, hash, etc.), along with objects which define to_json and a constructor taking a JSON::PullParser. Union types are also supported, including unions with nil. If multiple types in a union parse correctly, it is undefined which one will be chosen.

To change how individual instance variables are parsed and serialized, the annotation JSON::Field can be placed on the instance variable. Annotating property, getter and setter macros is also allowed.

class A
  include JSON::Serializable

  @[JSON::Field(key: "my_key", emit_null: true)]
  getter a : Int32?
end

JSON::Field properties:

Deserialization also respects default values of variables:

struct A
  include JSON::Serializable
  @a : Int32
  @b : Float64 = 1.0
end

A.from_json(%<{"a":1}>) # => A(@a=1, @b=1.0)

Extensions: JSON::Serializable::Strict and JSON::Serializable::Unmapped.

If the JSON::Serializable::Strict module is included, unknown properties in the JSON document will raise a parse exception. By default the unknown properties are silently ignored. If the JSON::Serializable::Unmapped module is included, unknown properties in the JSON document will be stored in a Hash(String, JSON::Any). On serialization, any keys inside json_unmapped will be serialized and appended to the current json object.

struct A
  include JSON::Serializable
  include JSON::Serializable::Unmapped
  @a : Int32
end

a = A.from_json(%({"a":1,"b":2})) # => A(@json_unmapped={"b" => 2_i64}, @a=1)
a.to_json                         # => {"a":1,"b":2}

Class annotation JSON::Serializable::Options

supported properties:

@[JSON::Serializable::Options(emit_nulls: true)]
class A
  include JSON::Serializable
  @a : Int32?
end

Defined in:

json/serialization.cr

Constructors

Instance Method Summary

Constructor Detail

def self.new(*, __pull_for_json_serializable pull : JSON::PullParser) #

[View source]

Instance Method Detail

def to_json(json : JSON::Builder) #

[View source]