Technical Architecture

Photo of the NIEM Abstraction Layers. The NIEM Domain Abstraction Layer is used to provide mission-based/domain specific layer of data objects that specialize base objects from the NIEM Core and structures namespaces. The NIEM Core Abstraction Layer contains commonly used definitions for generic objects like person, organization, and activity that are used across domains. External Standards Abstraction Layer contains definitions for objects used in standards defined external to NIEM. Support Abstraction Layer provies the underlying standardized structure for NIEM. Each of the data objects in the other abstraction layers reuse the basic data objects in this layer.

The rules and guidance that make up NIEM’s technical architecture are designed to encourage and facilitate NIEM use. They are defined in detail by several key documents, including the Model Package Description (MPD) and Naming and Design Rules (NDR).

Introduction to NIEM Architectural Concepts

Namespaces are used to avoid element name conflicts. Therefore, each reference schema in the NIEM model is defined individually by a namespace. Reuse of any component is always by reference to both its namespace and its name. All NIEM component names have global scope.

The rules for the use of namespaces must also be followed for exchange-specific schema documents. It’s critical to evaluate the namespace of a component when browsing the model or building exchanges, as components have different meanings and attributes across the various NIEM domains.

The graphic below provides an overview of naming conventions for data objects in NIEM. Naming conventions start with a namespace prefix. In this example, “nc” stands for the namespace “NIEM core.” Qualifier terms can be inserted into Objects, Property, and Representation Terms to provide additional context.

This graphic provides an overview of naming conventions for data objects in NIEM. Data object names within NIEM always start with a namespace prefix and a colon, such as "nc" (which stands for NIEM core). Object class terms must consist of a category such as an activity or entity, such as arrest or vehicle, respectively (or disposition). Property terms need to describe or represent the central meaning of the data object.  Finally, representation terms indicate the format of the data, such as code, quantity, date, or text.

Here are all the NIEM Namespaces and their associated prefixes.

This table displays all the NIEM namespaces and their associated prefixes. The prefixes and namespace names are as follows: the prefix "it." is international trade; the prefix "em" is emergency management; the prefix "ip" is infrastructure protection; the prefix "cbrn" is chem/bio/rad/nuc; the prefix "scr" is screening; the prefix "intel." is intelligence; the prefix "mo" is milops; the prefix "structures" is structures; the prefix "appinfo" is appinfo; the prefix "nc" is NIEM core; the prefix "niem-xsd" is proxy; the prefix "j" is justice; the prefix "im" is immigration; the prefix "biom" is biometrics; the prefix "m" is maritime".

Read the NDR for more details about the use of namespaces and namespace prefixes.

Code lists are most often used to limit possible values for an element. NIEM conformant code lists can be generated from an Excel spreadsheet by using the NIEM Code List Schema Generator Tool. If code lists are reusable by many exchanges, they have the potential to be integrated into NIEM Core or a NIEM domain. An example of a code list in NIEM core is “nc:LocationCountryFIPS10-4Code,” which is used in the example below. The possible values for that particular element are country codes.

This graphic shows an example of a code list in NIEM's core, "nc:LocationCountryFIPS10-4Code." The possible values for this particular element  are country codes. The possible values for this data element, nc:LocationCounty, include: enumeration = BR, documentation = Brazil; enumeration = GM, documentation = Germany; enumeration = US, documentation = United States.

Publication of code lists: Each NIEM code list within the model has a governing body responsible for its content and has authority over its timeline for updates and code list publication. Code lists that are unique to an individual exchange, and not available in core or domain schema documents, are managed by that particular exchange developer.

Code list substitutions: The NIEM model defines an abstract element for each distinct concept that coded elements represent. This allows a code list to be updated independently of the NIEM core. A coded element (whose values are enumerated) is substituted for the abstract element that represents the concept (e.g., country).

Below is an example of a code list.

This graphic shows an example of a code list in XML schema format. The graphic highlights a simple type declared to contain code list, code value for code list entry, description of code list value, and simple type for code list (base type for complex time).

Association types link together related objects in an exchange. The use of association types prevents the need to redefine objects. Association types are implemented using references. Referencing allows the use of structures:ref attribute, which provides a link to an object with a matching structures:id attribute.

In the example below, the association type “DriverLicenseAssociation” allows both the “Person” and “DriverLicense” to be linked in the exchange through the use of structures:ref attribute.

This graphic shows an example of an association type, "DriverLicenseAssociation", allowing both "Person" (structures:id) and "DriverLicense" (structures:id) to be linked in an exchange through the use of the "structures:ref" attribute. The graphic shows a box titled "DriverLicenseAssociation" in the center with Person and DriverLicense down below. From the center, an arrow from left of the box  points to "Person, structures:id" and an arrow from the right points to "DriverLicense, structures:id".

The diagram below displays the same example in schema and instance format.

This graphic shows an example of an association type, "DriverLicenseAssociation" in XML schema format. It highlights an extension of nc:AssociationType and elements used as references to globally defined objects.This graphic shows an example of an association type, "DriverLicenseAssociation" in XML instance format. It highlights an ID for unique person object, an ID for unique driver license object, and reference to IDs for driver license and person objects.

The NDR outlines association types. Access the Association section of the NDR.

Every NIEM type that is built from structures:ObjectType or structures:AssociationType contains an "augmentation point" element. An "augmentation point" is an abstract element that acts as a substitution group head, for which additional elements (or containers of elements) of any type may be substituted. These additional elements are “augmentations,” which represent additional characteristics and relationships of the original type.

In summary, augmentation points increase the potential for reuse and adaptation across domains without forcing the creation of many specialized types. The example below displays how the augmentation element “nc:VehicleAugmentationPoint” can be used to create a domain-specific vehicle type.

This graphic shows how the augmentation element “nc:VehicleAugmentationPoint” can be used to create a domain-specific vehicle type in XML schema format. It highlights the augmentation element included for "domain specific" vehicle information.

This graphic shows how the augmentation element “nc:VehicleAugmentationPoint” can be used to create a domain-specific vehicle type in XML instance format. It highlights the NIEM core vehicle element used.

To learn more about Augmentations, visit the NDR.

Substitution groups are used in augmentation. They consist of elements from multiple domains and together create a new type.

NIEM uses substitution groups to allow a single concept to be represented by multiple elements of different types. Within NIEM, substitution groups allow flexibility in the allowed data types for an element. A user would substitute one of the following elements for nc:DateRepresentation:

  • nc:Date (a full date)
  • nc:DateTime (a full date and time)
  • nc:Year (a year)
  • nc:YearMonth (a year and month)

The example below demonstrates how to use substitution groups in XML schema.

This graphic shows how to use substitution groups in XML schema, in the XML schema format.  The graphic highlights the abstract head element that must be substituted for within the XML instance.

This graphic shows how to use substitution groups in XML schema, in XML instance format.  The graphic highlights elements allowed to substitute for nc:PersonSex.

To learn more about substitution groups, visit the NDR.

Metadata is data that qualifies other data. An nc:Metadata element is used in NIEM to add additional information about data. Metadata types do this by adding descriptive information about data within an XML instance. They can also be used for searching or categorizing data included within an exchange. Metadata can be implemented by reusing existing metadata types within NIEM or creating a new metadata type.

The example below shows the use of Metadata types in schema.

This graphic shows the use of Metadata types in schema, in XML schema format. This graphic highlights where basetype is s:Metadata Type and elements reused from NIEM core.

This graphic shows the use of Metadata types in schema, in XML instance format. This graphic highlights a unique metadata object and a reference to unique metadata object.

Read the NDR for more information about metadata.

XML Artifacts help define the parts of the model needed in a particular exchange.

NIEM is a relatively large model. When designing an information exchange, it’s not necessary to use all of NIEM. A schema subset based on a given NIEM release is more efficient. A NIEM schema subset contains only those types, elements, and attributes required for a particular information exchange.

Below is a subset schema document that outlines the exchange requirements for the element “VehicleType.”

This graphic shows as subset schema document that outlines the exchange requirements for the element “VehicleType.” It shows the definition for VehicleType and Globally defined vehicle elements.

A wantlist is an XML document that identifies the NIEM types, elements, and attributes that a developer desires to use within the schema document subset for an information exchange. A NIEM-aware tool (such as the Schema Subset Generation Tool—SSGT) can import a wantlist and generate a correct NIEM schema document subset that includes additional NIEM components that the subset depends on.

A NIEM-aware tool can also generate and export a wantlist from a correct NIEM schema document subset.

This graphic shows that a NIEM-aware tool can generate and export a wantlist from a correct NIEM schema document subset. The graphic shows NIEM types, elements and attributes generating a wantlist.

The example below shows a sample wantlist.

This graphic shows a sample wantlist.

A wantlist does not necessarily identify all the components required for a complete subset. It only identifies the components requested by the developer by name. Those items may depend on other components that will be needed and present in the generated subset but that were not identified in the wantlist. A NIEM-aware tool can add the dependencies to the subset.

An extension schema document extends existing NIEM data components and it can create new NIEM data components. NIEM is a diverse data model, but it may not describe everything needed for an information exchange. An existing NIEM component should only be employed in a context that fits its semantics. Consider reusing, extending, or augmenting a NIEM component with the correct semantics first; but if such a component does not exist for a given situation or context, then create a component per the NIEM NDR. An extension schema document must include a unique target namespace declaration, as well as references to NIEM, W3C, and other extension schema namespaces required. When possible, extension schema documents should be designed for reuse in other information exchange definitions.

Extensions can be candidates for future inclusion into the NIEM model. Learn more about the NIEM harmonization process on the Model Overview page.

The example below shows an example of an extension.

This graphic shows an example of an extension. The graphic highlights code that inherits all properties of nc:VehicleType and also highlights new elements defined in HybridVehicleType.

Read the NDR for more information about extensions. 

Now that you understand some of the architecture of the model, learn how to build an exchange.