Data Requirements: Why They're Awesome and How to Work with Them (Part 2)

2025-06-23 12:57 Business analysis

In the first part, we discussed what data requirements are and where to start working with them.

4) The second key component of data requirements is the data dictionary (also called a data glossary).

In general, the data model itself would already be quite helpful both for you and the development team. But if time allows, a data dictionary becomes a fantastic addition.

The data dictionary is best presented in a table format. In this table, I recommend including the following details for each data entity:

Attributes (their names).
A description of each attribute in plain language, i.e., an explanation of what this attribute means in terms of the system’s information.
Is the attribute mandatory for every instance of the data entity? In other words, can the attribute be left empty? Using the Excel analogy mentioned earlier: could there be rows on the tab dedicated to this entity where the cell for this attribute is blank?
What is the data type of the attribute? For example, integer, floating-point number, text (either free-form or constrained to a narrower format), image, video, boolean (yes/no), enumeration (one value from a predefined set), date, etc. We will look at some of these types in the examples below.
Additional details: format specifics, data source, and anything else you find useful to specify.

Here is the data dictionary for our example, along with explanations of some interesting points as we go:

Required?

Why isn’t the Image attribute mandatory? After discussions with the stakeholders, we determined that not all Products have images if the admin does not add one when creating the Product. Naturally, this needs to be reflected in behavioral requirements: how to display a Product card without an image.

All other attributes cannot be empty under any circumstances: "Added by" obviously cannot be empty; "Title", "Description," and "Price" were agreed with the client to be mandatory (meaning these fields are required when creating a Product).

Data Types:

"Added by" is specified as a User. This is a method I like to use when referring to linking attributes. It shows that this is a reference to a User — an object of the User class.

Additional Details:
Usually, this column describes format specifics, especially those that will be important to consider in behavioral requirements.

For the Image attribute, the file type and maximum file size are specified. This will directly affect whether the system will allow the admin to upload that image when creating a Product. Other parameters could also be specified, such as dimensions and aspect ratios, but in this example, no such restrictions exist (meaning the system must be able to accept and properly display images of any size and ratio in the Product card).

"Added by" has no format specifics — it’s just a reference to the admin who created the Product.

For text attributes, the maximum length is indicated. This means the system will not allow entering text longer than that during Product creation. If there were no such restrictions (either from the perspective of what users are allowed to enter or how to display arbitrarily long text in lists and cards), we wouldn’t discuss or document these specifics with stakeholders.

A similar approach applies to the Price, which is a floating-point number. We discussed and agreed with stakeholders that the price cannot be lower than 0.01 and higher than 1000.00, and it must be entered with two decimal places. Thus, admins cannot specify a price outside this range when creating a Product. Such constraints can be relevant for numbers, dates, times, and anything that can have minimum and maximum values.

For the User entity, the attribute details are straightforward, but let’s look at the additional details:

It’s explained that these data will enter the system in a non-obvious way — that is, not entered through the system’s UI by users. A note about the data source is included so developers understand how these data should appear in the system. No other description is needed here for this example. In a more complex case, we could have specific formats for Login and Password (for instance, referring to a standard email format for Login, and a description of password requirements according to the company’s security policy).

Data Types:

The Payment type attribute is listed as an Enumeration. I recommend this data type when the attribute can take only one value from a predictable set of options. That is, not any number or arbitrary text, but like in our case, either Cash or Card. Naturally, from a UI perspective, this will be collected not via a text field, but through radio buttons, dropdown lists, or something similar.

Products — similarly to what we discussed earlier — this is a reference to Product instances, plus here an array symbol is added to indicate that there may be multiple such references.

Additional Details:

We noted that the Total Cost a) is calculated by the system (i.e., it’s not entered manually by users), and b) is fixed at the moment the Order is created. This is essentially the reason for defining this attribute: product prices may change after the order is created, so simply referring to the Product and its current price would not work. Also, we included the calculation formula here so it’s documented centrally.

For Payment Type, we described the set of allowed values, which is necessary because it is an enumeration.

Note how, by doing this work (developing the data dictionary), we also explicitly thought through and detailed many nuances: mandatory fields, format specifics, which translate into important requirements for how to collect this information in forms and how to correctly display it. Without explicit focus on the data dictionary, predicting the fate of such requirements is hard: an analyst might consider them, but it’s unclear how timely or thorough that would be — it depends on how the planets align.

Don't cross the line: like with the data model, in the data dictionary we try not to delve into technical implementation details. What this means:

a) Data types, as you may notice, are “human-readable.” For example, Text (not Char(100)) or Integer (not Int(32)). These become “technical” data types in their physical implementation, once that becomes clear.

b) Linking entities is also abstract. For example, if I were designing a relational database, I’d link Product to User by UserID. But I’m not designing a database here, and I don’t even know if there will be one or what kind of data storage and linking methods will be used.

c) Format constraints on attributes are linked to behavior, not storage. For example, a delivery address might have a max length of 200 characters because, for some reason, we don’t want users to enter more — so it’s easier to display, etc. We don’t discuss database-level limits here. Implementation concerns matter (remember feasibility), but not as input I can specify upfront — I’ll get those during requirements review with the dev team.

What else does the data dictionary provide? It’s a single source that helps keep behavioral requirements consistent. Without it, here’s what could happen: when working on the Order creation form (User Story for creating an order), I’d think “dear stakeholder, let’s figure out what the user needs to enter and how.” Later, when detailing order editing — I’d repeat the same work; when detailing how to display the order to admins — again the same process (“what useful info do we show here?”). This is a breeding ground for inconsistencies: something collected from the user might not be displayed, or vice versa; optional info entered might not be handled correctly when shown, etc.
Having a central data dictionary greatly eases this and drastically reduces such errors. You always have one place with info on whether a parameter can be empty, its type and format, how it’s calculated, and so on.

5) Although we have finished with data requirements, here’s a brief note on how I recommend considering data requirements in the context of other requirements, highlighting two key points:

a) Much of what we thought through while doing this work are business rules (or at least have business rules as their information source). What important business rules can we extract from our work above?

A customer can place an order for no more than 5 products at once.
Prices in the online store are indicated as floating-point numbers with two decimal places.
The maximum price of a product in the online store is 1000.00.
The online store accepts two types of payment: cash and card.

b) From any behavioral requirements (acceptance criteria for user stories, detailed use cases, etc.), you now need to trace back (link) to the data dictionary wherever behavior works with information. Without this, the part of our work here loses its meaning. What this means in practice:

Put your LDM (Logical Data Model) and data dictionary side-by-side in your documentation (for example, in the “Data Requirements” section of your SRS or on a dedicated page in your project’s Confluence).
When describing system behavior, reference these resources as precisely as possible so developers understand exactly what data you collect from users or display to them.

US01 Creating a Product

As an admin, I want to be able to add a product to the system so that it becomes available for customers to order.

Acceptance criteria:

1) When viewing the product list, I can open the form to add a new product.
2) To add a new product, I must specify the following parameters:

Name (link to the Title attribute for Product).
The system does not allow me to enter text longer than the maximum length (described via attribute link).
Description (link to the Description attribute for Product).
The system does not allow me to enter text longer than the maximum length (described via attribute link).
Price (link to the Price attribute for Product).
If I attempt to enter a price outside the allowed range (described via attribute link), the system will shout at me.

3) If I do not provide any of these parameters and try to add the product, the system screams.
4) I can also add an image for the product (link to the Image attribute for Product).
The system allows me to add images only in the specified format (described via attribute link).
If I attempt to add an image file exceeding the maximum size (described via attribute link), the system swears at me.