Ruby JSON serialization/deserialization

[ethnt]

Serialization/deserialization

Depending on the data object structure, the serialization method should be straightforward enough using the standard library JSON gem. Previously the oj gem was preferred here for performance reasons, but the JSON gem was recently significantly optimized, where it is now faster than oj.

Dealing with snake_case and CamelCase

If we are storing some sort of information about each property in our data objects, we can also store an "external name" for the property and have a different one for the actual attribute (e.g., the attribute per_page would have perPage as the external name). The actual conversion is fairly easy:

def snake_to_camel(str)
  str.split("_").map.with_index do |segment, idx|
    next segment if idx.zero?
    segment.capitalize
  end.join
end

def camel_to_snake(str)
  str.tr("::", "/")
    .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
    .gsub(/([a-z\d])([A-Z])/, '\1_\2')
    .tr("-", "_")
    .downcase
end

[amckinney]

The actual conversion is fairly easy

Fortunately, we won't need to actually transform the "external name" for any given property with the Ruby code above -- all of this is predetermined in the IR that the Ruby generator acts upon so we can just generate the models in whatever way we need. I see a couple approaches so far:

1. Explicit mappers

class Customer
  attr_accessor :full_name, :email_address
  
  def initialize(attributes = {})
    @full_name = attributes[:full_name]
    @email_address = attributes[:email_address]
  end
  
  def as_json(options = {})
    {
      'name' => @full_name,
      'email' => @email_address
    }
  end
  
  def self.from_json(json)
    data = JSON.parse(json)
    new(
      full_name: data['name'],
      email_address: data['email']
    )
  end
end

2. Metaprogramming (w/ base class)

A BaseModel class (or something similar) could implement the to_json and from_json methods based on the attributes.

class Customer < BaseModel
  map_attribute :full_name, 'name'
  map_attribute :email_address, 'email'
end

I'm not sure if we already have other map_attribute use cases in mind, but (2) seems like a simple way to consolidate all of the serialization logic in one place, but still make it easy for readers to understand how the attributes are mapped to/from JSON.

With that said, we could also make it easy for the serialization layer to track additional properties and surface them in each class.

What are your thoughts @ethnt?

[amckinney]

For what it's worth, I can also see a combination of both here -- simple objects could lean on the BaseModel, but more complex serialization logic could override the to_json or from_json methods. This is similar to what we do for discriminated unions in PHP here.

[amckinney]

Discussed offline - it looks like we're honing in on some representation like the BaseModel approach (i.e. something imported from Internal::Types::Model).

We'll likely include a field attribute like api_name, external_name, json_name, or wire_name whenever the snake_case property doesn't match how the value is serialized in JSON.