Type Refinement Traits

This wiki contains a mapping between Smithy Type refinement traits and generated Ruby code.

box Trait

Indicates that a shape is boxed. When a structure member is marked with this trait or the shape targeted by a structure member is marked with the box trait, the member may or may not contain a value, and the member has no default value. Boolean, byte, short, integer, long, float, and double shapes are only considered boxed if they are marked with the box trait. All other shapes are always considered boxed. Non-boxed defaults should be set as early as possible.

structure Type {
    @box
    integer BoxedInteger

    integer NotBoxedInteger
}

For output, the default values are set in the protocol parsers. The generated code is:

# parsers.rb

class Type
  def self.parse(json)
    data = Types::Type.new
    data.boxed_integer = json['boxed_integer'] # may be nil
    data.not_boxed_integer = json['not_boxed_integer'] || 0
    data
  end
end

Parsers are boxed by default, as the default value for boxed_integer for Types::Type is nil. For Integer (Byte, Short, Integer, Long, Float, Double) and Boolean (Boolean) Ruby types, the default values without the box trait are 0 and false respectively.

For input, the default is set in the param builder. The generated code is:

module Type
  def self.build(params, context: '')
    type = Types::Type.new
    type.boxed_integer = params[:boxed_integer]
    type.not_boxed_integer = params[:not_boxed_integer] || 0
    type
  end
end

error Trait

Indicates that a structure shape represents an error. Structures marked with this trait have a type definition, an error class, and a parser to populate the error structure.

@error("client")
structure ThrottlingError {}

The generated code is:

# types.rb
ThrottlingError = Struct.new(
  keyword_init: true
)

# errors.rb
class ThrottlingError < ApiClientError
  def initialize(http_resp:, **kwargs)
    @data = Parsers::ThrottlingError.parse(http_resp)
    kwargs[:message] = @data.message if @data.respond_to?(:message)
    super(http_resp: http_resp, **kwargs)
  end

  # @return [Types::ThrottlingError]
  attr_reader :data
end

# parsers.rb
class ThrottlingError
  def self.parse(http_resp)
    json = Seahorse::JSON.load(http_resp.body)
    data = Types::ThrottlingError.new
    data
  end
end

The Seahorse error parser determines that the response has an error, and delegates to the error class in errors.rb. Then the error’s class uses the parser in parsers.rb to populate a structure defined in types.rb. Depending on the value passed to the @error trait, the error will inherit from ApiClientError or ApiServerError.

sparse Trait

Indicates that lists and maps MAY contain null values. The protocol’s null values are represented by Ruby’s nil value. For shapes without this trait, depending on the protocol, nil values are omitted when building or parsing the list element or map value. For example, check if unless element.nil? or unless value.nil? before populating the data structure.

@sparse
list SparseList {
    member: String
}

@sparse
map SparseMap {
    key: String,
    value: String
}

The generated code is:

# parsers.rb

class SparseList
  def self.parse(list)
    data = []
    list.each do |element|
      data << element # unless element.nil?
    end
    data
  end
end

class SparseMap
  def self.parse(map)
    data = {}
    map.each do |key, value|
      data[key] = value # unless value.nil?
    end
    data
  end
end

This works similarly for protocol builders.