This tutorial area provides step-by-step instructions on how to build a moderately complex IEPD. Material from the “Hello World” IEPD series, reusable XML snippets, and other parts of NIEM’s GitHub site is used in the tutorials.
A NIEM IEPD is a package that describes the construction and content of a NIEM information exchange. It contains all of the schemas necessary to represent and validate the data content of the exchange. It is also contains supplemental artifacts, such as documentation, business rules, search and discovery metadata, and sample instances.
The process described here is a general outline of the steps that may be taken to create an IEPD, but may be adapted or customized as needed. The 300-series of the NIEM Training describes these steps in greater detail.
The first step in this stage is to identify existing related exchanges. Related non-NIEM based exchanges will support requirements analysis. A related NIEM IEPD can not only serve as an example, it may also be able to be adapted or reused. Such IEPDs may be found posted online, published in a local repository or the IEPD Clearinghouse, or via fellow practitioners, NIEM user groups, or the NIEM Help Desk (https://www.niem.gov/aboutniem/Pages/get-help.aspx).
Existing documentation should be reviewed to determine such things as the stakeholders of the exchange, current technical architecture requirements, security, privacy, and other-related concerns, content requirements, and the use of external standards.
Resource needs should also be reviewed. There will be a learning curve the first time a group or developer works with NIEM, but subsequent IEPDs tend to progress more quickly. Additionally, other factors like a new, poorly documented, or complex exchange, multiple stakeholders with varied requirements, or formalized approval processes may require more time and/or resources for IEPD development.
Finally, the business scenarios of the exchange may be modeled. Use case diagrams may be used to describe system interactions by the various actors and system functionality. Business process diagrams may be used to describe activity sequencing, like a workflow diagram, with stakeholders, activities, decisions, flow, and triggering events or results. Sequence diagrams may be used to describe how applications or systems interact with one another and the messages sent between them.
Each IEPD developer will have different methods for analyzing the requirements of a data exchange – the content requirements, exchange partners, the conditions that trigger an exchange, security requirements, etc. NIEM does not prescribe how this step should be performed, nor is knowledge of NIEM or XML Schema even required at this stage, so long as the subject matter experts capture the requirements and analysis with thorough detail.
The content portion of the requirements analysis can be done in a user-preferred format, such as a document, spreadsheet, or UML diagram. The kinds of information to be captured here include:
Data elements – These are the data fields for the message. For each field, the following information may or will be needed:
Element name – This is the name of the field / tag. Examples include First Name, Last Name, Street Address, Phone Number, SSN, Arrest Date, Unit Name, and Badge Number.
Data type – The structural representation or format of the element. Examples include string, date, number, boolean, state code set, person data type, location data type.
Definition – Descriptive definitions will be required for all components in the exchange. At this stage, the semantics need to be captured, but the wording does not have to be finalized or perfected. If in a later stage the element is determined to map to NIEM, then the NIEM element will come with its own definition. The definition captured here should be sufficient enough so that the meaning is clear.
Occurrence constraints – The minimum and maximum number of times an element may appear in the instance. For example, Last Name may occur once only, SSN may occur 0 to 1 times, Phone Number may occur 0 to many times.
Default occurrence constraints in NIEM are 0 to unbounded (with a few exceptions); the default in XML Schema is once only. Without explicitly setting these occurrence constraints, the defaults mean that components reused from NIEM will be optional and the ones added locally will be required.
Source information – Optional. It may be useful or necessary in some cases to record the source of the requirement. Traceability information may seem very apparent at the time but can be difficult to reconstruct at a later date if needed.
Note – if a corresponding NIEM element is already known at this stage, then the NIEM values may be used in place of local ones for element name, data type, and definition.
Objects / classes – These are the complex, reusable data structures where related elements are grouped together. Examples include Person (with elements First Name, Last Name, SSN, and Phone) and Location (with elements Street Address, City, State, and Zip Code).
Code sets – This is a list of allowable values, such as a state code list or an eye color list. Code sets may come from a standard or may be custom-defined.
Conditions / business rules – There may be certain restrictions on the content that need to be represented. Examples include restrictions on individual values (such as a number that cannot be less than zero or a string that must have a certain number of characters) and conditional restraints (such as if the SSN is not provided, then Last Name and Birth Date are required), etc.
The other requirements of the exchange – technical, security and privacy, performance, reporting, etc. – should be described in this stage as well.
There are various ways to implement this stage, but a common way to begin is by creating a spreadsheet to record the mappings of local components to NIEM components. Local elements, with their data types and definitions can be listed on one side, matching NIEM components on the other, and an additional field may be needed to capture any issues or problems.
There are several ways to discover NIEM content in this mapping stage. One way is by using the NIEM SSGT Tool. This tool allows you to search the model, follow links to discover related components, and build a subset so that rather than having to use the entire NIEM package schemas, you can create a much smaller, customized set of schemas with only the components you need. See the SSGT Tutorial for further information.
SSGT searches run on the components names themselves, plus their definitions and metadata. When trying to find matches for your local components, use words or common acronyms in the search box. Local tag names will be much less likely to return results. A search for tag names “FirstName” or “First_Name” will return empty because these exact terms do not appear in any NIEM names or definitions; a search for “First Name” will return the matching component, nc:PersonGivenName, based on a match in the definition.
If no match is found, replacing a search term with a common synonym may help.
Another way to discover NIEM components for mapping is by browsing through the [documentation spreadsheet] that is provided with each NIEM release. In these spreadsheets, there is a tab for Core and one for each domain, listing each of the components. It may be useful to skim over the Core tab and any domain tabs that are related to the exchange to get an idea of what kinds of components are available.
After the mapping is completed, there will be a set of local components that map to NIEM and a set that does not. For the set that maps, add each of the NIEM components to a custom NIEM schema subset using the SSGT as described in the SSGT Tutorial. Save the subset to the base-xsd subfolder in your IEPD package. Make sure to keep the subset wantlist (the save file) so that changes can be made later on without having to rebuild the entire subset.
For the set of local components that do not map to NIEM, add them to the IEPD by creating an extension schema:
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema version="1.0"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.example.org/SuperHero-extension"
xmlns:tns="http://www.example.org/SuperHero-extension"
xmlns:nc="http://release.niem.gov/niem/niem-core/3.0/"
ct:conformanceTargets="http://reference.niem.gov/niem/specification/naming-and-design-rules/3.0/#ExtensionSchemaDocument"
xmlns:ct="http://release.niem.gov/niem/conformanceTargets/3.0/"
elementFormDefault="qualified">
<xs:annotation>
<xs:documenation>This IEPD shows how to create a basic extension schema file with one element that reuses a NIEM Core type.
The context of this IEPD is based on Superheros.
</xs:documentation>
</xs:annotation>
<xs:import namespace="http://release.niem/gov/niem/niem-core/3.0/"
schemaLocation="..niem/niem-core/3.0/niem-core.xsd" />
<xs:element name="SuperHero" type="nc:PersonType">
<xs:annotation>
<xs:documentation> A person with super human abilities generally used to help others.
</xs:documentation>
</xs:annotation>
</xs:element>
</xs:schema>Additional artifacts are required in an IEPD. An mpd-catalog is required and must conform to the mpd specification. Other artifacts such as schematron rules, xml-catalogs, example instances, documentation etc. are also required however will not be covered in this tutorial. Schematron rules are not required but can be used to ensure the IEPD is following required business rules. A basic xml-catalog will get generated with the subset and can be modified as necessary. A sample xml instances is required per the MPD Specification and can be generated using an XML tool.
IEPD Artifacts:
NIEM MPD-catalog (required) – A specially-formatted XML instance that contains metadata about the IEPD.
<?xml version="1.0" encoding="UTF-8"?>
<c:Catalog xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:nc="http://release.niem/gov/niem/niem-core/3.0/"
xmlns:structures="http://release.niem/gov/niem/structures/3.0/"
xmlns:ex="http://example.com/iepd"
xmlns:mo="http://release.niem/gov/niem/domains/militaryOperations/3.1/"
xmlns:c="http://reference.niem/gov/niem/resource/mpd/catalog/3.0/"
xsi:schemaLocation="http://reference.niem/gov/niem/resource/mpd/catalog/3.0/mpd-catalog-3.0.xsd"
xmlns="http://reference.niem/gov/niem/resource/mpd/catalog/3.0/">
<c:MPD c:mpdName="example-iepd"
c:mpdVersionID="1"
c:mpdClassURIList="iepd"
c:mpdURI="http://example.com/">
<nc:DescriptionText>Example MPD</nc:DescriptionText>
<c:MPDInformation>
<c:CreationDate>2015-07-28</c:CreationDate>
<c:StatusText>Draft</c:StatusText>
</c:MPDInformation>
<c:IEPConformanceTarget> structures:id="C1">
<c:HasDocumentElement c:qualifiedNameList="ex:RootElement"/>
<XMLCatalog c:pathURI="base-xsd/xml-catalog.xml"/>
<c:IEPSampleXMLDocument c:pathURI="sample-xml/SampleXML.xml"/>
</c:IEPConformanceTarget>
<c:ReadMe c:pathURI="readme.txt"/>
<c:XMLCatalog c:pathURI="base-xsd/xml-catalog.xml"/>
<c:WantList c:pathURI="base-xsd/niem/wantlist.xml"/>
<c:ExtensionSchemaDocument c:pathURI="base-xsd/extension/Schema.xsd"/>
<c:SubsetSchemaDocument c:pathURI="base-xsd/niem/appinfo/3.0/appinfo.xsd"/>
<c:SubsetSchemaDocument c:pathURI="base-xsd/niem/conformanceTargets/3.0/conformanceTargets.xsd"/>
<c:SubsetSchemaDocument c:pathURI="base-xsd/niem/localTerminology/3.0/localTerminology.xsd"/>
<c:SubsetSchemaDocument c:pathURI="base-xsd/niem/domains/militaryOperations/3.1/mo.xsd"/>
<c:SubsetSchemaDocument c:pathURI="base-xsd/niem/niem-core/3.0/niem-core/xsd"/>
<c:SubsetSchemaDocument c:pathURI="base-xsd/niem/proxy/xsd/3.0/xs.xsd"/>
<c:SubsetSchemaDocument c:pathURI="base-xsd/niem/structures/3.0/structures.xsd"/>
</c:MPD>
</c:Catalog>
Change log (required) – An artifact that describes the changes applied to the IEPD since its previous version. IEPD developers may choose their own format for the change log. The change log for a new IEPD may simply be the release date.
ReadMe Artifact (required) – An informal documentation artifact that serves as the initial general source of human readable descriptive or instructional information. This artifact should at minimum describe the IEPD purpose, scope, business value, exchange information, typical senders/receivers, interactions, and references to other documentation.
XML catalogs – An XML instance that describes mappings between external schema references and locally-cached equivalents.
Sample XML instances (required) – A sample xml instance that serves as a test for the IEPD schemas. To the extent possible, the sample instance should contain realistic data and use as many data components and validity constraints as possible.
Conformance assertion – An artifact that provides a declaration that an IEPD conforms to relevant NIEM specifications and associated rules, including NIEM Conformance 3.0, NIEM Naming and Design Rules 3.0, NIEM Conformance Targets Attribute Specification 3.0, and NIEM MPD Specification 3.0. A weak conformance assertion may simple self-assert that the IEPD is NIEM-conformant. A strong conformance assertions may include such things as the kinds of reviews and checks performed and the output from the NIEM Conformance Tool
Optional IEPD Artifacts – These may include: