18 May 2010: Added links to Part 4 of this series in Introduction, Conclusion, and Resources sections.
09 Mar 2010: Added links to Part 3 of this series in Introduction, Conclusion, and Resources sections.
Now that you've created a UML model of your exchange (see Part 1), the next step is to map your model to NIEM to determine what parts of NIEM you will reuse in your messages. This mapping is most commonly done in a spreadsheet, known as a Component Mapping Template (CMT). The CMT is useful for several reasons:
- It provides a detailed, human-readable definition of your exchange model with places for comments and extra documentation.
- It makes explicit which parts of the model reuse NIEM components and which are custom to the Information Exchange Package Documentation (IEPD).
- It serves as a convenient checklist when you make a subset of the NIEM model.
You typically create CMTs in Microsoft® Office Excel® or other spreadsheet software, such as OpenOffice.org Calc. However, you can create them in any tabular format. There is no one required format for a CMT, but a typical CMT has, at a minimum, the following columns:
- Source type. The name of the class in the UML model
- Source property. The name of the property in the UML model
- Data type. The data type of the property
- Description. A short description of the type or property
- Cardinality. How many of the properties are allowed to appear
- Extension indicator. Whether the model matches a component in the NIEM model
- XPath. The path to the element in an XML message
Some NIEM implementers add more columns to the CMT to represent the details of extending NIEM. Part 3 of this article series will look further into extending NIEM.
Your first step is to record your UML model in the first five columns of the CMT.
Part 1 of
this article series introduced a UML diagram of a simple example case that
involved reporting on the theft of registered vehicles. Based on that UML class
diagram—shown again in Figure 1—Table 1
TheftLocation class in CMT format.
Descriptions are omitted from the table to save space, but a completed
example CMT is available from Downloads. (View a text-only
version of Figure 1.)
Figure 1. UML model diagram from Part 1
Table 1. Representing a type and properties in the CMT
|Source type||Source property||Data type||Description||Cardinality|
In the Data type column, XML Schema simple type names are used. In
the case of code lists, a code list name is specified, and the valid values
are documented in another tab of the spreadsheet. Cardinality shows
the minimum and maximum number of occurrences, where
represents an unbounded number.
Each association should have a row in the CMT, along with rows for references to
the types involved in the association. Table 2 shows a
CMT representation of the
Table 2. Representing an association in the CMT
|Source type||Source property||Data type||Description||Cardinality|
Role types should be shown with references from the role to the type that is
playing the role. The
Witness role type in
Table 3 contains a reference to
Table 3. Representing a role in the CMT
|Source type||Source property||Data type||Description||Cardinality|
The next task in mapping your exchange is to determine where your model overlaps with NIEM and record those elements in the CMT. You want to reuse NIEM as much as possible to maximize interoperability with other NIEM applications. An IEPD is not NIEM-conformant if it adds new components when semantically equivalent components already exist in the NIEM model. That said, you should not force data into NIEM if it really doesn't fit. Part 3 of this article series will explain how to add new components to the model.
Because the NIEM model is very large, you do not want to scan the schemas by hand looking for matching components. Fortunately, several online tools are available to find components in the NIEM model (see Resources for links to these tools):
- NIEM Wayfarer. Using this tool, you can search for NIEM components and traverse through the model with one page per component.
- Schema Central. This tool has similar capabilities to NIEM Wayfarer but works with a variety of XML vocabularies, not just NIEM.
- NIEM Schema Subset Generation Tool (SSGT). Use this tool to search and navigate the NIEM model in a slightly more graphical fashion. It has the added capability of generating a NIEM subset once you find the components of interest.
Use one of these tools to look for all the components in your CMT that might already exist in NIEM. As an example, when you search for the term Vehicle in Schema Central, you see the search results page in Figure 2.
Figure 2. Schema Central search results page
When you click nc:Vehicle, the page in Figure 3 is displayed. It shows some general characteristics of the element, followed by a complete listing of its possible children.
Figure 3. Schema Central element display page
All of the NIEM components have a namespace prefix: nc refers to NIEM Core, the namespace in which the most fundamental types reside. There is also a namespace for each of the domains (for example, j for Justice). Feel free to use NIEM components from any domain as long as they are semantically equivalent to your model. You don't have to be implementing an immigration-related exchange to use an element from the immigration domain.
Regardless of which tool you use, you can make searching the model easier by following these tips:
- It is often easier to start by looking for the highest-level types/classes
(in the example case,
Location, and so on) first, and then finding the appropriate properties.
- Don't forget to search for synonyms. If you don't find License Plate, look for Registration.
- If you can't find your specific component, look for a more general one. Some
of the most general types in NIEM are
Item. For example, if you don't find Theft Location, you can look for Location more generally and use
nc:Location. If there is not a specific type for Theft, consider using the more generic
- Don't just search names. If you expand your scope to search descriptions and enumerations, it might lead you to the appropriate type.
Finding components in the NIEM model might seem daunting at first, but it gets easier as you become more familiar with the general naming and structural patterns of the NIEM model.
When you find an equivalent NIEM component, record it in the CMT in the XPath
column. Generally, simple XPath expressions are used—element and/or
attribute names are separated by slashes (
/). Type names
do not need to be included in the XPath. Use namespace prefixes such as nc:,
because element names are not necessarily unique across namespaces.
Table 4 shows the XPath mappings for
TheftLocation. Note: For formatting purposes,
the longer XPath mappings are split to multiple ines in the table. The mappings are normally a
single string without blank spaces.
Table 4. TheftLocation XPath mappings
|Source type||Source property||...||Ext?||XPath|
You should include enough steps in the XPath to uniquely identify it. For example,
don't just put
nc:StreetFullText in the row for
Address. Sometimes, multiple paths can lead to an
element in NIEM, and the entire path is needed for precision.
In the example, the
CountyCode property, which is a
state-specific county code, is not found in NIEM, so it will require an extension.
Therefore, the Ext? column is set to
Y, and the
XPath is left blank for now. Part 3 of this article series will walk through the process
of filling in the XPaths for extensions.
For a complete mapping of the Theft Report example model to NIEM, see the spreadsheet available from Downloads.
When you have decided which components of NIEM you want to use in your exchange, you create a subset of the NIEM model that takes the form of a set of XML Schema documents. Because the full NIEM model is so large and loosely constrained, a NIEM subset is necessary to validate your exchange more precisely. The NIEM subset restricts the elements and attributes allowed, the number of times they can occur, and—in some cases—their allowed values. Creating a NIEM subset also speeds up validation of XML messages, because the schemas are much smaller.
You create NIEM subsets using the NIEM SSGT. The initial page of the SSGT in Figure 4 has two panes. The right pane is where you search and navigate the model, and the left pane shows your subset as you add components to it.
Figure 4. SSGT main page
Based on your CMT, you perform searches to find components to add to your subset. Using the SSGT, you can choose to search either properties (element or attribute names), types, associations, or other components. Because you have the names of the element in your CMT, it makes sense to search properties. Sample search results are in Figure 5.
You might wonder why mapping and subsetting are two separate steps when you can perform the tasks in the same tool (the SSGT). It is certainly possible to perform the mapping and subsetting at the same time using the SSGT. However, many NIEM practitioners find it easier to do the mapping with NIEM Wayfarer or Schema Central, which shows the actual (flattened) structure of the types more clearly. The SSGT requires more knowledge of NIEM (and more clicking) to navigate, so going to the SSGT prepared with a CMT that lists exactly what you want from NIEM makes subsetting more efficient.
Figure 5. SSGT search results page
When the NIEM component of interest is displayed, click Add to add it to your subset. It then appears in the left pane under NIEM Schema Subset, as in Figure 6.
When you add a property, its type automatically goes with it. For example, if you add
is automatically added to the subset, as well. The components you explicitly
selected appear in the left pane in bold, with a check box next to them, while
the dependent components are not in bold.
Figure 6. SSGT subset
The SSGT does not add the child properties of a type by default. For example, if you
nc:PersonName, it does not include the properties
These you must add to the subset separately. When you add them, you must do so in
the context of
nc:PersonName so that the parent-child
relationship between, for example,
nc:PersonGivenName is maintained. To do this,
nc:PersonName tree in the SSGT search
results and click Add next to
as in Figure 7.
Figure 7. Adding a child using the SSGT
If instead you separately searched for
and added it from the search results, the element would be added but not as a child
Figure 7 also shows that when you add a property of a type, you can specify the cardinality. Clicking the right down arrow on the Add button brings up a drop-down menu that shows possible cardinalities. The default is 0 to infinity.
If a property is included by inheritance, it is not displayed in the SSGT hierarchy by default.
For example, expanding
nc:Vehicle in the SSGT search
results does not automatically show the
that is mapped to the
Property Description property. To
see these inherited properties, click show inheritance (next to
nc:VehicleType) and expand the type that contains
the property of interest—in this case,
nc:ItemType, as in Figure 8.
Figure 8. Adding an inherited property using the SSGT
The NIEM model commonly uses XML Schema abstract elements and substitution groups.
For example, there are several ways to represent the color of an item. NIEM has an
cannot appear anywhere in an XML instance. Instead, it must be substituted by one
of several elements, such as
nc:ItemColorDescriptionText. In XML Schema terminology,
nc:ItemColorDescriptionText are said to be members of
a substitution group whose head is
The abstract elements add some complexity to the creation of a subset, because you are required to add the substitutable elements in your subset, not just the abstract element. The SSGT marks all abstract elements with the word abstract and allows you to expand them to see the substitutable elements, as in Figure 9.
Figure 9. Adding a substitutable element using the SSGT
Most date-related types also contain an abstract element
nc:DateRepresentation that is substitutable by
so on. It is an easy mistake to simply add a date-related property, such as
nc:ActivityDate, without expanding it to click on
nc:DateRepresentation, and then
nc:Date to allow for the appropriate child elements.
When you have created your subset, you can modify it using the left pane of the SSGT. You can choose to delete any component by selecting the check box next to it, and then clicking Delete. You can also delete allowed code list values by expanding the appropriate simple types in the left pane. By default, all code list values from a simple type are included in the subset.
You can also choose to change the cardinalities by clicking Edit Cardinality at the top of the left pane. Doing so gives you another opportunity to decide how many of a particular property are allowed in a parent type.
Your NIEM subset does not have to be perfect at this point. NIEM subsetting is often an iterative process. You can save and modify your subset as needed during the final stages of IEPD development.
To generate your subset, click Generate Documents in the upper right corner of the page. Doing so brings up a window similar to Figure 10 that shows some generation options. Select Save Subset Schema to a file, and choose the location in which to save it.
Figure 10. Generating a subset using the SSGT
Doing so creates a .zip file called Subset.zip with a niem subfolder that contains the NIEM subset. It has a schema document for every namespace from which you chose elements in the SSGT plus a few standard schemas that come with all subsets.
Only the types you chose are included in the schema documents, and those types only
contain the chosen properties. For example, although the
nc:PersonNameType has seven possible children in
the entire NIEM model and they all have cardinalities 0..*, your subset schema will
contain only what is in Listing 1.
Listing 1. nc:PersonNameType in NIEM subset
<xsd:complexType name="PersonNameType"> <xsd:complexContent> <xsd:extension base="s:ComplexObjectType"> <xsd:sequence> <xsd:element ref="nc:PersonGivenName" minOccurs="0" maxOccurs="1"/> <xsd:element ref="nc:PersonSurName" minOccurs="0" maxOccurs="1"/> </xsd:sequence> </xsd:extension> </xsd:complexContent> </xsd:complexType>
The subset also contains an XML document called wantlist.xml, which lists all of the components you added to your subset along with their cardinalities. The wantlist is useful if you need to make changes later: You can re-upload the wantlist to the SSGT, modify the subset, and regenerate. Listing 2 shows part of the wantlist.
Listing 2. Partial NIEM subset wantlist
<w:WantList w:release="2.1" w:product="NIEM" ...> <w:Element w:name="j:Person" w:isReference="false"/> <w:Element w:name="j:Witness" w:isReference="false"/> ... <w:Type w:name="j:PersonType" w:isRequested="false"> <w:ElementInType w:minOccurs="0" w:maxOccurs="1" w:name="j:PersonAugmentation" w:isReference="false"/> </w:Type> <w:Type w:name="j:WitnessType" w:isRequested="false"> <w:ElementInType w:minOccurs="0" w:maxOccurs="1" w:name="j:WitnessAccountDescriptionText" w:isReference="false"/> <w:ElementInType w:minOccurs="1" w:maxOccurs="1" w:name="nc:RoleOfPerson" w:isReference="true"/> </w:Type> ... </w:WantList>
In this article, I showed you how to map a UML exchange model to NIEM using a CMT. I then described the process of creating a NIEM subset using the NIEM SSGT. In Part 3 of this series, I will address the rows of the CMT that were not filled in yet: the extensions. I will explain the different approaches to extending NIEM and take you through the process of creating Exchange and Extension schemas.
|Component Mapping Template (CMT)||niem2mapping.zip||62KB||HTTP|
- NIEM: Refer to the NIEM Web site for additional information about the purpose and approach of NIEM.
- NIEM Practical Implementer's Course: Get more detailed guidance in NIEM mapping and subsetting by attending this course, which is available online at no cost.
- Creating a NIEM IEPD, Part 1: Model your NIEM exchange: Design an XML information exchange between US government entities (Priscilla Walmsley, developerWorks, January 2010): Design an XML information exchange between US government entities. Set up a start-to-finish solution using the National Information Exchange Model (NIEM), a U.S. government-sponsored initiative to facilitate information sharing among public and private sector organizations in this series of four articles.
- Creating a NIEM IEPD, Part 3: Extend NIEM: Design an XML information exchange between US government entities (Priscilla Walmsley, developerWorks, March 2010): In Part 3 of this four-part article series, learn what to do about the parts of your model that do not map directly to NIEM, as you walk through the process of creating extension and exchange schemas.
- Creating a NIEM IEPD, Part 4: Extend NIEM: Design an XML information exchange between US government entities (Priscilla Walmsley, developerWorks, May 2010): In the last of this four-part series by Priscilla Walmsley, cover the final step as you assemble the schemas, documentation, and all the other artifacts of an exchange into a complete NIEM-conformant IEPD. This article also describes the process of validating and publishing your IEPD.
- XML area on developerWorks: Get the resources you need to advance your skills in the XML arena.
- IBM XML certification: Find out how you can become an IBM-Certified Developer in XML and related technologies.
- XML technical library: See the developerWorks XML Zone for a wide range of technical articles and tips, tutorials, standards, and IBM Redbooks.
- developerWorks technical events and webcasts: Stay current with technology in these sessions.
podcasts: Listen to interesting interviews and discussions for software developers.
Get products and technologies
- NIEM Wayfarer and Schema Central: Try out these tools to search and navigate the NIEM model.
- NIEM Schema Subset Generation Tool: Use the SSGT to create a NIEM subset.
- IBM product evaluation versions: Download or explore the online trials in the IBM SOA Sandbox and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.
- XML zone discussion forums: Participate in any of several XML-related discussions.
- developerWorks blogs: Check out these blogs and get involved.
Priscilla Walmsley serves as Managing Director and Senior Consultant at Datypic. She specializes in XML technologies, architecture, and implementation. Most recently, she has been working (through Trusted Federal Systems) with the U.S. Department of Justice on LEXS, a NIEM-based IEPD framework. She is the author of Definitive XML Schema (Prentice Hall, 2001) and XQuery (O'Reilly Media, 2007). She is also the co-author of Web Service Contract Design and Versioning for SOA (Prentice Hall, 2008). You can reach Priscilla at email@example.com.