Home

Attributor is a powerful Ruby library for describing and managing complex data structure schemas. As a type-management library it has many different uses. In a general sense, it can be used anywhere where it is important to define complex data structures, and ensure that data for those structure can be validated (with properly descriptive errors), coerced and properly described in a machine readable manner.

In essence, it is useful i any internal or external Interface definition where data can flow in or out of it, and validation/coercing/error-reporting/schema-definition must be done (without unnecessary boilerplate). Here are a couple of examples of common uses:

• Application Configuration: defining the structures to expect for configuration of applications, validating received values (i.e. through config files, env variables..), properly reporting errors, and coercing values into the right types.
• External APIs, such as Web Applications: defining the headers/params and body structures expected in any incoming API calls, reporting of errors, as well as documenting the expected response schemas. This is how the Praxis API framework, for example, works.

Here's a hypothetical example of you could define the schema for a Blog media-type structure for your Web application:

class Blog < Attributor::Struct
  attributes do
    attribute :id, Integer,
      description: 'Unique identifier'
    attribute :name, String,
      description: 'Short name'
    attribute :href, URI, path: |^/blogs|
      description: 'Href for use with this API'
    attribute :description, String,
      description: 'Longer description'
    attribute :url, String,
      description: 'URL for a web browser'

    attribute :timestamps do
      attribute :created_at, DateTime
      attribute :updated_at, DateTime
    end

    attribute :tags, Collection.of(String),
      description: 'Array of tags'

    attribute :recent_posts, Collection.of(Post),
      description: 'Array of recent related Post resources'
    attribute :owner, User,
      description: 'Related User resource'
  end

You can also watch a few hands-on screencasts in the following youtube channel:

Further details and type reference

• Attributes vs. Types
• Getting Started
• Using the main Features
  • Defining attributes and types
  • Instantiating and loading data
  • Validating data
  • Dumping data
  • Generating examples
  • Describing schemas
  • Other
    • id and family
    • anonymous_type
• Creating your own types
• Reference Guide:
  • Attribute
  • Primitive Types: Simple, terminal types provided by the library.
    • Boolean
    • Integer
    • String
    • Symbol
    • BigDecimal
    • Float
    • DateTime
    • Date
    • Time
    • Class
    • Object
  • Basic Types: Base building block types to compose other types into arrays or substructures
    • Hash
    • Model and Struct
    • Collection
  • Utility types: A few utility types that are commonly used, which wrap other basic or primitive types
    • URI
    • TempFile
    • CSV
    • Ids
    • Regexp
    • FieldSelector