The RETS DTD calls out data items that are generally-known and widely-used in MLS systems. However, many of these are subject to unique local conventions. This developer note provides detailed recommendations for the format and content of fields which may be open to interpretation so that implementers can translate local data into common language.
As with other developer notes, this note is advisory in nature; if there are strong local conventions that conflict with this note, implementers may choose to follow local convention instead. However, following the recommendations in this note will lead to improved interoperability and will make it easier to take advantage of the MLS data repository.
This note doesn't reiterate information that is already available in the DTD, such as data formats and element structure. You should refer to the DTD for that information.
Constructing and Interpreting a RETML Record
The presence of a tag in the DTD does not mean that a compliant RETS implementation must transmit that field. If the field isn't used by the sending host, or if security or business rules prohibit transmission of the field, it need not be sent. When a field is withheld in this manner, it should be omitted entirely from the transmitted data, rather than transmitted with an empty field value.
Conversely, a client receiving an XML representation of a listing should not assume default values for any tag not transmitted. Instead, the client should assume that the value of that tag is unknown or unavailable.
Again, using the following content recommendations will greatly improve interoperability when exchanging real estate data using RETML. If strong local custom requires deviating from these descriptions, the sending entity should insure that the receiving entity is aware of the differences.
BathsTotal
This need not be the total of BathsFull , BathsHalf and BathsThreeQuarter . The receiver is free to calculate this field from the three detail fields if it is not provided. However, if the sender transmits this field, the receiver should use it instead of the calculated value.
BuildingType
Examples: fourplex, high-rise.
ComplexFeatures
A list of the common features of a multi-unit property.
CloseDate
ContractDate
The date on which the property was sold. This is not the close date.
DevelopmentStatus
The status of the land. Values include Tentative Map, Approved, Undeveloped, etc.
ExistingStructures
Used for lots and land, the content of this tag describes any existing structures present on the property.
Expenses
Used for income properties. The total expenses for the property, on the specified time basis.
Garage
The number of parking spaces in the garage.
GrossIncome
Used for income properties. The total gross income for the property, on the specified time basis.
Latitude
Longitude
Latitude and longitude should be transmitted as degrees and decimal parts, rather than degrees, minutes and seconds. Positive latitude values represent the Northern Hemisphere; negative longitude values represent the Western Hemisphere. This is consistent with Federal Information Processing Standards as well as US Census Bureau data. World Geodetic System 1984 (WGS-84) coordinates are preferred.
LivingArea
This is the total living area, usually called "square footage" in the United States and Canada.
ListDate
The date associated with the current listing contract.
ListingArea
The name of the area according to local convention.
ListingServiceName
The name of the multiple listing service, if any, that originated the listing.
ListingType
The legal type of listing, e.g., exclusive, exclusive agency, etc.
MapCoordinate
If there is a commonly-used map system, this field should contain the map coordinates in that system -- usually a page and grid reference. This is distinct from latitude and longtitude.
ModificationTimestamp
The modification timestamp included with an XML representation is intended to inform the recipient whether any internal cached representation of the record needs to be updated. If a modification wouldn't be externally visible, the value of ModificationTimestamp need not change.
OpenParking
This is the number of legal parking spaces that are open or uncovered.
OriginalListDate
The date on the original listing contract. An application may calculate the number of days on market by using this date field. If OriginalListDate isn't transmitted, the application may use ListDate .
Ownership
Primarily for condominiums: lease, fee simple, etc.
ParcelAccess
Intended for lots and land, describes the types of access available to the property. Examples: road, air, ski.
Parking
An application interpreting the XML document is free to calculate the total number of parking spaces available by adding each of the Parking sub-elements. This means that spaces cannot be counted in more than one Parking field.
PresentUse
For lots and land, the present use of the land.
PublicRemarks
Remarks
Receivers should assume that Remarks may have limited distribution, while PublicRemarks may be displayed publicly. Host implementers are responsible for implementing whatever business rules determine whether a particular query should return non-public information.
RentIncome
Used for income properties. The total rental income for the property on the specified time basis. Readers may assume that this amount is included in Gross .
Status
Do not use the OffMarket attribute for listings which are sold or expired. OffMarket should be reserved for listings which have become inactive in some way other than a sale or an expiration. Hosts may transmit more detailed information about the status as the value of the Status tag.
StatusChangeDate
This is the date on which the listing's status last changed. If possible, the StatusChangeDate tag should record the last change among the four status values listed as attributes in the Status tag.
Stories
The total number of levels separated by at least half a floor.
TotalUnits
The number of units in a condominium or apartment development.
URL
URL tags have an associated attribute, Internal , which specifies the validity scope of the URL. If a URL is designated as Internal , the receiver should assume that the URL will only be valid during the session in which the URL tag was transmitted. If the URL is not Internal , a receiver may assume that the URL is valid even after the end of the current session. The URL may become invalid at some future time; however, it is likely to be valid for a reasonable period of time.
When an entity sends a URL tag with the Internal attribute false, it should insure that the URL is valid for a reasonable period of time -- certainly at least as long as the ModificationTimestamp value remains unchanged.
Type
A locally-defined subtype within a property type. Examples include attached vs. detached, single-family vs. multiplex.
VacancyFactor
The vacancy factor, meaning the fraction or percentage of units that are currently vacant.
View
The content of the View tag may be used to describe a view according to local convention. Use the Present attribute to indicate whether the property has a view or is considered a view property.
YearBuilt
This field should indicate the year that the property is to be built if the NewConstruction tag indicates that the property has yet to be constructed.