Requirements Analysis

The Glossary of Terms

A glossary is not documentation written after the schema. It is the instrument that makes the schema possible, because a database cannot be more precise than the words used to describe it. This lesson shows how to build one that is used.

Beginner

Learning objectives

  • Write a glossary entry with term, definition, exclusions, examples and source
  • Detect synonyms, homonyms and vague terms in a requirements text
  • Choose a canonical term using explicit criteria
  • Keep the glossary and the conceptual schema aligned in both directions
  • Use the glossary as the anchor for multilingual naming

Prerequisites

  • Finding Attributes and Relationships
  • Finding Candidate Entities

Introduction

Every database project contains a moment like this one.

The librarian says "the loan". The director says "the borrowing". The old system calls it "the transaction". The printed form says "the delivery". All four are talking about the same thing, and none of them knows that the others are using a different word.

Then someone asks what happens when a member returns a book late and the answer arrives in two versions: "we charge a fine" from the librarian and "we never charge, we suspend the membership" from the director. The two statements are not contradictory — they describe two branches of the same rule — but the design team hears a contradiction and spends a week resolving it.

Both problems have the same root: the project has no agreed vocabulary. Not a bad vocabulary — none at all.

Glossary

A glossary is the controlled list of the terms used in a database project, each with a single agreed definition, its accepted synonyms, its explicit exclusions, and a pointer to where it appears in the requirements and in the schema.

It is controlled in the sense that terms are admitted deliberately, not accumulated. A word that is not in the glossary should not appear in a requirement, a diagram, a column name or a conversation without someone asking why.

The glossary is usually treated as documentation: something produced at the end, by whoever has time, to satisfy a checklist. That is precisely backwards. The glossary is a design instrument, and the earlier it exists the more it pays.

Here is why, stated as plainly as possible: a database cannot be more precise than the words used to describe it. If "loan" means two different things in two sentences of the requirements, the schema will either pick one meaning and silently lose the other, or merge both and produce an entity that means nothing. No amount of diagramming skill fixes a vocabulary defect, because the diagram faithfully reproduces the confusion.

What a glossary entry contains

A term and a definition are not enough. The entry must make disagreement visible.

Field Purpose Example
Term The canonical name Loan
Definition One sentence, testable, in the domain's words The temporary transfer of one copy to one member, with a due date
Not What the term explicitly does not mean Not a reservation; not a renewal; not a transfer between branches
Synonyms Words that mean the same and must be avoided Borrowing, transaction, delivery (legacy system)
Examples One positive and one negative case Positive: copy 2 lent to member 4471 on 3 March. Negative: a member reserving a copy that is on loan
Owner Who has the authority to settle disputes about it Head librarian
Source Where the definition came from Interview of 12 Feb, confirmed in writing 20 Feb
Requirements Which requirement IDs use the term F7, F9, F12, N4
Schema Which entity or attribute implements it Loan

Two fields do most of the work, and both are usually omitted.

"Not" is the field that prevents the most expensive errors. A definition says what a term is; the exclusion says what it is not, and most vocabulary confusion is about boundaries. Loan defined as "the transfer of a copy to a member" is compatible with a renewal; Loan with the exclusion "not a renewal — a renewal extends an existing loan and is recorded as an attribute of it" is not. The second version prevents a schema in which renewals are separate loans that double-count the copy.

"Source" is the field that makes the glossary authoritative. A definition that came from an interview on a specific date can be checked, disputed and corrected. A definition that came from nowhere is an opinion that will be overruled by whoever speaks last.

Terms are not only entities

A common misunderstanding: the glossary is the list of entities under another name. It is not. The glossary covers everything the project must say precisely.

Kind of term Example Where it lands in the schema
Entity Copy, Member Entity
Attribute Condition, Due date Attribute
State value Overdue, Withdrawn Value in an enumerated domain
Role Borrower, Supervisor Role name in a relationship
Event Return, Reservation Entity (usually)
Measure Loan period, Fine rate Attribute or parameter
Rule Borrowing limit Constraint, not a column
Document Membership card Possibly nothing — may be out of scope

The last two rows are the ones that catch people. Borrowing limit is a rule, and rules do not become columns; a schema that adds max_loans to every member row has misunderstood the term. Membership card may be a physical artefact the system never models, and saying so in the glossary prevents someone from building a Card entity for a piece of plastic.

The three vocabulary defects

Almost every glossary problem is one of three kinds. Learning to name them makes them findable.

Synonym

Two or more words used for the same concept: loan, borrowing, transaction, delivery.

Cost: the schema acquires two entities or two attributes for one fact, and the data splits between them. A report on "loans" silently omits the rows recorded as "borrowings".

Homonym (polysemy)

One word used for two or more concepts: "book" meaning the title and the physical copy; "member" meaning a registered person and a person with an active subscription.

Cost: one entity is asked to hold two kinds of fact, and every attribute becomes conditionally meaningful. The classic symptom is a column that is NULL for half the rows because it only applies to one of the two meanings.

Vague term

A word with no testable boundary: "recent", "large", "appropriate", "valid", "active", "soon".

Cost: the requirement cannot be implemented or verified, so the implementer invents a threshold and the user rejects the result. Every vague term is either a missing requirement or a hidden business rule.

The three defects need three different responses, and confusing them wastes time.

Defect Response What you produce
Synonym Choose one canonical term; list the others as avoided One glossary entry with synonyms
Homonym Split into two terms with distinct names Two glossary entries, and usually two entities
Vague Quantify or escalate as an open question A number, a date, or a recorded decision

Note that a homonym is not resolved by choosing — it is resolved by splitting. "We will use book to mean the title only" is a decision, but it leaves the physical copy without a name, and the copy is what gets lent. The right response is to introduce a second term (Copy) and keep both.

Finding the terms

Terms hide in four places, and a thorough pass visits all of them.

1. The requirements text. Every noun and noun phrase, plus every adjective that describes a state. The previous two lessons already extracted the nouns; the glossary adds the states and the measures.

2. The interviews. Listen for the words people repeat, and more importantly for the words people correct each other on. "No, that is not a loan, that is a reservation" is a glossary entry being born.

3. The existing documents and systems. Old forms, old reports, the previous database's column names. This is where synonyms come from: the organisation has been using three words for the same thing for fifteen years, and the new schema will inherit the confusion unless the glossary names it.

4. The schema as it grows. Every entity and attribute you add must have a glossary entry. If it does not, either the term is missing from the glossary or the element is unjustified — both are useful findings.

Choosing the canonical term

When a synonym set is found, one term must win. Four criteria, applied in order:

Criterion Question Library example
Precision Which term has the narrowest correct meaning? Loan beats transaction: a transaction could be anything
Domain usage Which term do the domain experts actually use? Librarians say loan; the accounting system says transaction
Absence of collision Which term is not already used for something else? Delivery collides with supplier deliveries
Brevity Among equals, the shorter Loan over book borrowing transaction

Precision comes first because a term that is too broad will be reused for something else within a year. Domain usage comes second because the glossary is a contract with the organisation, and a term they do not recognise will not be used, no matter how elegant.

Worked example: the library glossary

Six entries from the running case study, chosen because each one settles a real ambiguity.

Term Definition Not Synonyms avoided Schema
Title A bibliographic work the library may hold in one or more physical copies Not a copy; not an edition Book (ambiguous), work Book
Copy One physical exemplar of a title, held at one branch Not a title; not a loan Item, volume, exemplar Copy
Loan The temporary transfer of one copy to one member, with a due date Not a reservation; not a renewal; not a branch transfer Borrowing, transaction, delivery Loan
Renewal An extension of an existing loan, recorded on that loan Not a new loan Extension, prolongation Loan.renewals
Reservation A member's claim on a title that currently has no available copy Not a loan; not a hold on a specific copy Booking, request, hold Reservation
Fine A charge owed by a member for a specific overdue loan Not a fee; not a replacement cost for a lost copy Penalty, sanction Fine

Five observations, each of which is a lesson.

"Title" instead of "Book". The domain says book, but book is used for both the work and the physical object, and the physical object is what gets lent. Introducing title and copy resolves the homonym. Note the cost: librarians will keep saying "book" for a while, so both words must appear in the glossary, with book marked as ambiguous.

"Renewal" is an attribute, not an entity. The glossary entry says so explicitly — "recorded on that loan" — which prevents the schema from creating a Renewal entity that would duplicate the loan's identity and make counting loans ambiguous. The "Not" field carries this decision.

"Reservation" is not a hold on a specific copy. This is a real modelling decision disguised as a definition. If reservations were on copies, a member could only reserve copies that exist; reserving a title the library does not yet own would be impossible. The definition chooses the title-level interpretation, and it must be confirmed with the library.

"Fine" is not a fee. The library has both: fines for lateness and fees for services such as printing. Two words, two concepts, two entities — and without the exclusion, someone would merge them into a Charge table and lose the distinction that matters for reporting.

Every entry points to the schema. The Schema column is what keeps the glossary alive. When the model changes, the column breaks, and the break is visible.

The glossary and multilingual naming

ERMap Academy itself is a small illustration of the same problem in a different dimension: the same concept must have one identity and several names.

The rule that makes this work is: the glossary holds the concept, the language files hold the labels.

Layer Contains Changes when
Concept A stable identifier and one authoritative definition The domain changes
Labels The term in each language A translation improves
Schema The physical name, derived from the canonical term The schema is refactored

If the schema name is derived from the Italian label, the day the project adds English the schema name becomes a historical accident that nobody can explain. If it is derived from the concept, the label can change freely.

For the library case study, this matters less — one language, one schema. For any system with more than one linguistic community, the glossary is the only thing that keeps the schema names stable while the display names change.

Maintaining the glossary

A glossary that is not maintained is worse than none, because people trust it.

Three practices keep it alive:

Assign an owner per term. Not one owner for the whole glossary — one owner per term, the person with the authority to settle disputes. Disputes get resolved by the right person instead of the loudest one.

Version it with the requirements. The glossary is part of the requirements document, not an appendix to the code. A change to a definition is a change to the requirements, and it should trigger a review of the affected requirements and schema elements.

Break it deliberately. When a term must change, record the old definition and the date of the change. Six months later, the question "why is this column called loan when the UI says borrowing?" has an answer.

Common mistakes

Mistake What it looks like Why it hurts Fix
Definitions that restate the term "A loan is a loan"; "the member is the person who is a member" No information; nothing testable Define by what one instance is, and add the exclusions
No "Not" field A definition that is compatible with three interpretations Boundaries stay undecided until the code decides them Add explicit exclusions
Synonyms left unresolved Both loan and borrowing used in requirements Data splits; reports undercount One canonical term, others marked as avoided
Homonyms not split Book meaning title and copy Columns that are NULL for half the rows Two terms, two entries, usually two entities
Vague terms accepted "recent", "valid", "active" Unimplementable and unverifiable Quantify, or record as an open question
Glossary as a post-hoc appendix Written after the schema, by one person, in a week Describes a model that no longer exists Write the disputed entries first, maintain continuously
One owner for everything "The analyst owns the glossary" Disputes escalate instead of resolving Owner per term
No traceability to the schema Glossary and model evolve separately Drift, and nobody notices Two-way check at every review

Summary

  • A glossary is the controlled list of the project's terms, each with one agreed definition, its synonyms, its exclusions, its source, and its place in the requirements and the schema.
  • A database cannot be more precise than the words used to describe it. A vocabulary defect cannot be fixed by better diagramming.
  • An entry has nine useful fields; the two that prevent the most errors are "Not" (what the term excludes) and "Source" (where the definition came from).
  • The glossary covers more than entities: attributes, state values, roles, events, measures, rules and documents.
  • Three defects, three responses: synonyms are resolved by choosing; homonyms by splitting; vague terms by quantifying or escalating.
  • Terms are found in the requirements, the interviews, the legacy documents and the schema itself.
  • The two-way check keeps glossary and schema aligned: every data term appears in the model, every model element has an entry.
  • The canonical term is chosen by precision, then domain usage, then absence of collision, then brevity.
  • Write the disputed entries first; a glossary that starts with the easy words will never be consulted.
  • With several languages, the glossary holds the concept and the language files hold the labels.

Verification questions

1. The requirements use "active member" eleven times. What do you do?

Show the solution

First, recognise the defect: active is a vague term, and it is doing structural work — eleven uses means it is load-bearing. Second, find out what it excludes: an active member is not a member who has never borrowed, not a member whose subscription lapsed, not a member suspended for overdue books. Each candidate exclusion is a different rule.

Third, quantify. Typical answers: "has a subscription whose end date is in the future and has no unpaid fine above 20 euros" — which is a business rule, not a definition, and it must be recorded as such, with its numbers confirmed by the owner of the term.

Fourth, decide where the state lives. If active is computed from subscription dates and fines, it is a derived attribute and must not be stored. If it can be set manually by a librarian (a suspension decided by a person), it is stored and it is an attribute with its own history — which usually means an entity recording suspensions, not a boolean.

The mistake to avoid is accepting "active" and writing is_active BOOLEAN. That column will be wrong within a month, because nobody agreed what it means and every update path will interpret it differently.

2. Why is a glossary entry with no "Not" field dangerous, even when the definition looks clear?

Show the solution

Because definitions describe the centre of a concept, while disagreements happen at the edges.

"The loan is the transfer of a copy to a member" is clear about the centre: a member walks out with a book. It says nothing about renewals, about a copy transferred between branches while on loan, about a loan that is cancelled the same day, or about a member who takes a copy without recording it. Each of those is an edge, and each has at least two defensible interpretations.

The consequence is not a bad document; it is a bad schema. Without an exclusion, the implementer decides the edge cases, and the implementer's decisions are invisible: they appear as a NULL here, an extra row there, a status value nobody documented. By the time the librarian notices, the data exists and the fix is a migration.

The "Not" field is cheap — one sentence — and it converts an invisible decision into a reviewable one.

3. A glossary has an entry for Invoice but the schema has no Invoice entity. What are the two possible explanations, and how do you decide?

Show the solution

Either the model is incomplete, or the term is out of scope. Both are legitimate; they are distinguished by the requirements, not by the schema.

Model incomplete: a requirement says invoices must be issued, and the model has no entity for them. The glossary caught a gap — this is the glossary doing exactly its job, and it is the more valuable of the two outcomes.

Out of scope: the organisation issues invoices, but from a different system, and this database only needs to reference the invoice number as an attribute of a payment. Then the glossary entry should say so explicitly: "Invoice — issued by the accounting system; this database stores only the reference number." That sentence prevents two future errors: someone building an Invoice entity that duplicates the accounting system, and someone wondering why an entity named in the glossary does not exist.

The way to decide is to trace the term to a requirement ID. If a requirement needs it and the model lacks it, the model is wrong. If no requirement needs it, the glossary entry needs the scope sentence — and the scope table from the domain analysis needs a row.

Exercise

Intermediate

A university's disputed vocabulary

The following sentences come from five different interviews about the same student information system. Identify the vocabulary defects, then write five glossary entries that resolve them.

Registrar: "Each student enrols in a course and gets a grade at the end." Professor: "I teach two courses this semester, each with about eighty students." Administrator: "A course runs every year, but the programme changes every three years." Student: "I failed the course last year and I am repeating it now." IT manager: "The old system has a course_code that is reused every year, which is why the historical reports are wrong."

Commented solution

The defects

Sentence Defect Detail
Registrar: "enrols in a course" Homonym Course means the catalogue entry (the subject, with a code and a syllabus)
Professor: "I teach two courses" Homonym Course means the specific offering this semester, with a teacher and a timetable
Administrator: "a course runs every year" Homonym confirmed The catalogue entry recurs as an offering each year
Student: "I failed the course and I am repeating it" Homonym confirmed Failure attaches to the offering, not to the catalogue entry
IT manager: "course_code reused every year" Symptom of the homonym The key identifies the catalogue entry, so two years of offerings collide — the historical reports are wrong because the identifier is not unique per offering

So there are not one but two concepts behind course, and the legacy key proves the model has been wrong for years.

Two more defects:

  • Student is a mild homonym: a person registered in the system, versus a person with an active enrolment in a given year. "Eighty students" counts enrolments, not people.
  • Grade is a vague term: a mark out of thirty? a pass/fail? the outcome of the whole year? In the Italian system these are three different things.

Five glossary entries

Term Definition Not Synonyms avoided Schema
Course The catalogue entry for a subject: a code, a title, a syllabus and a credit value, stable across years Not an offering; not a class group Subject, module, insegnamento Course
Course offering The delivery of one course in one academic year, with its own teacher, timetable and enrolled students Not the catalogue entry; not a single lesson Course (ambiguous), edition, erogazione CourseOffering
Enrolment The link between one student and one course offering, with a status and an outcome Not a registration in the system; not a payment Registration, subscription, iscrizione Enrolment
Grade The numeric mark awarded for one enrolment, on a scale of 0 to 30, recorded with a date and an examiner Not a pass/fail outcome; not the final degree mark Mark, score, voto Enrolment.grade
Student A person registered in the system who may be enrolled in zero or more course offerings Not an enrolment; not a person who has graduated Pupil, learner, studente Student

Why these five and not others

Course and course offering are the type/occurrence split from the entity lesson, arrived at through vocabulary analysis instead of through the two-question diagnostic. Both routes lead to the same place, which is reassuring: the vocabulary and the model are two views of one reality.

Enrolment is an entity rather than a plain link because it carries a status, an outcome and a grade, and because the student's sentence — "I failed and I am repeating" — is a fact about an enrolment, not about a person.

Grade stays an attribute of Enrolment at this stage. It becomes an entity the moment the university needs exam attempts ("failed twice, passed on the third"), which is a very common requirement and which the glossary would reveal as a missing term: exam attempt is nowhere in the five interviews.

Student is defined to exclude the enrolment on purpose. Without that exclusion, "eighty students" and "eighty enrolments" are the same phrase, and a report on class sizes will be wrong whenever a student repeats a course.

The lesson the IT manager gave for free

The reused course_code is not a naming problem: it is proof that the schema has been modelling one concept where the domain has two. A glossary built at the start of the legacy project would have caught it, because the entry for course would have had to say which of the two meanings it carried — and the answer would have been "both", which is the homonym defect stated out loud.

Where to go next

Related lessons