Developer Resources


We are currently working to modernize our training materials. We’re giving NIEM training a major revamp—updating the content, changing the delivery format in favor of user-driven tutorials and easy-to-use reference content, and moving all training materials to NIEM’s GitHub site. In addition to the content on this page, be sure to check out the technical materials and reference content currently in beta on NIEM.github.io/training.


Since NIEM exchange developers follow the same development lifecycle, they can borrow from and reuse each other's work. An exchange developed for one organizational business need could be reused (partially or fully) for a different need within that or another organization.

In an era when return on investment has never been more important to government services, NIEM enables organizations to exchange information in a manner that is both effective and efficient. Be sure to check out the NIEM Cost Model, which allows users to quantify the associated costs of adopting NIEM.

High-level overview of NIEM architecture

As a point of reference, let’s explore the graphic below as a simple introduction to NIEM architecture.

Introduction to NIEM architecture. There are 4 Layers of the Architecture. Layer 1: The NIEM Reference Model is a collection of data components organized into the NIEM core and specialized domains. NIEM includes Federal, State, Local, Tribal, Private sector, and International communities with shared interests in Surface Transportation, Screening, MilOps, Maritime, Justice, International Trade, Intelligence, Infrastructure Protection, Immigration, Human Services, Emergency Management, CFYS, CBRN, and Biometrics. Future Domains is highlighted in the model (as other interests can be added). NIEM domains are communities of interest that are formally established, with an executive steward, to officially manage and govern a portion of NIEM. These components provide the NIEM common vocabulary, structure, and semantics. Layer 2 (Optional): The Enterprise Information Exchange Model (EIEM) is the creation of a custom set of IEPDs. First, a subset is built using data components needed for the set of IEPDs. Next, the subset is extended from the model as needed to satisfy missing requirements. Then a family of IEPDs can be built by re-using the master subset, associated extentions, and possibly external standards. Layer 3: An Information Exchange Specification defines a given recurring information exchange by reusing data components in a release of the NIEM reference model. The developer incporates the necessary NIEM core and domain model content. Layer 4: The Implementation of the Message includes hardware, software, or system infastructure needed to send and recieve the data instance documents that carry data and are defined by one or more IEPD.


IEPD lifecycle overview

To use NIEM, you normally build an Information Exchange Package Documentation. An IEPD defines a recurring message in XML and is built to satisfy information exchange business requirements.

The developer may also extend that content as needed to account for information requirements that are not yet addressed in NIEM. The IEPD will ultimately define XML instance documents that will contain the information to be exchanged. Extended and new content developed in IEPD extension schema documents should be considered for future model updates. In turn, domain and core model updates will be harmonized and integrated into future NIEM releases. In this way, NIEM evolves with new and changing needs.

An IEPD is a combination of both business and technical information.

From a technical perspective, an IEPD is a set of XML schema documents that define instance XML documents which, in turn, will tag and carry the data and information to be exchanged. For example, when you want to exchange "person" data and its related attributes, you will leverage (essentially reuse from a NIEM release) XML schema components that define the “person” related tags and structures.

From the business perspective, an IEPD provides documentation such as business scenarios and other aspects of the business requirements for the exchange, including a catalog of its content, a change log, a conformance assertion, etc. In addition, reusing existing IEPDs that meet or can be easily adapted for similar business requirements is encouraged, and can save time and money!

NIEM follows a six-phased approach to IEPD development:

IEPD LIfecycle. There are 6 phases. Scenario Planning, Analyze Requirements, Map and Model, Build and Validate, Assemble and Doucment, Publish and Implement


Building IEPDs

Complete the initial tasks associated with defining an information exchange.

Key considerations

You can help expedite the work in this phase by collecting prior documentation created for the information exchange, or a similar information exchange. IEPDs are designed to be re-usable, so leveraging already existing exchanges can reduce the work required to build a new exchange.

Examples of documentation include:

  • Business process documentation
  • Stakeholder interviews
  • Work flow diagrams
  • Data flow diagrams

Additional information may include insights into the current technical architecture of exchange partners, use of external standards, type of data being shared, and policy-related concerns associated with the exchange.

Artifacts produced

Using information gathered, you will begin to define the business processes surrounding the information exchange though graphical representations of the information exchange requirements. There are three main types of business representations included in building a NIEM-based exchange.

Sequence diagram: A graphical representation of the messages sent sequentially within an information exchange. This should include both the messages sent and the systems and applications involved in the information exchange. A sample sequence diagram is shown below.

Example of a sequence diagram

Business process diagram: A textual or graphical representation of the activities involved in an exchange, similar to a work flow diagram. Business processes should be used in the development of use cases. A sample sequence diagram is shown below.

Example of a Business process diagram

Use case diagram: A graphical representation of the functionality of a particular information exchange as perceived through an external observer. Use cases are effective for identifying the actors (or individuals) in an exchange and how those actors will interact. NIEM does not prescribe any one method, however, we find Unified Modeling Language (UML) has been used successfully to develop use cases. A sample use case diagram is shown below.

Example of a Use case diagram

Training available          

  • NIEM 300: IEPD Discovery and Development is specifically designed for exchange developers and individuals looking to get a more detailed explanation of Scenario Planning.
 

Define the business rules and requirements for the information exchange.

Key considerations

The business rules and requirements help provide some clarity around the exchange, and how and what data will be represented as part of the exchange. This phase is a direct result of the work done in the Scenario Planning phase — the sequence diagrams, business process diagrams, and use cases are used as inputs​ into this phase.

Artifacts produced

Two artifacts that should be documented during this phase of the IEPD Lifecycle are business rules and business requirements. Together, they help define the exchange as well as the expectations of the exchange.

  • Business requirements: A business driver for an information exchange that is primarily an operational or functional requirement. For example, the Verification Service shall respond only to search requests issued by the client application, the Verification Information System.
  • Business rules: For NIEM, business rules are focused on the structure of data (field length, data validation, etc.). When defining an exchange, it is recommended that all business rules are captured — not just those relating to the data.

Business requirements

  • NIEM does not prescribe any single method for developing requirements. However, developing requirements that are specific, measurable, agreed-upon, realistic, and time constrained can help ensure they are effective.
  • The business requirements and rules of an IEPD will help drive important aspects of the information exchange, such as the responsibilities of the sender and receiver.

Example of a business case

A large city identified the need to create a series of exchanges that would allow parents, city-wide, to apply online for their children’s school meals program and automate the processing of the request between the Human Services Agency and the school.

This will be implemented via a web-based service that, upon submission, will automatically check the city’s Human Services agency database to ensure the applicant is from a low income family and qualifies for the school meals program. If qualified, the web-based service will then notify the respective school to add the child to the meal program.

Currently, the only means the city has to process school meal program applications is through paper-based applications at the city Human Services Agency office. Once approved, the Human Services Agency faxes approved applications to the particular school where the child attends. Overall, it is a manual process that inhibits timely delivery of citizen services.

Examples of good business requirements

Candidate message exchange packages

  • Request from Parent to Human Services Agency for meal program
  • Eligibility request from Human Services Agency web-based service to eligibility system
  • Eligibility reply from Human Services Agency to parent
  • Notification to add child to meal program from Human Services Agency to school
  • Request from school to Human Services Agency for monthly report
  • Monthly report reply from Human Services Agency to school

Performance requirement

  • The web-based service will notify parents via email whether or not their child qualifies for the school meals program ten minutes after receiving their application.
  • A school will receive notification within 24 hours of a new qualified child within their school.

Reporting requirements

  • Each school in the city shall be able to receive a monthly report of every child in their school who is currently enrolled in the school meals program.

Training available          

  • NIEM 300: IEPD Discovery and Development is specifically designed for exchange developers and individuals looking to get a more detailed explanation of Scenario Planning.

Create an Exchange Content Model to represents data objects for the information exchange. The data objects from the Exchange Content Model are then mapped to objects in NIEM.

Key considerations

The phase is important in the process of moving from requirements to actual design of the data structures to meet those requirements. The Exchange Content Model created is a primary driver of the data objects and relationships among those objects that will be used within the information exchange.

Artifacts produced

There are two artifacts associated with the Map and Model phase of building a NIEM-based exchange—Exchange Content Model and Mapping document. First, you will create an Exchange Content Model. Then, you will create a Mapping document to record how the required objects map to equivalent NIEM data objects.

Exchange Content Model: A graphical representation of the data and relationships involved in the information exchange. Exchange Content Models consist of objects, their related elements, and the associations between those objects.

Image of a NIEM Exchange Content Model. Objects are 1)Construct that represents a person, place, thing ,etc 2)Structured and able to contain instances of itself. Elements are 1)Specification that defines a property of an object 2)Defines the unique characteristics of an object. Associations are 1)Interactions between objects taht portray structure 2) Defines the relationships between data. Cardinality defines numeric relationships between objects, elements, and associations.

Exchange Content Models display the content and structure of the data being exchanged. Although no specific methodology is required, the most commonly used methodology is based on Unified Modeling Language (UML) Class Diagrams. UML Class Diagrams consist of objects, their related elements, and the associations between those objects. The Exchange Content Model does not have to explicitly use data objects from the NIEM model.

Example of an Exchange Content Model

Example of an Exchange content model

Mapping Document: Aligns elements identified in your Exchange Content Model to the NIEM model.

Example of a Mapping Document

Image showing sections of an example mapping document. There are three sections, A, B, and C. Section A Source Data Columns include (in order from left o right): Source container type, Source element, Source data type, and Source Element Definition. Section C Mapping Column includes mapping and is between Section A and B. Section B includes (in order from left to right): NIEM element, NIEM element path, NIEM type, NIEM element definition.

To create a Mapping Document, the exchange developer will map the elements and objects in the Exchange Content Model to elements in NIEM. Each data object should be mapped to an element or type in NIEM, if possible.

Reuse of NIEM data elements increases consistency across exchanges and reduces development time for data definitions. A golden rule of NIEM is that if it exists in NIEM, use it—don't recreate it. During the mapping process, existing related IEPDs should be reviewed to evaluate reuse.

However, mapping to NIEM should not be forced if it doesn't make sense. Instead, exchange developers should create “extensions” to the NIEM model. A Mapping Document can also serve as a communication tool to relate the level of reuse in NIEM to business users.

Training available          

  • NIEM 300: IEPD Discovery and Development is recommended for those interested in gaining an in-depth understanding of how to build an Exchange Content Model.
  • NIEM 302: Build and Validate an IEPD is specifically designed for exchange developers to provide an in-depth understanding of how to build a Mapping Document.

Create the XML schema documents that will define the exchange XML instances and validate for conformance.

Key considerations

The purpose of this phase is to create the XML schema documents that define the XML instances that will be exchanged in an implementation. The exchange developers will use the Exchange Content Model and Mapping document created during the previous phase as inputs to build the schema documents.

Artifacts produced

XML Schema documents: A type of XML document used to structure and constrain the XML document instances that carry the data for an information exchange. XML schema documents that are typically included in an IEPD are subsets and extensions. However, reference, constraint, and external schema documents can also be used in an IEPD. Note that subset, extension, and reference schema documents are NIEM-conformant; external and constraint schema documents are not.

  • Subset schema documents contain a specified subset of NIEM elements and types needed for an exchange. Subset schema is a required artifact of an IEPD and should be NIEM-conformant.
  • Extension schema documents define additional NIEM-conformant exchange-specific types, elements, and attributes not available within a NIEM release and its updates, but required by the exchange XML instances
  • Reference schema documents are intended to be the authoritative definitions for a NIEM namespace. This includes the reference schema documents for NIEM core and NIEM domains.
  • Constraint schema documents add restrictions to exchange XML instances that NIEM cannot necessarily control. Thus, an XML instance document defined by an IEPD that includes constraint schema documents must be valid (1) to the NIEM-conformant schema document set (generally, the subset and extensions), and (2) to the constraint schema set or sets which apply the additional restrictions. Constraint schemas are a convenient method for adding constraints on XML instances. They are similar to additional business rules on exchange instances, but their effects are not as easy to understand as formal Schematron rules, for example.
  • External schema documents are XML schema documents from other standards that do not conform to NIEM. For example, Geospatial Markup Language (GML) is an external standard that is commonly used with NIEM. NIEM provides conformant external adapter types for encapsulating the components defined by such schema documents and employing them within NIEM IEPDs. For more information, reference the NIEM Naming and Design Rules (NDR) version 3.0 for details on use of external adapter types and external schema documents—here’s a direct link to external adapter types.

XML schema documents can either be coded by hand or generated through tools. Visit the tools catalog for more information on tools that can be used to generate XML schema automatically.

NOTE: Manual design of subset schema documents from NIEM reference schema documents is difficult. A subset is a careful combination of both the requirements (what the user wants in the exchange) and dependencies (types, elements, and attributes that a correct subset needs to support the required components). A tool that has NIEM ‘baked-in’ is highly recommended for generating schema document subsets without overlooking dependencies.

Other XML documents: In addition to schema documents, there are other XML artifacts required and recommended to include within an IEPD. Here are a few:

  • A Model Package Description (MPD) catalog is an XML instance that is a required artifact of an IEPD. The MPD catalog contains basic metadata about the IEPD that describes its unique identity; artifact content; relationships to other IEPDs; author, sponsor, and contact information; and IEP conformance targets. An MPD catalog must conform to the schema document and rules defined in the MPD Specification version 3.0. For more information on the MPD Specification version 3.0 required and recommended content of an IEPD, here’s a direct link to the MPD/IEPD table of artifacts.
  • A wantlist specifies the elements and types from a NIEM release or update that will be used in the subset schema documents for an exchange. A wantlist is exported and imported by the Schema Subset Generation Tool when building a schema subset. SSGT is available in the Tools Catalog
  • A sample XML instance within an IEPD is an example of a valid XML message instance that is defined by that IEPD. An IEPD requires one or more sample XML instances to exemplify each IEP conformance target defined in its MPD catalog.
  • Documentation: An IEPD should contain sufficient documentation to enable an implementer to understand its purpose and how to implement NIEM XML exchanges in practice.

Training available          

  • NIEM 301: Build and Validate an IEPD is recommended for exchange developers.

Prepare and package all related files for the IEPD into a single, self-contained, portable archive file (i.e., a ZIP file).

Key considerations

The purpose of this phase is to complete IEPD documentation and then assemble all artifacts into a single package. At this point in the development process, all technical artifacts should be completed and ready to include within the IEPD.

Specifications

  • NIEM Naming and Design Rules (NDR) is the specification that defines schema documents, schema document sets, and instance XML conformance to NIEM.
  • NIEM Model Package Description (MPD) is the specification that defines how to build, design, and package up schema documents sets and the documentation that goes with them. The purpose of a MPD to make the schema document sets understandable so that others can pick them up, implement, and/or reuse.

Artifacts produced

  • MPD Catalog: An XML artifact that validates with the NIEM Model Package Description (MPD) catalog schema (XSD) and resides in the root directory of the MPD. This artifact must bear the file name “mpd-catalog.xml.”
  • ReadMe Artifact: The first source of documentation necessary to effectively describe the information exchange. The MPD catalog must identify this file. The ReadMe artifact should refer to, index, or hyperlink to other documentation artifacts within the IEPD.
  • Change Log: The IEPD change log records changes to previous versions of this IEPD. If this is the first version, then the change log simply records its release date. This artifact must appear in the MPD catalog.
  • Sample XML Instances: An IEPD must include sample XML instance documents that exemplify each IEP (Information Exchange Package) conformance target defined by the IEPD and listed in the MPD catalog. One sample may represent multiple IEP conformance targets if appropriate. However, each IEP conformance target defined must be covered by a sample XML instance. Sample instances provide insights into what the exchange representation would and should look like for an implementation of this IEPD.

See the MPD Specification 3.0 for details on all required and recommended artifacts in IEPDs. Refer to http://reference.niem.gov/niem/specification/model-package-description/3.0/model-package-description-3.0.html#appendix_C.

Training available          

  • NIEM 303: Assemble, Publish, and Implement an IEPD is recommended for exchange developers.

Publish the IEPD to an online repository for reuse and implement the information exchange.

Key considerations

Publish: Publishing an IEPD allows others to discover it and use it in other exchanges. This ability to reuse IEPDs is part of NIEM’s overall value proposition.

Implement: When creating an information exchange, you rarely ever use NIEM by itself. Depending on business requirements, there are other aspects of information exchange implementations that are required, including access controls, policy automation, transmission protocol, and others.

Maintain: An information exchange needs to be maintained throughout its existence. Best practices for maintaining IEPDs include:

  • Ensuring that any changes to an information exchange are correctly reflected within the IEPD.
  • Establishing a governance process to actively manage the changes identified for an IEPD.
  • Updating the IEPD to reflect any changes to the technical architecture over time.
  • Publishing a new version of the IEPD in online repositories once changes have been made.

Training available          

  • NIEM 303: Assemble, Publish, and Implement an IEPD is recommended for exchange developers.

Helpful tips and tricks

Visit our GitHub site for more information on your most commonly asked questions. This includes:

  • Browse our running list of tips and tricks that address frequently asked questions.
  • For step-by-step instructions on how to build a moderately complex IEPD, visit our Tutorials page.
  • Check out our IEPD samples that demonstrate how to incorporate various aspects of the NIEM technical framework, such as extensions, augmentations, associations, and even how to create local terminology in NIEM!   
  • Leverage our Patterns page to save development time! We created XML templates and various NIEM XML components that developers can cut and paste directly into their integrated development environment.

References and Specifications

Visit the technical specifications that outline the rules and requirements for NIEM conformance and use. They also describe key aspects of NIEM architecture, tooling and model versioning.

Security Markings

The NIEM technical architecture provides integration capabilities to leverage the Intelligence Community Information Security Markup (IC-ISM), as well as other IC security markups such as Need to Know (NTK).

Check out our ISM IEPD for an example on how to apply the IC-ISM markings.

Geospatial Capabilities

Learn how to leverage NIEM in a map-based environment, including use of Open Geospatial Consortium (OGC) industry standards.