V1.3: Custom Schema
We can take data integrity a step further: we can optionally define our own entity internal schema.
Custom schema is optional for SQL databases, while it's mandatory for entities without a database table, or while using with a non-SQL database.
Custom schema takes precedence over automatic schema. If we use custom schema, we need to manually add all the new columns from the corresponding SQL database table.
Default mode
# lib/bookshelf/entities/user.rb
class User < Hanami::Entity
EMAIL_FORMAT = /\@/
attributes do
attribute :id, Types::Int
attribute :name, Types::String
attribute :email, Types::String.constrained(format: EMAIL_FORMAT)
attribute :age, Types::Int.constrained(gt: 18)
attribute :profile, Types::Entity(Profile)
attribute :codes, Types::Collection(Types::Coercible::Int)
attribute :comments, Types::Collection(Comment)
attribute :created_at, Types::Time
attribute :updated_at, Types::Time
end
end
Let’s instantiate it with proper values:
user = User.new(name: "Luca", age: 35, email: "luca@hanami.test")
user.name # => "Luca"
user.age # => 35
user.email # => "luca@hanami.test"
user.codes # => nil
user.comments # => nil
It can coerce values:
user = User.new(codes: ["123", "456"])
user.codes # => [123, 456]
Other entities can be passed as concrete instance:
user = User.new(comments: [Comment.new(text: "cool")])
user.comments
# => [#<Comment:0x007f966be20c58 @attributes={:text=>"cool"}>]
Or as data:
user = User.new(comments: [{text: "cool"}])
user.comments
# => [#<Comment:0x007f966b689e40 @attributes={:text=>"cool"}>]
It enforces data integrity via exceptions:
User.new(email: "foo") # => TypeError: "foo" (String) has invalid type for :email
User.new(comments: [:foo]) # => TypeError: :foo must be coercible into Comment
Strict mode
# lib/bookshelf/entities/user.rb
class User < Hanami::Entity
EMAIL_FORMAT = /\@/
attributes :strict do
attribute :id, Types::Strict::Int
attribute :name, Types::Strict::String
attribute :email, Types::Strict::String.constrained(format: EMAIL_FORMAT)
attribute :age, Types::Strict::Int.constrained(gt: 18)
end
end
Let’s instantiate it with proper values:
user = User.new(id: 1, name: "Luca", age: 35, email: "luca@hanami.test")
user.id # => 1
user.name # => "Luca"
user.age # => 35
user.email # => "luca@hanami.test"
It cannot be instantiated with missing keys
User.new
# => ArgumentError: :id is missing in Hash input
User.new(id: 1, name: "Luca", age: 35)
# => ArgumentError: :email is missing in Hash input
Or with nil:
User.new(id: 1, name: nil, age: 35, email: "luca@hanami.test")
# => TypeError: nil (NilClass) has invalid type for :name violates constraints (type?(String, nil) failed)
It accepts strict values and it doesn’t attempt to coerce:
User.new(id: "1", name: "Luca", age: 35, email: "luca@hanami.test")
# => TypeError: "1" (String) has invalid type for :id violates constraints (type?(Integer, "1") failed)
It enforces data integrity via exceptions:
User.new(id: 1, name: "Luca", age: 1, email: "luca@hanami.test")
# => TypeError: 1 (Integer) has invalid type for :age violates constraints (gt?(18, 1) failed)
User.new(id: 1, name: "Luca", age: 35, email: "foo")
# => TypeError: "foo" (String) has invalid type for :email violates constraints (format?(/\@/, "foo") failed)
Learn more about data types in the dedicated article.