The Data Dictionary: Every Field, Defined Once

A data dictionary defines every field once, authoritatively: its meaning, type, allowed values, source, and rules. It exists to kill the ambiguity that happens when two teams interpret the same field differently, which is a quiet but major source of broken integrations and wrong reports.

A data dictionary is a centralized, authoritative definition of every data element in a system or domain: for each field, its name, business meaning, type, format, allowed values, source, and rules. Its purpose is singular and important: to give everyone, business, development, testing, a single shared definition of what each field means, so nobody interprets the same data differently. When the meaning of a field is ambiguous, two teams will quietly assume two different things, and the result is an integration that breaks or a report that is subtly wrong, discovered late and expensively. The data dictionary prevents that by defining each field once and making the definition the reference everyone uses. Building and maintaining it is core functional analyst and business analyst work.

I have seen a single ambiguous field, a “status” that meant one thing to the source system and another to the consumer, cause weeks of confused debugging because no authoritative definition existed to settle it. A data dictionary would have made the answer a five-second lookup. The structured templates for this and other core analyst deliverables are in Real-World BA Deliverables.

What goes into a data dictionary entry?

Each data dictionary entry fully defines one field, so that anyone reading it knows exactly what the field means and how it behaves. A complete entry has a predictable set of attributes, and the discipline is filling every one.

For each field, capture: the name, as it appears in the system or message; a clear business definition in plain language, what this field actually represents; the data type and format, string, decimal, date, with the precise format; the allowed values, the enumeration or range that is valid, including code lists; whether it is mandatory; its source or system of record, where the authoritative value comes from; any validation or business rules that govern it; and its relationships to other fields. You might also note how the same field is represented across different systems or messages, which is invaluable in integration work.

Field: creditorAccount
Definition:  The beneficiary's account that receives the payment
Type/format: string, IBAN format
Allowed:     valid IBAN, mod-97 check
Mandatory:   yes
Source:      provided in pain.001, carried to pacs.008
Rules:       validated at ingestion; closed account -> AC04 downstream
Relates to:  creditorAgent (BIC), creditorName

The business definition is the attribute people most often skimp on and most need. A field name like “status” or “amount” feels self-explanatory until you realize “amount” could be the instructed amount, the settlement amount, or the equivalent in another currency, and “status” could be the payment status or the message status. The plain-language definition removes that ambiguity, which is the entire reason the dictionary exists. This precision is the same discipline that makes a good functional specification and a good API requirement, applied at the level of the individual field.

How do you build one without it becoming a chore?

Build a data dictionary by working from the data elements that actually matter and defining each from real sources, existing systems, message standards, subject matter experts, and the data itself, then verifying against how the field is really used. The trick to keeping it manageable is to scope it to what matters and to ground every definition in reality rather than aspiration.

Start with scope: you rarely need to define every field in the universe, you need the fields in scope for the work, the ones flowing through the integration, feeding the report, or carrying the business meaning. Then gather definitions from where the truth lives. Message standards like ISO 20022 define many payment fields precisely. Existing systems and their schemas hold the technical definitions. Subject matter experts hold the business meaning. And the actual data holds the reality, what values really appear, which “optional” field is always populated, which enumeration has more values in production than the documentation admits.

That last source is the one analysts underuse. The fastest way to learn what a field really means and contains is to look at the data, the same testing-over-documentation principle from You Don’t Understand the System Until You Test It. Querying the data to see the actual distribution of a field’s values often corrects a definition that was wrong on paper, which is exactly the kind of SQL-based verification a technical analyst brings. Grounding the dictionary in observed data rather than documentation alone is what makes it trustworthy. The broader skill of reading systems to extract this truth is mapped in The Technical Skills Guide for BAs.

Why is a single authoritative definition worth the effort?

A single authoritative definition is worth the effort because ambiguity about what a field means is one of the most common and most expensive sources of defects, and a dictionary eliminates it at the source. When everyone references the same definition, the class of bug where two teams interpreted a field differently simply cannot occur.

The damage from undefined fields is insidious because it is invisible until it surfaces downstream. A source system populates a field with one meaning; a consuming system reads it with another; nothing errors, because both are technically valid, but the data is now wrong in a way that corrupts a report, a reconciliation, or a downstream decision. By the time someone notices the numbers are off, the cause is buried under layers of correct-looking processing, and tracing it back to a definitional mismatch takes days. A data dictionary turns that days-long investigation into a lookup, because the authoritative meaning was written down before anyone could disagree about it.

Beyond preventing defects, the dictionary accelerates everything that touches data. New team members onboard faster because the fields are defined. Requirements are clearer because they reference precise definitions. Testing is sharper because the expected values are documented. And in regulated domains, the dictionary supports data governance and audit, because you can demonstrate what each field means and where it comes from. This compounding value, fewer defects plus faster work plus governance, is why I treat the data dictionary as a high-return artifact rather than busywork, and why it underpins solid functional analysis.

How does the data dictionary relate to the data model?

The data dictionary and the data model are complementary: the model describes how data is structured and related, while the dictionary defines what each individual element means. You often want both, and confusing them leaves gaps.

The data model is about structure: the entities, the tables, the relationships, how a payment relates to an account relates to a party. It answers how the data is organized and connected. The data dictionary is about meaning: what each field within those structures represents, its type, its allowed values, its rules. It answers what each piece of data actually is. A model with no dictionary tells you the shape but not the meaning; a dictionary with no model tells you the meaning of fields but not how they fit together. Together they give a complete picture, structure plus semantics.

For an analyst, the practical move is to use the model to understand the relationships, often expressed in or alongside a system context diagram and the broader systems analysis, and the dictionary to nail down the meaning of each field. In payments, the model shows that a payment has a debtor and creditor each with accounts and agents, and the dictionary defines exactly what creditorAccount, creditorAgent, and creditorName each mean and require. Both are needed to specify and test correctly, and an analyst fluent in both can reason about data at the level the work demands. Maintaining them as living, owned artifacts rather than one-time documents is what keeps them authoritative, the same maintenance discipline that keeps a reason code mapping or a traceability matrix trustworthy.

The takeaway

A data dictionary defines every in-scope field once and authoritatively: its meaning, type, format, allowed values, source, and rules. It exists to eliminate the ambiguity that arises when two teams interpret the same field differently, which is a common and expensive source of broken integrations and wrong reports. Build it from real sources, ground each definition in the actual data, and maintain it with clear ownership so it stays authoritative.

Pair it with the data model for structure, and you have both the meaning and the shape of your data nailed down, which makes every requirement, build, and test that touches data sharper. Start with Real-World BA Deliverables for the templates and The Technical Skills Guide for BAs for the data skills, or browse everything at The Tech BA Toolkit.

Ahmed is a Senior Technical Business Analyst with 10+ years in banking and payments. He builds practical guides and tools for analysts at The Tech BA Toolkit.

Tags: Business Analysis, Data Management, Functional Analysis, Requirements, Data Governance