We recently developed a work-in-progress style guide for using Omnigraffle to describe Object Relationship Mappings (ORMs) in our Rails applications. We wanted to use simple, standard stencils while being able to exhaustively describe relationships. We also wanted to have them be fairly obvious to developers.

Has One / Belongs To

One of the more common relationships is belongs_to. We decided to show this as a line on the connector toward the belonging model. The sometimes-ambiguous sibling, has_one is shown as a block toward the belonging model. In both cases, we use the unfilled circle/square to show optional.

Has One and Belongs To

Has Many

The has_many relationship is shown as “crows feet” stretching toward the child model. We use the unfilled circle to show optional relationship. The fairly common combination of a belongs_to and has_many is shown as as a combination of the crows feet and line connector.

Has Many and Belongs To

Through, HABTM and Polymorphic

The through relationship, or one that uses a joining table, is show shown as a block using the double -greater and -less than symbols <<through>>. Then we use an arrow to point at the joining model.

The has and belongs to many relationship is shows as double crows-feet with a perpendicular line on each end.

The polymorphic relationship is shown as a rectangle, like a model class, but the name of the relationship is shown in <brackets>. This lets us know the object is not an actual model.

Polymorphic and Through Relationships

And finally, a combination of all the relationships discussed here.

Combination

UPDATE: Jan 8, 2010 -- Changed the way through relationships are described. Swapped the belongs_to and has_many symbols to make room for the has_and_belongs_to_many (habtm) relationship.

Thanks to Greg Sterndale for his feedback.