Type Refinement Traits

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

default Trait

Indicates that structure member has a default value. See Smithy Documentation for details.

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 = Hearth::JSON.load(http_resp.body)
    data = Types::ThrottlingError.new
    data
  end
end

The Hearth 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. Read more on Errors.

required Trait

Marks a structure member as required, meaning a value for the member MUST be present and not set to null.

structure MyStructure {
    @required
    foo: FooString,
}

input Trait

Specializes a structure for use only as the input of a single operation. The input trait is useful for modeling but is not used during SDK code generation.

output Trait

Specializes a structure for use only as the output of a single operation. The output trait is useful for modeling but is not used during SDK code generation.

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.