NIEM Guy - NIEM, XML, and .NET

There are several publicly available tools to search the NIEM 2.0 reference model and generate schema subsets that you can bring into a project.  The primary tool I use is the NIEM Tools site maintained by Georgia Tech.  This is also the site that is linked to from Niem.gov when you click the "tools" link.

There is also a fine site out there called "Niem-o-Rama" that links to a lot of other tools that help with the Information Package Exchange Documentation Process (IEPD Process).  The IEPD process defines the steps you follow to create an "exchange": a definition of the model and xml structure of the documents you will be exchanging.  Those of us who think SOA would call this part of the contract.  Using the Niem Tools available you will be generating the schemas that will define the documents you wish to exchange.

For this tutorial we will be using the Schema Subset Generator Tool (SSGT) maintained by GA Tech.  Once you connect to the IEPD tools site, hover over "Search/Navigate Model" and then choose the top option - Search/Navigate Textually.  I find this one easier to use, but if you want one with a bit of a GUI you can choose the second option.

The way this tool works is that you search on attributes (properties/elements) or names you want to find in the model.  Once you locate the item you want you can add it to your subset (equate it to a shopping cart for NIEM elements and schemas).

Let's begin the tutorial:

1) Navigate to http://niem.gov and click on tools, then "Search Navigate Model"  and "Search/Navigate Textually (shortcut for those of you who need one)

2) For this example let's assume we have been asked to create a schema subset that can contain a person.  So we will pull in stuff related to the Niem Person (as we'll learn soon person is mostly defined in the NIEM Core namespace.  When searching the NIEM schemas you can search different elements, associations, etc.  Most of the time I recommend searching property.  So go ahead and search for "Person"

You probably noticed you get all kinds of stuff back from namespaces other than nc (Niem Core).  You can change that by clicking advanced and unchecking all the namespaces you don't want.  Other wise get used to filtering through your results and picking out the namespace you want.

3) Locate "nc:Person" which should show that it is of type PersonType.  Next to it should be a button that says "Add", clicking this will add the nc:Person element and nc:PersonType to your cart.  Now doing this only adds that basic definition, you now must pick and choose your way through the rest of nc:Person to find what else you might need.

A note here.  NIEM Is very complex and very deep.  It's inheritance hierarchy is very, very complex and you must really hunt to find things.  Sometimes you will be working with an element that may be a great grandchild to another and you won't even realize it (a good example is vehicle.  VehicleType inherits from ConveyanceType which inherits from TangibleItemType which inherits from item type which inherits from ComplexObjectType.  This tool does not always make that clear.  For reference you might want to go to the main NIEM site and just download all of the schemas.  I do not recommend including the whole Niem core in your project.  It is way too big.  That is why the subset generator is so useful. 

Schemas consist of many things, the main two being ComplexType definitions and elements.  Elements are what are exposed as usable tags from your schema.  For a ComplexType to be useful you must expose an element for it.  ComplexTypes can also contain elements (attributes to, but those are a "special" kind of element if you will).  So, back above when I said to search for Person under property, had you chosen type and found nc:PersonType and added that you would find upon using your schema you had no valid elements.  So be sure if you add a type to add the element that references that type.

You also have to understand what elements can contain a value and what elements are complex.  For instance, PersonAccentText is a simple TextType that can contain a value, ex. <nc:PersonAccentText>English</nc:PersonAccentText>.  However, PersonName is a complex type (PersonNameType) and you cannot have <nc:PersonName>Chris</nc:PersonName>.  That is invalid.  The correct structure is:
<nc:PersonName>
 <nc:PersonGivenName>Chris</nc:PersonGivenName>
</nc:PersonName>

So keep those things in mind as you pull your schema in.

 4) Once you have added all the properties (elements) for nc:Person that you need you are ready to "check out".  In the upper right look for the "Generate Documents" link.  Click that.  I usually opt to include documentation.  That will include the annotation that the NIEM creators added.  This is useful for understanding the semantic meaning for the elements you pulled in.  When you click "Save schema subset to a file" it will prompt you to download a zip file.  The zip file will contain a wantlist which you can use to reload your schema into the cart (if you need to add things later you don't have to add it all over again) and also the NIEM subset schemas you requested.  If you requested elements from different namespaces it will download all those for you as well and put them in a nice logical folder structure.

Your next question - how do I use them?  That is a much bigger one and again, I highly recommend the IJIS training.

For those of you in Visual Studio 2008 you can copy the folder structure from the schemas zip into your project.  At that point you can create an extension schema in your own namespace and reference the NIEM schemas you generated.  Then you are ready to create a document and start using it.  (That is the highly glossed over high level view...much more to it than just that).

Screenshots:
Search Navigate Model
Data model search
Advanced Search Settings
nc:Person
Adding Elements
NIEM "Shopping Cart"
Schema Subset Generation
Zip File Folder Structure