Stannum

A library for defining and validating data structures.

Read The Documentation

Stannum provides a framework-independent toolkit for defining structured data entities and validations. It provides a middle ground between unstructured data (raw Hashes, Structs, or libraries like Hashie) and full frameworks like ActiveModel.

It defines the following objects:

• Constraints: A validator object that responds to #match, #matches? and #errors_for for a given object.
• Contracts: A collection of constraints about an object or its properties. Obeys the Constraint interface.
• Errors: Data object for storing validation errors. Supports arbitrary nesting of errors.
• Entities: Defines a mutable data object with a specified set of typed attributes.

Stannum is not tied to any framework. You can create constraints and contracts to validate Ruby objects and Entities, data structures such as Arrays, Hashes, and Sets, and even framework objects such as ActiveRecord::Models and Mongoid::Documents.

Still, most projects and applications use one framework to handle their data. Why use Stannum constraints?

• Composability: Because Stannum contracts are their own objects, they can be combined together. Reuse validation logic without duplicating code or defining abstract ancestor classes .
• Polymorphism: Your data validation is separate from your model definitions. This gives you two major advantages over the traditional approach:
  • You can use the same contract to validate different objects. Do you have a shared concern that cuts across multiple domain objects, such as attaching images, having comments, or creating an audit trail? You can write one contract for the concern and apply that same contract to each applicable model or object.
  • You can use different contracts to validate the same object in different contexts. Need different validations for a regular user versus an admin? Need to handle published articles more strictly than drafts? Need to provide custom validations for each step in your state machine? Stannum has you covered, and because contracts are composable, you can pull in the constraints you need without duplicating your logic.
• Separation of Concerns: Your data validation is independent from your entities. This means that you can use the same tools to validate anything from controller parameters to models to configuration files.

Stannum is tested against Ruby (MRI) 3.1 through 3.4.

Code documentation is generated using YARD, and can be generated locally using the yard gem.

The full documentation is available via GitHub Pages, and includes the code documentation as well as a deeper explanation of Stannum's features and design philosophy. It also includes documentation for prior versions of the gem.

To generate documentation locally, see the SleepingKingStudios::Docs gem.

Copyright (c) 2019-2025 Rob Smith

Stannum is released under the MIT License.

The canonical repository for this gem is located at https://github.com/sleepingkingstudios/stannum.

To report a bug or submit a feature request, please use the Issue Tracker.

To contribute code, please fork the repository, make the desired updates, and then provide a Pull Request. Pull requests must include appropriate tests for consideration, and all code must be properly formatted.

Please note that the Stannum project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.