By: Amod Singhal, Business Systems Analyst I Business Rules Journal Vol. 19, No. 9, (Sep. 2018)
Summary: The Real Estate Standards Organization (RESO) needed a standardized way to communicate business rules used by various MLSs to validate data input input for creating home-for-sale listings. To that end, the Real Estate Business Rules (REBR) notation was recently adopted by the Real Estate Standards Organization (RESO) as a ‘best practice’ for documenting rules. In this case study, Amod Singhal describes how REBR was formulated from a combination of Structured English and RuleSpeak®, specialized in a way that was comfortable for the real estate community. He also shares insights gained along the way.
The Real Estate Standards Organization (RESO) recognized that Multiple Listing Service (MLS) organizations needed a standardized way to communicate business rules for validating data for creating property listings. Jeremy Crawford, CEO of RESO, notes[1] that currently, “We [have] rules embedded in software that is written in ‘computerese’ and so the business stakeholders have no idea what the rules really say…. The irony is that the very people who make and are responsible for the rules often do not have insight into what has been implemented in terms of the business rules in the software their members or agents are using.” Sound familiar?
The RESO Business Rules Workgroup was tasked with devising a standard way of expressing real estate business rules. Working with a domain expert, we identified half a dozen rule ‘patterns’ that covered the majority of all MLS’s input-related business rules. The Real Estate Business Rules (REBR) notation[2] was developed to enable non-technical people to express each kind of rule easily, without having to be schooled in the intricacies of RuleSpeak®.[3] REBR was officially adopted by RESO as a ‘best practice’ for documenting rules. There were some epiphanies along the way. In this case study, we describe the role played by the business rules approach, including RuleSpeak, and what we learned along the way.
Clear and Unambiguous
The team started by laying down the design objectives for the standard.
The proposed notation must provide the ability to state real estate business rules
- in terms such that another human will understand the rule clearly and unambiguously.
- using a concise, predictable syntax that can be correctly parsed (to extract each component of the rule) programmatically. This is necessary so that two parties can exchange the rules electronically.
- as a collection of rules for an MLS, i.e., as a “Rulebook” for that MLS.
Initially, the scope is limited to rules for validating data input for MLS listings. Rules governing the following are out of scope: what to display, listing deletion, and constraints on photos/videos attached to the listing.
Rule Collection
Our team collected input validation rules deployed by about a dozen MLSs. Each participating MLS found the exercise of gathering all business rules to be very useful. In nearly every instance, the MLS discovered rules, implemented in code, that were outdated or just plain wrong!
Early on, we had a tough time delineating exactly which rule was a ‘business rule’. For example, consider the rule: Listing Status is set to “Expired” on Expiration Date. Since the change of Listing Status was to be triggered by the system’s clock, is this a system rule? On the other hand, since this rule will be implemented in some process, is it a “process rule”? Are these distinctions meaningful?
The light bulb went on once we realized that a business rule is always declarative: Business rules transform nothing. Process and workflow tasks do. So, the business rule is: Listing Status must equal “Expired” on or after the Expiration Date. And the related workflow task is: On or after the Expiration Date, if the listing is not already in Expired status, change the Listing Status to Expired.
Rule Patterns
As might be expected, each MLS believed their rules were so unique they couldn’t be modeled into a small number of common patterns. This was largely due to the co-mingling of declarative business rules with task directives, resulting in rules that had to be executed in a specified sequence in order to work correctly.
To get an understanding of the kinds of business rules we were attempting to standardize, we enlisted the help of a subject matter expert. We identified the following patterns, which could apply to a single field or a group of fields in an MLS listing:
- Editability: Can the field value be modified?
- Mandate: Is the field required or optional? Must the field be an empty value?
- Constraint: If a value is provided for the field, what are the constraints on the value?
- Derivation: How is the field value computed?
A Rule Is Simply an If/Then. Not!
When we started researching notations for business rules, we began with a common misconception: A business rule is nothing more than an “If…Then…” statement. That notion was quickly dispelled as we better understood the Structured English approach developed by Business Rule Solutions. There are several issues with the If…Then… approach of stating business rules. We mention a few here.
- Not understood by business & non-technical persons: It perpetuates the computer programmer mindset, which focuses on implementation at the expense of clear and unambiguous understanding by non-technical business people.
- Obscured by details: The intent of the rule is in the details of the If…Then conditions, especially when they are complex.
- Artificially imposed If/Then: Not all business rules are amenable to the If…Then format, which is then artificially applied. For example, there is no IF/ENDIF in the rule: “An Agent must have a name.”
For a more in-depth discussion, see Ron Ross’s article.[4]
Structured English and RuleSpeak
Early in our research, the team realized that commercial business rule engine technologies were focused on software implementation of rules. What we needed, instead, was a sound conceptual framework in which to express business rules clearly and unambiguously. We found such a framework in the book “Business Rule Concepts (4th ed.)” by Ron Ross[5] which we read cover to cover. We rendered hundreds of real estate rules in Structured English and RuleSpeak. Our conclusion: RuleSpeak is easily understood by humans, can state the rules unambiguously, and has the potential to provide the predictable syntax we were looking for.
But there was a problem. Proficiency in RuleSpeak required training and practice. Even with our growing experience, we found ourselves making mistakes. Resource-constrained MLSs would simply not take the time to learn the nuances of RuleSpeak. We needed to come up with a rules notation that could be easily learned by business and technical people in a matter of hours.
From RuleSpeak to REBR
Starting with the “Structured English” constructs provided by RuleSpeak, we formulated the Real Estate Business Rules (REBR) notation as a limited, domain-specific equivalent. REBR uses a predictable syntax for clearly and unambiguously specifying real estate business rules. Thus, it is possible to programmatically translate to/from REBR and RuleSpeak. There is a much smaller learning curve for REBR, especially since we provided numerous examples for each rule pattern. Our field testing established that business folks found the REBR notation easy to work with.
The general format of each REBR rule is as follows, with minor variations.
- Starts with a rule name which indicates the rule purpose. This could be one of the following:
- ALLOW_EDIT
- REQUIRE_VALUE
- REQUIRE_EMPTY
- CONSTRAIN_VALUE
- CONSTRAIN_DATETIME
- DERIVE_VALUE
- Followed by YES/NO, if applicable, with default=YES
- Followed by what the rule applies to. This could be one of the following:
- FIELD fieldName
- FILEDGROUP fieldgroupName
- OBJECT objectName
- Followed by applicable conditionals, i.e., the IF…ENDIF block. Default is “Unconditional”.
- Finally, additional rule details are added, including Min/Max counts, Lookup list names, Definitions, etc.
Additionally, in order to minimize rule proliferation and promote rule reuse, we separated the following from the core rule:
- Scope: For example, rules applicable to MLS1 can be separated from those for MLS2.
- Trigger: The condition or event that would trigger the rule. In the scenarios described in this article, the rule is triggered when the listing is saved.
- Enforcement: Three enforcement levels were permitted — Strict, Warning, and Override. Default is Strict.
Finally, we recognized that all variations of fields, rule conditions, and triggers cannot be anticipated in advance. Hence, the REBR notation retains the flexibility to specify certain rule elements in natural language. For example:
| A geological study is required if property is near a marsh. The meaning of “near” is to be defined later. | REQUIRE_VALUE OBJECT (Geological Study) IF (Property is near a marsh. The meaning of “near” is to be defined later) ENDIF |
Rule Examples in REBR
Below is an example of a fully-specified rule, including Scope, Enforcement, and Trigger.
SCOPE (
MLS=MyMLS,
ListingTransactionType=ALL, //Includes: Sale, Lease, Lease w/ Option to Buy
ListingPropertyType=INLIST (“Residential”, “Lease”),
ListingPropertySubType=ALL //Includes: Single Family Residence, Mobile, Condo, Townhome, etc.
)
REQUIRE_VALUE
FIELD Closing Date
IF ListingStatus = “Closed” ENDIF
ENFORCEMENT = WARNING IF User Role INLIST (“MLS STAFF”, “SUPERUSER”) ENDIF
MSG “You did not enter a Closing Date for a Closed Listing. Continue?” ENDMSG
ENFORCEMENT = STRICT IF User Role INLIST (“AGENT”, “BROKER”) ENDIF
MSG “A Closed Listing must have Closing Date.” ENDMSG
TRIGGER (OnSave)
The above rule is interpreted as follows.
- The rule is applicable to MyMLS listings, for all Listing Transaction Types, for Listing Property Types of Residential and Lease, and all their Subtypes.
- The rule states: A Closed listing must have Closing Date.
- The rule can be overridden by MyMLS Staff and Super Users with the warning “You did not enter a Closing Date for a Closed Listing. Continue?”
- The rule can’t be overridden by agents and brokers. The error message is “A Closed Listing must have Closing Date.”
- The rule is triggered when a user executes the Save Listing functionality.
Below are additional examples, omitting scope, enforcement, and trigger for brevity.
|
Rule in Structured English |
Same Rule in REBR |
| State must have a value. State has a default value of “Minnesota”. | REQUIRE_VALUE FIELD State DEFAULT “Minnesota” |
| Exactly 1 field in CommissionFieldGroup must have a value if CommissionYN is “Yes”.
CommissionFieldGroup consists of the following fields:
|
REQUIRE_VALUE FIELDGROUP CommissionFieldGroup IF CommissionYN = “Yes” ENDIF MINCOUNT 1 MAXCOUNT 1 DEFINITION CommissionFieldGroup = INLIST (BuyerAgencyCompensation, SubAgencyCompensation, TransactionBrokerCompensation) ENDDEFINITION |
| A Single Family Residence Listing with ListPrice greater than $3,000,000 must have at least: 2 Bedrooms, 2 Bathrooms, and 1 Kitchen. |
REQUIRE_VALUE OBJECT ( Bedroom MINCOUNT 2, Bathroom MINCOUNT 2, Kitchen MINCOUNT 1) IF (Listing Type is Single Family Residence) AND (ListPrice GREATERTHAN $3M) ENDIF |
| ReserveListPrice must be empty valued if this is not an auction listing. | REQUIRE_EMPTY FIELD ReserveListPrice IF (Listing is not an Auction Listing) ENDIF |
As these examples show, MLSs often preferred to use data field names instead of a business name for that data. This was because business users were comfortable using data field names, many of which were RESO standard.
An interesting observation was that most people found that the easiest way to write a rule in REBR was to iterate between Structured English and REBR. Iterating between the two provided a “check and balance” ensuring the accuracy of the rule.
The IT Mindset Is Alive and Well
After several rounds of field testing with our pilot MLS partners, the notation was presented to the larger RESO workgroup for discussion and approval. The biggest objection by far, mostly from IT staff, was that the notation did not provide a way to implement the rule. The point that this is intentional was initially missed altogether.
To get the idea across, we constructed a silly example as follows.
Rule in plain language: Unless the moon is made of cheese and pigs can fly, Assessor Parcel Number (APN) is required.
Same rule in Structured English: Assessor Parcel Number (APN) is required unless both of the following are true: (1) the moon is made of cheese, (2) pigs can fly.
Same rule in REBR notation:
REQUIRE_VALUE
FIELD (Assessor Parcel Number)
IF NOT [ (the moon is made of cheese) AND (pigs can fly) ] ENDIF
How could the system implement the crazy conditions in this rule? The answer is: it varies. Your implementation may present a human being with pop-ups to answer the questions — “Is the moon made of cheese?” and “Can pigs fly?” Or, in anticipation of having to answer these questions programmatically, you may implement each question and its answer in a lookup table. Or, you may have correctly interpreted the intent of the rule to be “APN is always required” and state it as: REQUIRE_VALUE FIELD (Assessor Parcel Number). The point is: Business should be able to state a rule clearly, unambiguously, without first having to worry about whether or how it could be implemented.
A second, related objection was the desire to seek a notation that could simply be “fed into a rules engine which will automatically implement the rule.” Needless to say, such a magic-bullet solution does not exist. We did note, however, that a majority of the simplest REBR rules could be easily automated.
A third objection was that languages for stating business rules already exist, why not use those? Examples cited were JSON, ACE (Attempto Controlled English), Gherkin, and others. We asked workgroup participants to state a few simple real estate rules in these languages and put them side by side for comparison with Structured English and REBR. The findings were that, except for Structured English and REBR, in every case (a) the syntax was too complicated for business, and (b) the intent of the rule was either opaque or could only be inferred from the informal comments embedded in the chosen notation!
A Rule Engine To Put It All Together
Using the principles of separating the core business rule from rule scope, triggers, and violation-response levels, an application architecture was developed for a custom-built business rule execution engine. This is best illustrated with an example.
For instance, consider the following rules.
- For MLS1: List Price is required. Value must be less than $5M.
- For MLS2: List price is required. Value must be less than $10M. Enforcement: Coordinator role can override.
- For MLS3: List price is required. Value must be less than $8M. Enforcement: Warning only.
- For all MLSs: Default Enforcement = Strict.
The above rules are implemented in the rule engine, as follows, and reused by all three MLSs:
- REQUIRE_VALUE List Price
- CONSTRAIN_VALUE List Price LESS THAN MaxListPrice
The following are configurable for each MLS:
- MaxListPrice
- Enforcement Levels
The rule engine pulls in the core rule from the rules repository, merges in the configurable components from the configuration store, then executes the rules against input data for applicable listings when the triggering condition is detected.
Conclusion
After a discussion and comment period, RESO officially adopted the REBR notation as a ‘best practice’ standard for documenting real estate listing input rules. Since then, at least four MLSs have compiled their rules into Rule Books using Structured English and REBR. REBR continues to evolve. Extensions and modifications to REBR have been proposed.
Acknowledgments
Members of the RESO Business Rules Workgroup played a seminal role in the development of REBR. Matt Cohen led categorization of rule patterns. Susie Cass compiled rules from many MLSs, providing valuable insight into correctly mapping rules to patterns. She also acted as our Structured English police, catching subtle and not-so-subtle errors in applying RuleSpeak. Other workgroup members contributed significant amounts of their time to review and provide feedback on REBR.
References
[1] Jeremy Crawford, “RESO Offers Real Estate Business Rules as a Best Practice,” Real Estate Standards Organization, (Real Estate Standards Organization, 15 Dec. 2017), URL: www.reso.org/reso-offers-real-estate-business-rules-best-practice/ 
[2] Amod Singhal et al, REBR: A Standard Notation for Real Estate Business Rules – Reference Manual v1.0 Draft, (Real Estate Standards Organization, 17 June 2017), URL: www.reso.org/download/rebr-reference-manual/
[3] RuleSpeak®, (Business Rule Solutions, LLC, 1996-2018). PDF available at http://www.RuleSpeak.com
[4] Ronald G. Ross, “What’s Wrong with If-Then Syntax For Expressing Business Rules ~ One Size Doesn’t Fit All,” Business Rules Journal, Vol. 8, No. 7, (July 2007), URL: http://www.brcommunity.com/a2007/b353.html
[5] Ronald G. Ross, Business Rule Concepts 4th Edition, (Business Rule Solutions, LLC, April 2013).
Original post: http://www.brcommunity.com/articles.php?id=b964
