The naming of entities, relationships and attributes is an important consideration when creating a rulebase.
Choose a name for a relationship
Document the naming convention for a project
Entities should be named using the definite article 'the', as in 'the family', 'the child', 'the friend', 'the school' etc.
When creating a relationship you should give the relationship a meaningful name. Remember that the relationship describes the reference from one entity instance to one or more of another entity instance. The relationship name should therefore include the source entity text so that it is clear from the relationship name who the relationship is from.
The name of the relationship should reflect the everyday expression used to describe the relationship (if there is one), and should be clear in and out of context what is being referred to. Try to consider that nature of the relationship you are capturing and give it a name that represents this relationship.
Where you are referring to a single instance ("to-one" relationships), your relationship text must therefore be singular. When you are referring to multiple instances ("to-many" relationships), your relationship text must be plural. Where one entity is the global entity, you may simply refer to the target entity.
| Relationship type | Entity 1 | Entity 2 | Relationship text |
|---|---|---|---|
| One-to-one | "the child" | "the friend" | "the child's best friend" |
| Many-to-one | "the child" | "the family" | "the child's family" |
| One-to-many | Global | "the child" | "the children" |
| Many-to-many | "the child" | "the friend" | "the child's friends" |
| Self-referential one-to-one | "the child" | "the child" | "the child's twin" |
Selecting correct attribute wording is fundamental to capturing logic accurately in your Oracle Policy Modeling application and conveying information to a user in a meaningful way. Specifically, attribute text influences:
The following general principles apply to the writing of Oracle Policy Modeling boolean attributes.
An Oracle Policy Modeling boolean attribute must include at a minimum a subject and verb. The subject is what or who the sentence is about. The verb tells us something about the subject. Most sentences also contain an object which is the thing the action is being performed on.
Examples of grammatical sentences are:
the investigation continued (subject – verb)
the lion stalked the gazelle (subject – verb – object)
The tense of a verb is used to indicate when the action took place. Your top level goal should usually be worded in the present tense as it describes the current state of affairs. However, everything below the top level goal should be written in the past tense as it describes what occurred for the top level conclusion to have been reached.
For example:
the person is eligible for an award (PRESENT TENSE) if
the person has demonstrated exceptional conduct (PAST TENSE)
the person has demonstrated exceptional conduct (PAST TENSE) if
the person has been commended by peers (PAST TENSE)
This principle applies regardless of the tense of the source material.
In English grammar we make a distinction between the speaker/s (I, we), the addressee (you), and the one/thing spoken about (he, she, it, they). This is known as person: first, second and third person, respectively. Boolean attributes should be written in the third person. (Note that there is a mechanism in Oracle Policy Modeling for switching attribute forms to second person for use in interviews.)
For example:
the person can go to the movies
the person has done a good job
Rather than:
I can go to the movies
you have done a good job
Some boolean attributes can be difficult to negate and for this reason should be avoided.
Examples are attributes which use the conjunctions 'and' and 'or'. In these attributes ambiguity can result from the negation of the attribute as we don't necessarily know how the negation of the verb should affect each of the components. For instance, let's look at the attribute "the cat and the dog ate the man's dinner".
If this attribute is false, this could mean that:
Given that there are three possible interpretations means that this attribute cannot be negated conclusively and should not be used.
In many instances, it may be tempting to word an attribute that could be split into two separate clauses as a single attribute.
However, if it is likely that part of the attribute is going to be used in other attributes, it is best to separate it into two attributes which each represent distinct concepts.
Contractions are used in more informal styles of writing and speech and should not be used in Oracle Policy Modeling attributes.
For example, rather than "there's an application pending", you should write "there is an application pending".
Each boolean attribute should be meaningful without reference to another. To do otherwise makes the rulebase more difficult to develop, maintain and audit.
The following are examples of attributes which do not make sense in isolation:
The wording of the attribute should be as simple as possible while still retaining its full intended meaning.
If the attribute belongs to an entity, the exact text of the entity should be included in the attribute text to make it clear which entity it belongs to. For example, if you have an entity 'the child', then attributes which belong to that entity group should include the text "the child":
the child is happy
the child’s toy is educational
the birthdate of the child
A variable can be replaced with the appropriate pronoun the second (and any subsequent times) the variable is used in a boolean attribute. For example, if we had a variable 'the claimant' we could write a boolean attribute 'the claimant owns the claimant's home' and then once we know the name and gender of the claimant this would be rendered as 'John owns his home'. This is preferable to hard-coding "his/her" or "their" in the attribute text.
Boolean attributes which refer to amounts should specify the unit of measurement to avoid any ambiguity. For example:
the person was 100 feet from the scene of the crime
See also:
When creating non-boolean attributes (variables) the following guidelines apply:
The definite article 'the' is used to refer to some specific thing (in contrast to the indefinite article 'a' or 'an' which does not refer to one specific thing). As variables are always referring to a particular thing, they must start with 'the'. For example,
the claimant's name
the type of animal
the price of the car
If a variable belongs to an entity, the text of the entity should be included in the variable text to make it clear which entity it belongs to. For example, if you have an entity 'the child', then variables which belong to that entity group should include the text "the child":
the child's age
the child's date of birth
the school that the child attends
To make it clear what unit of measurement is expected for amount variables, this should be included in the variable text. For example:
the distance between home and work (kilometers)
the weight of the truck (tonnes)
References to values derived in other sections of the material should explicitly state the origin of these values in the variable text.
A Rulebase Naming Conventions document should be created at the start of every Oracle Policy Modeling project to clearly set out a consistent method of wording attributes. This is critical because automatic linking will only work when attributes are an exact text match. If different rule developers use different text when creating separate chunks of rules the attributes will not tie together. The Rulebase Naming Conventions document should define which nouns will be capitalized and whether particular acronyms should be used.
The Rulebase Naming Conventions document can be kept in the Oracle Policy Modeling project under Documents/Design.