Review the data requirements captured during the previous phase and discover if there are similar components in NIEM. Document results in a mapping spreadsheet. Begin modeling the data requirements without a match in NIEM; these will be later added added to the IEPD as extensions.
Some IEPD developers skip the mapping document and go straight from documenting data requirements in the previous step to building schemas in the next step. This can be done and a mapping document is not a required artifact in an IEPD; however, this kind of mapping can provide the following advantages:
Provides an easy way to allow others to review and confirm mapping and modeling decisions before beginning to build extension schemas.
It can be useful to allow others, especially subject matter experts involved with the exchange, to review the work in progress. Spreadsheets are typically easier to use when reviewing lists of elements names and definitions, plus can be used to capture comments and feedback.
Clearly captures the source data requirement for each of the properties that will appear in the exchange.
This information is often fairly obvious during development, but can be easily forgotten over time or lost as the original IEPD developers move on to other projects. Reverse-engineering where initial requirements came from at a later date can be challenging.
Identifying and recording mapping is a manual process. It becomes easier as you gain familiarity with NIEM and learn what’s available and where things are, but can be slow-going for those new to NIEM. There is no automated way of identifying matches. For each data requirement, NIEM should be searched and the success or failure of that search should be recorded.
There are multiple ways NIEM can be searched for matches.
|Tool / Product||Description|
|SSGT||Use the SSGT to search any NIEM release. Property, type, and code information will be available.|
|Movement||Use Movement to search the current NIEM release. Movement has a fast search capability and a more modern UI, but note that some information about NIEM is not displayed, like abstract elements, associations, code sets, and type details like inherited properties.|
|Model spreadsheet||Download the model spreadsheet that comes with a NIEM release and review property and type information in Core and domain-specific tabs.|
|Release schemas||Download a NIEM release package and explore the model in an XML or text editor.|
|Tools catalog||Check the Tools Catalog on niem.gov for a listing of third-party tools, some of which can be used to search and discover content in the NIEM model.|
A mapping spreadsheet should have three main sections:
Data requirements for the exchange
The most basic kind of a mapping spreadsheet is shown below. This is the minimum amount of information needed to capture mappings between data requirements and NIEM components.
|facebook username||no match|
NIEM provides a mapping spreadsheet template that can be used to both document mappings and to begin modeling extensions. To use the spreadsheet for mappings only, focus on the “Property” tab and ignore the other tabs unless needed. Customize the spreadsheet by hiding columns that won’t be needed.
IEPD developers can begin to plan out and model the content that does not map to NIEM and therefore will need to be added in extension schemas.
See the Mapping Spreadsheet – Modeling examples section for basic information about modeling new extensions in the mapping spreadsheet.
The following are some very basic tips for getting started with modeling new extensions:
See the Property section under Reference / Concepts for more details about the various kinds of properties in NIEM, along with naming and definition tips and examples.
Come up with NIEM-conformant property names and definitions.
NIEM property names are composed of class terms, property terms, qualifier terms, and representation terms.
NIEM definitions for properties that carry a value (like a string, boolean, or number) should begin with the standard opening phrases provided by the NIEM Naming and Design Rules (NDR).
See the Type section under Reference / Concepts for more details about the various kinds of types in NIEM, along with examples.
Reuse a type directly from NIEM if possible.
nc:PersonTypealready contains everything needed for a new vice principal element, reuse that type from NIEM as is.
IEPDs can reuse types from Core, a domain (even if the domain doesn’t directly relate to the IEPD’s subject matter), a code set, or any other namespaces in NIEM.
Very frequently reused types in NIEM include
If a NIEM type is close but doesn’t quite fit all of the requirements, then there are several options:
Create an augmentation if the NIEM type is semantically a match but needs some extra properties added.
nc:PersonTypeseems like a good fit for the new vice principal element but the IEPD needs a few extra person-related properties that aren’t specific to a vice principal (like a LinkedIn profile URL), create an augmentation.
Create a typical type extension if the requirements need a specialization of a NIEM type. This is also known as type inheritance or type specialization.
If the IEPD needs to model a train,
nc:VehicleTypeshould be extended. An augmentation would not make sense here because additional train-specific properties for things like locomotive and number of cars would not apply for other generic vehicles.
Create an association if the requirements need to relate two or more peer-level objects, often within a certain date range.
Associations can be especially useful to eliminate duplication in messages for many-to-many relationships.
If the IEPD needs to relate teachers and students, and also needs to capture information like grade, subject, and class period, create an association. This can be used to represent that one teacher might instruct one subject all day to different groups of students while another teacher might instruct the same group of students all day. The basic information about the teachers and students would appear once in the message, and then multiple instances of the association could be used, each containing pointers to the teacher and student data objects, plus the data values for the class-specific information.
Create a role if:
If the IEPD needs to model a vice principal with specific properties for that position, but the person may also need to be represented in the IEPD as a coach and as a study hall monitor, then a role could be created. The role types for vice principal, coach, and monitor would each contain a pointer to person object, so basic person information does not have to be duplicated in the message.
Create a brand new type when no type in NIEM matches requirements.
The type should still likely extend
structures:ObjectTypein NIEM. This will allow it to be referenced, link to metadata, and contain security markup information.
If similar code sets exist in NIEM and the local codes from the data requirements can be mapped to them, try to use the NIEM version for better interoperability.
If that is not an option or a similar code set does not exist in NIEM, create the code set.
If an existing NIEM code set has most of the code values needed, but the IEPD requires a few extra codes, a union type can be created. Union types allow separate simple types to be combined together so multiple code sets can be combined into a single simple type without duplication.
A new code element should be created for the new code set type. This element can either then be added directly to an extension type or to a substitution group in NIEM if one exists.
ext:ClassSubjectCodeas a sub-element of type
ext:PersonHairColorCodeas a substitution for NIEM element
The mapping spreadsheet, filled with exchange data requirements, matching components in NIEM, and optionally containing information about how to start building extensions, will be used in the next phase of IEPD development, Build and Validate. This spreadsheet should also be included in the final IEPD package.