Understanding MISMO XML Model Extensions
September 10, 2020
In this article, we review how MISMO Extensions are designed and why. We use a simplified version of the iLad schema to show how you can create your own extension to the MISMO schema.
MISMO Extension Model Goals
The MISMO architects had the following goals for the extension mechanism:
- Any container element should be extensible. In the MISMO vocabulary, a “Container Element” is an element that contains other elements, instead of contained data directly. Think of an analogy to a database. A container element holds data points like a database table holds columns.
- Anyone should be able to extend the MISMO standard without ever having to modify the MISMO-published schema files. Editing the MISMO copyrighted files is bad practice because we may end up with schemas that unintentionally masquerade as the official MISMO files. It is also a violation of the MISMO copyright.
- Multiple organizations might want to extend the model at the same time. The model should allow that. In fact, that is exactly what we see in the MISMO iLAD specification. There are extensions from Fannie Mae and Freddie Mac both.
- The extended schema should be able to validate the MISMO data and all the extension data, all in one pass.
MISMO XML Extension Points
Each container in the MISMO Data Model has an element called EXTENSION of an XML data type that is defined specifically for extending that container. For example, the LOAN container has an EXTENSION element of type LOAN_EXTENSION. The extension types are all structured in the same way, as shown in Figure 1 below.
Figure 1 - MISMO Extension Type Template
Each extension type is composed by two sub-elements: MISMO and OTHER. The MISMO element is reserved for extensions published by MISMO. The OTHER element is available for extensions created by anyone else. It can contain any valid XML from any namespace, except the MISMO namespace. That is denoted by the xsd:any element with a namespace of ##other, as shown in figure 2 below:
Figure 2 - Definition of OTHER
How to Extend the MISMO Data Model
At the high-level, the process of extending the MISMO schema consists in providing new definitions for the MISMO extension points. To do that, we need to create two schema files:
- The first file is an extension schema that contains our custom element definitions.
- The second file is a wrapper schema that brings together the MISMO standard definitions and our custom definitions for the extension points we want to use.
This process is explained in the sections below.
Creating an Extension Schema
To create a schema for our extensions, we simply need to create a schema with a target namespace that is unique to our company or project. Having a unique target namespace is important because it distinguishes the element names that we create from definitions created by other companies and organizations. For example, in the case of the ULAD extensions, we use http://www.datamodelextension.org/Schema/ULAD as the target namespace.
The figure below shows a sample extension schema. This is a simplified version of the one used in the MISMO iLAD publication.
Figure 3 - Sample Extension Schema
In line 3, we declare the target namespace.
In line 6, we bring in the MISMO data types so that we can use them. In this example, we are making use of the MISMOIndicator type, as shown in line 14.
In line 7, we define a xsd:group to contain our desired extensions. We could have declared our custom extensions as global elements by placing them directly under the xsd:schema element. However, placing our custom elements inside of a xsd:group has the added benefit of preventing them from being accidentally used as root elements.
Creating a Wrapper Schema
To combine the MISMO standard definitions with our custom definitions, we need to create a "wrapper schema". This schema will also become the main schema to be used for creating and validating our custom data files.
The figure below shows the starting point of a wrapper schema:
Figure 4 - The Wrapper Schema, Step 1
In line 2, we set the target namespace to be the same as the standard MISMO target namespace, i.e., http://www.mismo.org/residential/2009/schemas.
In line 5, we use xsd:redefine to bring in the MISMO standard schema. The xsd:redefine statement is similar to xsd:import, but, in addition to importing the definitions from another schema, it allows us to redefine any of the XML data types defined in that schema.
At this point, we have a generic wrapper schema that will validate the same data files as the original MISMO schema. The section below describes how to bring in our extensions.
Bringing It All Together
We will now bring our extension schema into the wrapper schema, as shown below:
Figure 5 - The Complete Wrapper Schema
Lines 2 and 3 define the namespace prefixes for MISMO and ULAD.
In lines 7 and 8, we use the xsd:import statement to bring in the extension schema that we created before.
In lines 10-12, we specify the name of the MISMO XML type we want to redefine and the kind of redefinition we want to perform. In this case, we are using xsd:restriction, which means that the only content allowed inside of that element will be what we provide here.
In line 14, we duplicate the standard definition for the MISMO element. That is recommended to allow for extensions that MISMO may eventually publish for that container.
In line 15, we redefine the OTHER element to contain the grpASSET_DETAIL_EXTENSION group that we created in figure 3. In other words, instead of using the standard MISMO definition for OTHER, we construct our own definition for that element.
We now have a complete wrapper schema the can be used to validate any MISMO XML file, but only permits the ulad:IncludedInAssetAccountIndicator element inside of ASSET_DETAIL/ASSET_DETAIL_EXTENSION/OTHER.
Sharing your Extension Schema
Once you finish creating your wrapper schema, you may want to share it with your business analysts and software developers. One option is the Grid-ML XML Schema Viewer , shown in Figure 6 below. Grid-ML has full support for the MISMO extension mechanisms and also allows users to search the schema for elements of a specific namespace.
Figure 6 - Grid-ML Search Screen for the iLAD Schema
MISMO extensions are an important part of the MISMO V3 architecture. In this article, we provided a step-by-step process for creating an extension without having to edit a MISMO base files.
Greg Alvord is a Senior Data Architect at a Fortune 500 company and has been a member of MISMO since 2000. He served many years as the Chairman of the Architecture Committee. In May of 2007, Greg was appointed to be the V3 Chief Architect and supervise the design and release of the MISMO V3 architecture. Greg has authored white papers appearing in the American Bankers Association Journal and the Mortgage Technology Magazine. Greg Alvord is also a partner in GridML LLC, which developed the Grid-ML XML Schema Viewer.