How to Maintain Backward Compatibility for RETS Metadata

Submitted by:	Rapattoni RETS Support
Updated:	07/14/03
Version:	RETS 1.01
Issue:	Rapattoni Corporation upgrades its Internet-based MLS system approximately every quarter. When the upgrade occurs, RETS servers for those customers must also be upgraded to work with the new DB schema. If changes to the existing RETS metadata are made it might break existing RETS clients unless certain guidelines are established to handle these types of scenarios. These guidelines are the subject of this article.

The solution is to maintain backward compatibility to the previous version in the metadata when RETS Server upgrades are made. Rapattoni Corporation can add new columns to the metadata as requested and coordinate between the customer and RETS client vendors. RETS clients should always use SystemName when communicating with the RETS server.

If you have any questions about this process, please feel free to contact Rapattoni's RETS Support. In addition, some case studies are shown below.

---

Examples

Case 1: Fields added to the metadata

There shouldn’t be any problem with new fields being added to the metadata. The only issue that may cause a problem is changing the default fields returned in a query where a client did not specify a Select= clause. If a RETS client does not select specific SystemNames (in the order it wants them) for its queries and is instead relying on the default fields returned for a search to always be the same, then there could be a risk of breakage on the client side. However, if a RETS client always selects the SystemNames (in the order it wants them) for the fields it wants returned in a query there should be no problems for that client when metadata is upgraded.

Example: A RETS client selects fields A,B,C for an ActiveAgent query. The Table metadata is upgraded to a new version and now fields D,E,F are available and added to the default query for ActiveAgent. The RETS client still gets back fields A,B,C for an ActiveAgent query because it specified those fields in the select clause. If the RETS client wants to, it can add fields D,E,F to its select clause and get that additional data.

---

Case 2: Fields modified in the metadata

When fields have to be modified in the metadata due to schema changes in the underlying database, Rapattoni Corporation can instead add new fields for the ones it wants to modify, and retain the old fields for backward compatibility. Rapattoni Corporation has the capability to change the join logic behind the scenes and keep the old fields the same for metadata upgrades.

If a field changes type or size, such as an integer to a character, Rapattoni Corporation can use a SQL function on the back end to convert it back to the old type and functionality so that the client side perform as expected. One additional note is that old fields will be removed from the default fields returned in a search where the client does not specify a select clause. If a RETS client needs to be guaranteed that certain fields are returned in queries it should always use a select clause.

---

Case 3: Fields removed from the metadata

This is the most serious case for metadata upgrades. If for some reason a change is made to the underlying DB schema where a field is dropped from the database and the data is no longer available, Rapattoni Corporation can change the logic behind the scenes for that field to just return a blank. The field will be removed from the default fields returned in queries and if a client tries to Select it will just return a blank value.

---

Case 4: lookup values modified in the metadata

Lookup values can be modified in the metadata at anytime. Lookup values for fields like City, Area, Subdivision, School Districts, Schools, Styles and Amenities, and so on. can be modified in a dynamic way on the Internet MLS and those changes will be migrated over to the RETS server in a dynamic way. RETS clients need to check the metadata Version on login and see if any lookup values have been modified. The RETS Specification mandates that clients must check metadata version on Login to a RETS server (see pg. 4-6 of the RETS 1.01 spec). This is the minimum version of the metadata that the host will support. If the version of the metadata being used by the client is less than this version the client MUST retrieve newer lookup metadata from the host.

Rapattoni Corporation feels that modifications to lookup values are minor metadata changes and RETS clients should be able to handle them with no problems. The Rapattoni Internet MLS is a highly dynamic system and it allows customers to add/modify/delete lookup values as they need. When an MLS customer needs to modify a Lookup value, their RETS server should automatically reflect that change as well.