Extensibility & Omissibility in the RESO Data Dictionary
"If you do it and the Dictionary does it, then you need to do it the Dictionary way."
This sentence has become a mantra of Data Dictionary implementation, but there are assumptions in-between the words. Extensibility, or your ability to extend the Dictionary with your own local fields is hidden in that mantra. Also written between the lines is the expectation that you won't have everything in the Dictionary nor should you add everything just because it's there.
To the reader: This posting assumes a level of understanding of data integration in the MLS and real estate industry. The Dictionary was founded as a project to standardize MLS data and this paper will reflect as much. However many other types of systems have been or are in the process of having their fields and picklists standardized. Though this article may reference MLS, the same concepts apply to any product or system represented in, or absent from, the Dictionary. Lastly when referring to "fields" in this article, it is generally also referring to picklist items (enumerations) as well.
Role of the Dictionary
I'm the first to say it is a good thing to have the same names in your API as you have in your user interface. That having your Display Names and Standard Names (more on those later) be nearly identical or at least relatable is useful. Consumers of your metadata are influenced by the Standard Names, which tend to surface as field labels and picklist in 3rd party ancillary products. Having commonality or relatability between fields in your MLS and other products creates continuity for the users of those systems.
Where this can go wrong is when the dictionary is added verbatim as a back end structure for a system like an MLS. The Dictionary wasn't designed to be a back end. It and the transport (API/RETS) were built to be a pipe between systems. The Dictionary might speak to some changes in your back end, for compatibility sake, but it isn't meant to be your back end. Should the dictionary influence your back end? Yes. Should it be handed to your Database Admin as the new back end to your MLS? No.
The initial goal of the Dictionary was to represent the 80 to 90 percentile in common between systems, and to standardize those commonalities. It is expected that 10 to 20% of fields would be unique to local systems. As you get into that last 10 to 20%, the diversity grows at an increasing rate. Overloading the early Dictionary with uncommon fields was intentionally avoided. We used the term "bloat" as meaning the standardization of something that one or few used. In short, the Dictionary was to represent our commonalities and not try to be everything to everyone. The Dictionary was to be lean and effective.
Omissions from the Dictionary
Though the dictionary strived to cover commonality, it was clear that not everyone had or needed, all of the fields in the dictionary. If your system didn't serve any area with lakes or oceans, a field like Waterfront Features doesn't make a lot of sense. As such none of the "concepts" in the dictionary are required.
I use the term "concepts" intentionally. You are required to check that you don't have something that is in the dictionary, but that you call it by another name. If you have a field called Price and it really is the list price, then you must use the Dictionary Standard Name ListPrice as your field name. But if the Dictionary has something you don't have, like an Ocean View when your MLS is in Nebraska, then you need not make the nonsensical addition to your system.
Extensibility of the Dictionary
Again, with the same requirement that you look for concepts in common between your system and the Dictionary, if the Dictionary doesn't have something you have, then you're okay to keep that field. It may be that some of the items missing from the Dictionary are critical in your area. So never drop anything from your metadata based on it not being in the Dictionary. You should do the opposite.
We don't intend to stop growing the Dictionary at our theoretical 80% percentile. As such, if you have something that is not in the Dictionary, you should bring it to the Data Dictionary Workgroup as a possible addition. We may find that there are others with the same field. Those things systems have in-common are the things want to include in our evolution of the Data Dictionary.
Display Names vs Standard Names
There's an important distinction between Display Names, aka labels, and Standard Names. Currently RESO Certification tests the Standard Names and not the Display Names. Standard Names are the names used in your API, but probably not the same names showing as a field label on a report or during listing input. Those are Display Names. We are working on some cool ideas for Display Names, but today, the Standard Names are what we test for RESO Certification. Display Names are your choice, but keeping them easily relatable to the Standard Name is recommended.
In a Nutshell
"If you do it and the Dictionary does it, you need to do it the Dictionary way" also means that if the Dictionary has something that you don't, you don't have to add it (omissibility); if you have something the Dictionary doesn't, you can keep it (extensibility); and this currently applies to the Standard Names, not your Display Names, but it is recommended to have continuity between Standard and Display Names.
You can find the RESO Data Dictionary at https://ddwiki.reso.org.
More information and other articles are at https://larson.cc