The Coad Letter: Modeling and Design, Issue 107, Party Time (Part 2) by Stephen Palmer
Party time: Modeling Legal Id's, and Addresses
A brief recap
For those new to the modeling in color technique, a fuller introduction
to modeling in color can be found in Chapter 1 of Java Modeling in Color with UML.
The green class archetype in Peter Coad et al's[Coad]
Modeling in Color with UML represents a party, place or thing (PPT)
where a party is a legal entity, something or someone recognized by some
court of law. There are essentially only two different kinds of Party, individual
people and organizations. With an initial model that looks like figure 1
and the information in the class archetype diagram shown in figure 2 we
are ready to consider party identity numbers and documents.
Figure 1: Abstract Party class with
Person and Organization subclasses
Figure 2: The Party flavor of the PartyPlaceThing archetype
Legal Identity Numbers and Documents
In Party Time:
Modeling Party Names, we noted the problems caused by names not
always uniquely identifying people or organizations. For legal, business
or administrative reasons, being able to accurately and unambiguously match
a party's information in their IT systems with the real world person or
organization that it represents, is a fundamental concern for many organizations.
The Party, Place, Thing archetype suggests that some sort serial number
is a typical attribute found in classes of that archetype. Obviously such
an attribute in our Party class would allow us to precisely match a software
object with its real world equivalent. Unfortunately people and organizations
do not come with a serial number stamped on them by their manufacturer.
Of course, we can always have our system assign each party a unique identity
number but that is only part of the problem solved. Firstly, that identity
number may only be recognized within our system, or if we are lucky, across
our organization. It does not necessarily help us match information about
our party in other systems or other organizations with which we might need
to interface. Secondly, it does not help us determine if the person talking
or writing to us is who they say they are or represents the organization
that they claim they do.
In many countries, government agencies assign people various identity documents,
at birth, when they are old enough to start full-time work (for taxation
or social security purposes), or when they become permanently resident in
that country. Then there documents issued to people that prove they are
entitled to do something. Driving licenses are a good example. All these
types of document carry unique numbers or character strings that we could
use instead of or in addition to the identity number we create ourselves.
However, it is not always considered politically correct to demand that
a person provide a government issued number to identify themselves. Therefore,
some organizations prefer to use date of birth in addition to the person's
name to provide a 'unique enough' identifier. Of course, asking someone
their date of birth is also considered impolite in many cultures. Also some
types of document are not considered proof of identity by themselves. For
example the Council of Mortgage Lenders in the UK recommends two lists of
different types of document that prove identity. The entries in list A ,
such as passport and military identity card are considered proof of identity
alone but entries in List B, like credit, bank cards, and local government
tax or rental bills, require two examples to be considered an adequate proof
Fortunately, the situation with organizations is a little better. Most
countries, regions or states require an organization to register with a
suitable government agency before it is legally recognized. When an organization
does register itself with the appropriate government agency, that agency
assigns it an identity number that is unique for that kind of organization
in that country, region or state.
Lets ask the same six questions we asked about the name attribute in Party
Time: Modeling Party Names:
- What questions does this attribute enable our objects to answer?
- What services does this attribute help our objects provide?
- Is this attribute more than just a single, simple value or something
- Do we need to track and remember the changes in this attribute's value
for business or legal reasons
- Is this attribute applicable for Person, Organization or both?
- If the attribute is applicable for both Person and Organization, are
the attributes similar enough for them to be placed in the Party superclass?
Question 1 & 2: Obviously a unique identifier enables a Party
object to answer precisely the question, 'which party do you represent?'
and being able to answer that question means that it can participate in
services that locate a particular party object within our system
Question 3: A quick analysis of various forms of identity numbers/documents
shows they are more complex than a single string of digits:
- In reality the identity number is often a unique sequence of
characters including letters, punctuation and spaces.
- The identity numbers usually have some formatting rules that enable
basic validity checking. Although not much of a defense against the deliberate
use of a false id, this does protect against typing errors during data
- In addition to the actual identity number we need the type of the identity
document and the issuer to be completely certain that a search will only
find a single matching party object.
- Identity documents carry varying amounts of extra information about
the party such as the name, postal address, and date and place of birth,
etc. Many identity cards and documents also contain some magnetic or electronic
version of their information
- Organizations usually only have a single registered number for a given
country or state. In contrast, a person may hold multiple identity numbers/documents
of different types.
- Different organizations may prefer a certain type of personal identity
number. For example, a Malaysian organization is likely to want a person's
national identity card number if they are a Malaysian citizen but for
a foreigner they will request their passport number.
Question 4: Do we need to remember changes to identity numbers?
- Some personal identity numbers/documents have an expiry date e.g. driving
license and some countries' passports. However, the need to remember previous
values is dubious if we are using the id numbers purely to provide an
exact match between a software object and their real world counterpart.
- Organizational identity numbers do not generally expire or change unless
the organization itself undergoes a substantial change in the kind of
organization it is. In this case, it is probably better to treat the modified
entity as a completely new organization.
Questions 5 and 6: We have seen that identity numbers apply to both
Person and Organization classes but are they similar enough to be placed
in the party superclass or do we need to have specific classes for each
type of party? Summarizing the differences discussed above, we have:
- Each type of legal identity number or document is either for individual
people or organizations; never both. However, identity numbers created
by our own system can be applicable to both types of party.
- Different kinds of organization are assigned different identity numbers/documents.
- From questions 3&4 we note that people often have multiple different
current identity numbers but organizations usually only have one.
This is a tough call to make. Let's assume that they are similar enough
to be placed on the Party class. What model shape options do we have?
If we choose to represent each type of identity number as a subclass of
a common parent class we can store extra information in each subclass (see
Figure 3: Modeling each type of identity document as a subclass of a
common parent class.
Alternatively, we could decide that we do not need the extra information
in the subclasses and instead use a blue description class to indicate the
type of identity number providing it with a plug-in validation algorithm
if required. The result is a more general and much simpler model.
Figure 4: Using blue description objects to represent different types
of legal identity document
The use of a blue description class to represent different types of id
has an added advantage. If we add another blue description class to indicate
the type of organization represented by an Organization object, we can constrain
the type of legal id used by an organization to that which is relevant to
the type of organization. This is shown in figure 5. The models in figures
4 and 5 also have the advantage that new types of identity document can
be added by creating a new object rather than coding a new class.
Figure 5: Types of legal id constrained according to type of organization
We can use a plug-in (strategy pattern) in our LegalIdDescr class to provide
a more specific validation algorithm for some or all of the types of id
we recognize. If we do want to capture some of the other information found
on identity documents, such as date of birth, we can store that in the Person
or Organization class. One exception might be a postal address which frequently
appears on legal id documents for both people and organizations. This we
might feel is worth keeping as an optional item in the LegalId class (see
figure 5). Postal addresses and electronic addresses, however, are the subject
for another time.
References and notes
Coad, De Luca, Lefebvre, Java Modeling in Color
with UML, Prentice Hall