Implementation Guide

MISMO XML Version 3.6

Appendix B-1, page 32

Many MISMO v3.6 data points and containers are reusable and may show up in several different locations within one XML file. The location or context in which a data point is used must be known to fully understand the business meaning. The location is expressed using the

XPath. For example, the ADDRESS container may be used in the context of PROPERTY or PARTY.

Several data points are included in UAD to identify the XML file and its payload and establish relationships between containers. These data points do not display on the URAR but are necessary to provide context and create well-formed XML submission files.

Data Format Comments
Boolean MISMO data point terms ending with "Indicator" have values of "false" or "true". These values must be provided in lower case or the loan delivery XML file will fail schema validation.
Date Represents a specific date, which should be delivered in the format identified in the corresponding UAD Data Point Format Details column. The date must contain a dash (-) between the year, month, and day, for example, "2010-03-25".
Datetime Represents a specific date/time stamp. The date/time must contain a dash (-) between the year, month, and day and a colon (:) between the hour, minute and second. The 'date' and the 'time' must be separated by a "T". Time zones should be delivered in Coordinated Universal Time (UTC) with a time zone suffix of 'Z' included (i.e., UTC: 2022-05-13T09:45:00Z).
Note: the PDF will display the date as mm/dd/yyyy
Enumerated Represents a list of predefined values and applies to MISMO terms ending in "Type", and sometimes to terms ending in "Description," "Code," and "Identifier". When a data element is identified as "Enumerated", each value must be delivered exactly as indicated, following all spacing and capitalization or the delivered XML file will fail schema validation.
Amount Represents a number for the dollar amount. The numeric value should not contain dollar signs ($) or commas (,).
Numeric Represents values which must contain numbers only for the associated data point. The numeric value must not contain commas "," but can contain decimals "." (as indicated by the 'UAD Data Point Format Details' column).
String The string data type represents character strings and may contain a word, phrase, sentence, or paragraph.

The data in an appraisal XML file must pass certain data integrity rules. For example, an invalid enumeration or non-numeric data in a numeric field may cause the appraisal XML file to fail schema validation.

Guidance for displaying Amounts#
  • If the amount is a whole dollar value with no cents, display whole dollar only (e.g., show $25 instead of $25.00).
  • If the user enters cents, preserve and display them (e.g., $25.75).
  • Support user input of both whole numbers and decimal values (e.g., Accept 25 or 25.75).
UAD Data Point
Format Details		 Description XML Representation Display Rules
+5.0, +6.0, +7.0,
+8.0, +9.0, ±9.0		 These fields should be delivered as whole numbers only.
Do not deliver ".00" in the XML or display on PDF.		 Example: 350000 Example: $350,000
+4.2, +9.2 Include cents only when applicable. If amount includes cents: send with cents. Example: 25.75
If whole dollar: send integer only or include cents. Example: 25 or 25.00		 If amount includes cents: display cents. Example: $25.75
If whole dollar: display without .00. Example: $25

Special Characters in XML#

There are several reserved characters that cannot be included in the value of a data point unless they are properly "escaped." The following table shows common characters and corresponding character encodings that must be properly escaped in the appraisal XML file for the file to be valid. (This table does not contain a comprehensive list of all the reserved characters.)

Characters Properly Escaped Description
& &amp Ampersand
< &lt Less-than sign
> &gt Greater-than sign
" &quot Quotation Mark
' &apos Apostrophe
Note: In XML, do not escape quotation marks (double quotes) (") and apostrophes (') when they appear in normal element text. Escape them only when they conflict with attribute delimiters inside attribute values.

The URAR Delivery Specification includes the xLink language as described by the MISMO v3.6 Reference Model. This key topic Arcrole Relationships identifies the xLink attributes used by UAD.

XLink is an XML-based language for relating information. According to the W3C11 XML Linking Language (XLink) Version 1.1, W3C Recommendation May 6, 2010, http://www.w3.org/TR/xlink/, accessed June 4, 2018. , "XML Linking Language (xLink), allows elements to be inserted into XML documents in order to create and describe links between resources." The MISMO v3.6 Reference Model uses xLink to define relationships between elements that cannot be related hierarchically (through containment).22 MISMO Version 3 Reference Model General Information Guide, July 28, 2016, pp. 20-26. Available from www.mismo.org. MISMO uses a limited set of the xLink attributes:

  • xlink:label -attached to data point or container elements that will be used to express an arcrole relationship
  • xlink:from - identifies the source data point or container
  • xlink:arcrole - describes the type of relationship between source data and target data
  • xlink:to - identifies the target data point or container

Containers to be linked are identified using "xlink:label". The RELATIONSHIP container elements hold the "xLink:arcrole", "xlink:from", and "xlink:to" attributes that describe the data relationships.

XLink is the mechanism that establishes "relationships" or linkages in the XML that are visually obvious on the URAR. For example, each report has one subject property and one or more sale comparable properties. The detailed information about the subject property and each sales comparable property is obtained from different data sources (e.g., MLS, Assessor Records, etc.). When a report is printed or displayed, it is obvious which data source relates to the subject property or to an instance of a comparable property by where it is displayed on the report. However, in the v3.6 XML file, DATA_SOURCE and PROPERTY, are siblings under VALUATION_ANALYSIS. All data source information, regardless of which property the information belongs to, will appear together under DATA_SOURCES and all properties will appear together under PROPERTIES. Since the containers are all on the same level hierarchically, the relationships cannot be expressed using containment.

Additionally, UAD needs to link comparable adjustments to the subject property improvement. Defects need to be linked to their amenity, or improvement or property unit. Improvement costs and depreciated value need to be linked to a specific improvement. Each appraiser and/or appraiser supervisor must be associated with the report and to their respective signatory line in the report. None of these relationships can be expressed by containment either.

We need a way to:

  1. Uniquely label each item (in this case, a container holding a set of information).
  2. "Draw" logical lines between the items that should be linked.

This capability in XML is called xLink. In the submission file, each "item" is uniquely identified by a label specifically created to be used within UAD Delivery. The linking of the items is described in repeating RELATIONSHIP containers, which contain the label names of each item to be linked, and the type of relationship. The following table illustrates the xLink concept.

UAD Delivery File Relationships

Arcrole (Verb Phrase) XPath From Endpoint Source XPath To Endpoint Target
- MISMO v3.6 attribute providing information about the origin, destination, and behavior of a link between two objects described in the XML file.
- The "name" of the arcrole, defining the relationship between two containers.		 - The hierarchical path through the MISMO v3.6 schema document to the source data point that will be part of the link.
- This is where Xlink attributes are included in the Delivery File.		 - The name of the container or data point making up the first named entity in the verb phrase describing the relationship.
- In the RELATIONSHIP container, this item is identified with the unique Xlink label from the container being linked.		 - The hierarchical path through the MISMO v3.6 schema document for the target data point that will be part of the link.
- This is where Xlink attributes are included in the Delivery File.		 - The name of the container or data point making up the last-named entity in the verb phrase describing the relationship.
- In the RELATIONSHIP container, this item is identified with the unique Xlink label from the container being linked.