Thursday, May 11, 2017

Extensions, using UCD as an example

UCD Extensions

Introduction

UCD (Uniform Closing Dataset) is one of the big Real Estate Finance changes for 2017-2018. In it Fannie Mae [1] and Freddie Mac [2] (The GSEs) will require delivery of the data set for all loans to be underwritten and guaranteed by them. This is a big deal because it represents about 60% of the current loan volume coming from Mortgage Banks and non-banks alike.

The basic design for UCD is the MISMO 3.3 release [3]. Unfortunately, timing prevented the GSEs from giving MISMO all the data they wanted to use in UCD in time for the 3.3 publication. As a solution the GSEs use extensions in the http://www.datamodelextension.org  namespace. The specifications request the use of the “gse” abbreviation for  http://www.datamodelextension.org .

Validating Extension Data

Example files provided by the GSEs will validate with respect to the MISMO 3.3 release because the content of the element need only be valid XML to pass the tests. MISMO as delivered does not validate inside other peoples namespace based extensions.

The GSEs have not published and probably will not publish a schema that will validate the content “gse” extensions. In this blog we attempt to construct an unofficial schema for that purpose.  It is intended to give interested parties a leg up on how to do this. We do no intend to keep it current with GSE changes. It is released AS IS to promote understanding.

There are four approaches to building extensions that can be used to validate XML files that contain the extensions:

1. Best Practice – After version 3.5 use the “redefines” method to add restrictions to the unique definitions of OTHER under each extension point. This is the best practice because you can add your extensions without editing the MISMO delivered files. (Actually you need to be using a a catalog to achieve no editing.)
2. Acceptable practice – Before version 3.5 edit the release files to create unique definitions of OTHER then use the redefine method. It is acceptable because it is limiting the files that belong to MISMO ( their copyright) that you are editing.
3. OK practice – Edit the file that contains the Complex Type extensions ( e.g. file MISMOComplexTypeExtensionsB299 in version 3.3) to add in the bridge to your namespace. Like number 2 above it limits what you edit.
4. Poor practice – Edit anything you want. This is poor because it makes almost none of your work reusable when the time comes to upgrade to a later version. I see people do this who want to start with the “Combined” schemas MISMO publishes. I would suggest using one of the other methods and then create a Combined schema of your own with a tool that “flattens” a schema.[5] 

As part of this blog I have created the files needed to use the Acceptable Practice mentioned above.

     Acceptable practice

 
In order to keep the UCD file names unique I copied and renamed the MISMO files then edited them. Here is a list of the changes made to the MISMO published 3.3 files. These files are found at [4]

MISMO Name
UCD name
Description
Change
MISMO_3.3.0_B299
MISMO_3.3.0_B299_UCD
Root schema
1)Change xs:include to use the UCD files. Add xs:import to “gse” definitions.
MISMOComplexTypeExtensionsB299
MISMOComplexTypeExtensionsB299_UCD
Defines the OTHER element for each extension point
1)Change xs:include to use the UCD files.
2)Changes OTHER definition to have unique definition 3) Add xs:include for the MISMOExtensionDetails_UCD file.
MISMOComplexTypesB299
MISMOComplexTypesB299_UCD
Defines container elements
1)Change xs:include to use the UCD files.
MISMODataTypesB299
MISMODataTypesB299_UCD
Defines data point data types
1)Change xs:include to use the UCD files.
MISMOEnumeratedTypesB299
MISMOEnumeratedTypesB299_UCD
Defines enumerate types
1)Change xs:include to use the UCD files.

MISMOExtensionDetails_UCD
Holds the new unique OTHER definitions.

gseUCDBridge.xsd
The MISMO namespace file that imports the GSE namespace material and redefines the OTHER definitions as needed.

gseUCD.xsd
Definitions of the gse namespace.

GSE Extensions

Overview

The GSEs have requested that the namespace http://www.datamodelextension.org be used with the abbreviation “gse”. (See unique ID 0.054  in spreadsheet appendix_i_uniform_closing_dataset.xslx Tab “appendix_i_uniform_closing_dataset” We will call the spreadsheet “the specifications”.)
If you are using an OASIS catalog [6] this will look up the schema file needed to support a namespace. If you are developing in .NET your application may want to have a custom “resolver” to accomplish the same thing. [7]

Since we will be developing and testing XSD files and XML example files outside of a custom application we will include the file location of the gse extension schema in the MISMO/UCD schemas using an xs:import expression. We will also be including the file location of the MISMO_3.3.0_B299_UCD.xsd file in the XML root element.

It is considered a security risk to allow the source of the XML you receive to specify what schema to use. Oasis Catalog implementations and .NET resolver implementation are set up to ignore those values. The XML editors I use are set up to use those values. The “As is” files provided with this article SHOULD NOT use the internal schema locations when they are run through your system.

Attributes

The GSE have used an attribute “gse:DisplayLabelText” on several elements. See Unique ID 10.354 in the specifications where it is defined for use on the “LiabilityType” element in LIABILITY_DETAIL.

The MISMO schema set as published allows attribute from any non-MISMO namespace to be used in the XML. Therefore, nothing specifically needs to be in our gse.xsd to support it.  However, it is beat practice to always define everything in your namespace. So we include a global attribute to define it. The specification wants a maximum length of “gse:DisplayLabelText”to be 150 characters. We create a simple type to define that restricted length and use it in the attribute definition.

Elements

There are two part to adding elements.
1. Change the definition of the EXTENSION/OTHER element to identify the GSE namespace element child of OTHER to be included. ( aka the bridge)
2.  Define the GSE namespace element in its file.

The Bridge

In section Validating Extension Data we decided to use the “Acceptable Practice approach. In it we redefine the unique OTHER definitions.

In Schema Sample 1 The Bridge we see how to build the bridge

Line 1 imports the GSE namespace definition

Line 2 begins the redefinition of the content of the new MISMOExtensionDetails_UCD.xsd file we created to match the technique from version 3.5.

Line 3 begins the redefinition of the LIABILITY_DETAIL_OTHER_BASE complex type.

Line 4 begins the declaration that LIABILITY_DETAIL_OTHER_BASE is complex, not simple (i.e a single fact)

Line 5 declares that we are building this new definition of LIABILITY_DETAIL_OTHER_BASE by restricting it. The name of the complex type in line 3 MUST match the name of the complex type being restricted.

Line 6 like the original the content of OTHER is a sequence. I sequence of just one item in this case.

Line 7 a reference to the IntegratedDisclosureSectionType element defined in the file gseUCD.xsd.

Line 8 end the sequence

Line 9 end the restriction

Line 10 end the complex content

Line 11 end the complex type

Line 12 end the redefine.

1     <xsd:import namespace="http://www.datamodelextension.org" schemaLocation="gseUCD.xsd"/>
2     <xsd:redefine schemaLocation="MISMOExtensionDetails_UCD.xsd">
3     <xsd:complexType name="LIABILITY_DETAIL_OTHER_BASE">
4       <xsd:complexContent>
5        <xsd:restriction base="LIABILITY_DETAIL_OTHER_BASE">
6         <xsd:sequence>
7          <xsd:element ref="gse:IntegratedDisclosureSectionType"/>
8         </xsd:sequence>
9        </xsd:restriction>
10      </xsd:complexContent>
11    </xsd:complexType>
12    </xsd:redefine>

When we add additional GSE data points the pattern will be the same as in Schema Sample 1 The Bridge. The additional complex type redefinitions will go lines 11 ad 12.

If you have selected any other approach from Validating Extension Data the pattern will be similar. For the “OK practice” approach I would move the LIABILITY_DETAIL_EXTENSION complex type to the top of the file. Edit the LIABILITY_DETAIL_EXTENSION complex type shown in Schema Sample 2 Before to look like Schema Sample 3 After.

Schema Sample 2 Before
1     <xsd:complexType name="LIABILITY_DETAIL_EXTENSION">
2     <xsd:sequence>
3       <xsd:element name="MISMO" type="MISMO_BASE" minOccurs="0"/>
4       <xsd:element name="OTHER" type="OTHER_BASE" minOccurs="0"/>
5     </xsd:sequence>
6     </xsd:complexType>

Schema Sample 3 After

1    <xsd:complexType name="LIABILITY_DETAIL_EXTENSION">
2     <xsd:sequence>
3       <xsd:element name="MISMO" type="MISMO_BASE" minOccurs="0"/>
4       <xsd:element name="OTHER" type="OTHER_BASE" minOccurs="0">
5        <xsd:complexType >
6         <xsd:sequence>
7          <xsd:element ref="gse:IntegratedDisclosureSectionType"/>
8         </xsd:sequence>
9        </xsd:complexType>
10     </xsd:element>
11    </xsd:sequence>
12   </xsd:complexType>

Enumerated Types
When a data point in the GSE namespace has a enumeration of valid values the gseUCD.xsd file should contain those definitions.
      <xsd:simpleType name="LateChargeEnum">
             <xsd:restriction base="xsd:string">
                   <xsd:enumeration value=""/>
                   <xsd:enumeration value="FlatDollarAmount"/>
                   <xsd:enumeration value="NoLateCharges"/>
                   <xsd:enumeration value="PercentageOfDelinquentInterest"/>
                   <xsd:enumeration value="PercentageOfNetPayment"/>
                   <xsd:enumeration value="PercentageOfPrincipalBalance"/>
                   <xsd:enumeration value="PercentageOfTotalPayment"/>
                   <xsd:enumeration value="PercentOfPrincipalAndInterest"/>
             </xsd:restriction>
      </xsd:simpleType>

References

Posted by at

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)