Introducing the Salesforce Annotated Data Model: A Complete Breakdown

Data models tell stories about your data. Traditional Entity Relationship Diagrams (ERDs) use standard data modeling notations, acting as a language to guide readers toward a shared understanding of how data is structured to support business requirements. Most architects and technical consultants will be familiar with conceptual, logical, and physical models – each of which tells a different story of the data, presenting different levels of detail. 

However, in this article, we’ll unpack a new version of the data model that can add an additional layer of utility for Salesforce professionals. The annotated data model is an ERD with added oomph and should form an important part of the Architect’s toolkit for producing useful technical design artifacts.

What Is an Annotated Data Model?

What I’m calling an annotated data model has been produced in part by Architects prior. Salesforce leader, Matthew Morris introduced his take on documenting data models in his webinar on Architect Diagramming Best Practice. This article builds on Morris’s ideas to share a structure for annotated data models that can be used consistently across Salesforce teams. 

You can think of the annotated data model as an enhanced logical model – a type of ERD that represents actual Salesforce objects using the appropriate notation styles but does not drill down into field-level detail. 

Annotated data models are useful when you need to communicate key technical information relating to the model of the data quickly and efficiently to a technical audience. Annotated data models don’t replace conceptual or physical models. They are not a client-friendly ideation tool, nor are they a development tool. This tool sits in the middle by offering insight into critical, high-level details about the system’s objects and data.

Features of the Annotated Data Model

An annotated data model is created by adding additional information to a standard Salesforce logical model/ERD. It contains the following features:

• Entity Relationship Diagram, modeled with appropriate Salesforce cardinality notation styles.
• Object labels and API names that reference the actual Salesforce objects that will be used in the design.
• OWD setting for each object.
• Projected data volumes for each object.
• Anticipated record-owner persona for each object.
• Indication of objects from which record-triggered automation fires.
• Indication of highly sensitive data.

Annotating the data model with key information helps technical teams build a comprehensive shared understanding of the data model across three dimensions:

• Security and sharing: By adding the OWD, anticipated record owner, and flagging highly sensitive data, your team can more efficiently understand security and sharing implications by object.
• Governor limits: Projected data volumes help architects understand where they may need to consider performance, governor limits, and design for large data volumes. 
• Automation: Seeing where record-triggered automation exists can support understanding the overall system context and make debugging more efficient.  

Annotated Data Model Best Practices

Remember that an annotated data model should help your team digest key information about the data model quickly. That means it must stay easy to read. To preserve the utility of your annotated data model, consider these three best practices:

1. Don’t over-annotate: Try not to add narrative detail to your data model. Instead, use brief annotations and link to more comprehensive technical documentation.
2. Use color sparingly: The use of color can be helpful in drawing attention to certain aspects of the model (i.e. highlighting large data volumes); however, colors should only be used when they have an explicit purpose and add value to the reader. If more than one color is used to draw the reader’s attention, you need a legend. Consider the accessibility of your models for readers who may be color-blind.
3. Focus on annotated data models by functional area: Instead of creating a mega-model with a vast number of entities, create focused models. Consider limiting the number of objects to ~10 and/or creating focused models for specific functional areas of the business (i.e. Program Management Annotated Model)

In addition to the above, ensure you follow conventional data modeling best practices to produce high-quality diagrams that your team will actually use.

Template Annotated Data Model

Are you ready to try your hand at creating your own annotated data model? You can check out my Annotated Data Model template LucidChart to make your own model like the example below:

Final Thoughts

Annotating your data models can help to ensure your ERDs are as useful as possible. Remember to strike a balance between utility and readability by only including vital, high-level information so as to not clutter your diagrams. 

A well-annotated model can help increase your team’s understanding of the data model and shrink time to onboard new team members, build fluency with the design, and debug issues.