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.

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 of identity.

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:

1. What questions does this attribute enable our objects to answer?
2. What services does this attribute help our objects provide?
3. Is this attribute more than just a single, simple value or something more complex?
4. Do we need to track and remember the changes in this attribute's value for business or legal reasons
5. Is this attribute applicable for Person, Organization or both?
6. 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 entry.
• 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).

.

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

[1]Coad, De Luca, Lefebvre, Java Modeling in Color with UML, Prentice Hall