Frequently Asked Questions

Information that is exchanged between agencies can be broken down into individual components—for example, information about people, places, material things, and events. Data components within an information exchange commonly shared and understood among all domains are identified as universal components (e.g., person, address, and organization), while components used in exchanges between multiple domains, but not universally shared, are identified
as common components (e.g., offense, sentence, and disposition). Components managed by a specific COI (e.g., appellate case decision and arrest agency) are considered domain specific.

When working with the National Information Exchange Model (NIEM), information that is exchanged is broken down into the following components:

Universal
Common, and
Domain-specific
Data components within an information exchange commonly shared and understood among all domains are identified as universal components (e.g., person, address, and organization), while components used in exchanges between multiple domains, but not universally shared, are identified as common components (e.g., offense, sentence, and disposition). Components managed by a specific COI (e.g., appellate case decision and arrest agency) are considered domain specific.

NIEM IEPD development steps overview:

Conduct Business Analysis and Requirements Review: This step defines the business requirements associated with an information exchange for which NIEM is used. It incorporates scenario-based planning, which is the
recommended methodology for elaborating the business context of events, incidents, or circumstances in which information exchange takes place.

Complete Information Exchange Mapping and Data Modeling: This uses established methodologies to map and model operational information exchanges. Moreover, it describes the process a COI follows to map its data sources to NIEM and identify IEPDs available for reuse and/or gaps between its data source and NIEM. COIs can use the NIEM repository to search and discover existing data components to decrease the time needed to construct IEPDs.

Build and Validate IEPDs: This step addresses the importance of using common documentation standards, such as IEPDs, to ensure there is consistency in the way information is captured, stored, and exchanged and that uniform methodologies exist to support the generation of the IEPDs. Once the COI validates its IEPD, it may submit the IEPD to its domain specific area (proceed to Step 5) or nominate data components for inclusion into universal or common (proceed to Step 4).

Data Harmonization and Promotion: The appropriate NIEM governance stakeholders form a team to review an IEPD submission and determine whether any of the data components should be included in universal or common. The team evaluates the submission and makes a recommendation regarding which, why, how, and when to integrate the proposed changes into NIEM.

Publish and Implement IEPDs: Once an IEPD is approved, it is stored in the NIEM repository. Other stakeholders or COIs can then search and discover published IEPDs for reuse or extend for a specific instance of the information exchange.

Garner Feedback and Enhance and Expand IEPDs: This step describes how the COIs work with the NIEM Program Management Office (PMO) to ensure existing IEPDs remain up to date and compliant with NIEM.

NIEM includes a set of operational processes and procedures, standards, documentation, tools, training, and technical assistance which support each step in the NIEM IEPD life cycle.

• Documentation includes the NIEM Concept of Operations (CONOPS), User Guide, and NIEM Naming and Design Rules (NDR).
• Standards include IEPDs and other process standards identified in supporting documentation.
• Training and Technical Assistance is facilitated by the NIEM Web site, training materials, in person instruction, executive materials, as well as a help desk.
• Tools include those used for activities such as scenario‑based planning, information exchange mapping and modeling, and IEPD generation.
• Governance and Processes include the structure to manage and maintain NIEM and the processes and procedures behind its operations.

NIEM documentation and standards include a data dictionary, data model, and IEPDs. The data dictionary is a well‑defined vocabulary of data names and structures. The data model is the body of concepts and rules that underlie the structure of the data dictionary, including data components arranged by domain, the type of data being represented (date, integer, Boolean, string, etc.), and a semantically precise, context‑rich definition of each component. Together the data dictionary and model become a database, from which XML schemas are generated. These schemas contain the data components that are reused to construct the IEPDs.

NIEM standardizes the artifacts necessary for interagency information exchange into an IEPD. NIEM makes available reusable IEPD content used in data exchanges; creates and disseminates tools to support rapid IEPD development and deployment; and provides managed processes for the creation, support, dissemination, and implementation of information exchanges. In order to support these exchanges, NIEM provides a:

• Central place that allows for the registration and discovery of IEPDs
• Means to ensure IEPDs are developed using an established, conventional method that results in machine readable, easy‑to‑understand artifacts.
• Place where IEPDs, certified by authoritative sources, can be highlighted and disseminated. 

There are a variety of commonly used standards that are currently represented in XML Schema. There must be a method for NIEM to promote and use these external standards where requirements dictate.

There are two fundamental cases:

• Case 1: NIEM IEPDs reference, import, and use components in an external standard schema or namespace that does not conform to NIEM Naming and Design Rules.
• Case 2: External schemas reference, import, and use NIEM components.

Case 1. Presents a methodology for including non-NIEM components in NIEM-conformant schemas. It enables data modeling efforts to build NIEM-conformant components from non-NIEM data objects.

Case 2. The use of NIEM in external standards will likely involve per-standard recommendations. Use of NIEM should maintain compatibility with those standards, by doing things as the external standards intend. For example, Security Assertion Markup Language (SAML) uses attribute assertions, which each have a name and a value. In such a case, NIEM conformant content should be carried as a set of values, with each name indicating a NIEM-conformant component. Specific rules and guidelines will be developed for each standard.  Overarching guidelines for using NIEM content in external standards will be developed.  Such rules will be overridden by rules for specific standards. General rules will involve (1) focusing on elements as the prime semantic construct in NIEM-conformant data models, and (2) focusing on types as the prime structural entity. These guidelines will help maintain consistency in uses of NIEM content between various architectures.

The term “schema component” is used for any object constructed by XML Schema.

Schema components are specified by the XML Schema specification. They include attribute declarations, type definitions, etc. They include attribute uses (which are distinct from attribute declarations) and use of model groups (distinct from model group definitions).  In the National Information Exchange Model (NIEM) the term “NIEM Component” is used for a schema component from a namespace that is NIEM-Conformant.

From XML Schema Part 1: Structures 2d Ed

W3C Recommendation 28 October 2004

[Definition:] Schema component is the generic term for the building blocks that comprise the abstract data model of the schema. [Definition:] An XML Schema is a set of schema components. There are 13 kinds of component in all, falling into three groups. The primary components, which may (type definitions) or must (element and attribute declarations) have names are as follows: 

• Simple type definitions

• Complex type definitions

• Attribute declarations

• Element declarations

The secondary components, which must have names, are as follows:

• Attribute group definitions

• Identity-constraint definitions

• Model group definitions

• Notation declarations

Finally, the "helper" components provide small parts of other components; they are not independent of their context:

• Annotations

• Model groups

• Particles

• Wildcards

• Attribute Uses

The term “NIEM Component” is used for a schema component from a namespace that is NIEM-conformant, which follows the rules defined by the NIEM Naming and Design Rules (NDR) for NIEM conformance. The NIEM NDR provides a profile of W3C X ML Schema, along with additional constructs to support creating a data model. In order to be NIEM-conformant, a namespace must claim conformance, and must follow specific rules about structure, XML Schema feature usage, naming, and documentation.

NIEM conformance is determined at the namespace level, based on a reference schema for a particular namespace. To determine if a namespace is NIEM-conformant, the reference schema for the namespace is tested against a set of NIEM conformance rules.

These rules include such things as:

1. The schema must claim to be NIEM conformant.

2. The schema must have a target namespace, over which the schema author has dominion.

3. Schema components must be documented.

4. Component documentation must take specific forms, including being supported with XML annotations from a NIEM-specific namespace, to support data modeling concepts.

The term "External Component" is used for a schema component from a namespace that does not follow the rules for NIEM conformance.

Examples of external, non-NIEM standards include:

· GML: Geography Markup Language. GML is a prime candidate for content that may be included in NIEM structures.

· XHTML: Extensible Hypertext Markup Language. This language would likely be used for exchanging simple structured text.

· SAML: Security Assertion Markup Language. This is a likely language into which NIEM content will be embedded. Some SAML assertions will likely need to contain content defined by NIEM.

There are numerous goals in defining and using adapter components:

1. Ensure that content may be carried as defined by external standards, without modification. It would be bad to modify external content standards to make them "fit" NIEM. Instead, we should carry external content exactly as would be expected by external tools.
2. Allow modeling efforts to define the granularity of use of external content as needed.

Different groups require different levels of resolution into external standards. For example, one group may exchange a large block representing the geography of a large urban area, while another group may only exchange a single geographic point.

Both may be using the same external standard, but will need to use different parts, with different sizes, and different semantics.

1. Ensure specific modeling efforts (e.g. NIEM core, domains, or IEPDs) are independent of a centralized process for use of external components. Developers should be able to immediately utilize standards required for their area of expertise.
2. Provide points for harmonization. NIEM-conformant components that use external standards may be integrated into the core of NIEM. By using narrowly defined components with specific semantics, common uses that meet broad requirements may be identified and pulled up into the core of NIEM.
3. Reduce coupling between NIEM schemas and external schemas. This method ensures that any given implementation uses external schemas through specific known points of access, without excessive dependence on deeply nested external components.

Use of external schemas within NIEM should not require that each must be harmonized with components in or placed directly into NIEM. XML Schema provides namespaces to maintain semantic independence or uniqueness.

There are potentially two ways to use components from an external standard within the NIEM framework:

Methods of integrating external components

Profile the standard and insert its components into a NIEM namespace (potentially within Common).

Advantages:

1. The "standard" components will become part of NIEM.
2. The "standard" components will be registered with other NIEM components.
3. The "standard" components will have precise semantics (because they ARE NIEM components).

Disadvantages: 

1. Anytime the standards change, then NIEM must potentially be changed.
2. The "standard" components must be factored to conform to the NIEM NDR.
3. The "standard" components may need to be harmonized with the NIEM components they potentially duplicate in whole or part (from a semantic perspective).
4. The "standard" components may not be used in the same structural representation as the standard intended.
5. Interoperability may require translations back to standard structures. (Tools expecting standard geospatial component structures may not recognize or work with those components if they have been re-structured per the NIEM NDR.).
6. EACH standard that NIEM incorporates in this manner will result in the preceding disadvantages. Thus, insertion will require a lot of unnecessary extra work.

Provide a mechanism to reference and import the standard schemas/namespaces and use the components they contain within IEPDs constructed from NIEM components.

Advantages:

1. Standards components are used within IEPDs in the same structure they were intended without the need to translate -- a potential boost to interoperability.
2. Tools designed to recognize (parse) standard components from other namespaces will recognize these components.
3. No other refactoring, integration, harmonization, or maintenance of these standards is required (even if the standards change).
4. Components in preferred standards can still be registered with and discovered in a repository of NIEM components (requires storage of metadata about the standards).
5. Subset schemas of these standards can be maintained and stored locally as required for use within IEPDs, a registry, etc.

Disadvantages:

1. A NIEM structure (an adapter or container construct) will be required to encapsulate non-conforming components or schemas within an IEPD schema and to identify and preserve the semantics of those components.

A namespace can be labeled as NIEM-conformant. Any namespace that is not NIEM conformant is referred to as an external namespace. A namespace is NIEM-conformant if its reference schema follows NIEM conformance rules. A schema component must be in a NIEM-conformant namespace to be considered NIEM conformant. For any component of a schema to be conformant, the entire schema must be conformant.  A NIEM conformant schema must claim to be conformant. This occurs when the document element, the schema element, has a child annotation with a child appinfo with a child element i:conformant with the character child "true". In other words, the XPath

"/xsd:schema/xsd:annotation/xsd:appinfo/i:conformant" has the value "true".

<xsd:schema ...>

Non-Schema Namespaces

An external namespace may be defined by a non-schema mechanism, such as DTD. In such a case, a placeholder schema would be created to represent the exact constructs referred to from the NIEM-conformant schema. A placeholder schema would not represent the deeper XML content of such namespaces. Instead, it would define placeholder elements and additional required constructs that are further defined by the non-XML Schema standard.

For example, XHTML 1.0, which has no normative XML Schema definition, may be considered an external namespace. XHTML defines a namespace, and numerous elements within that namespace.  Were a NIEM-conformant schema specification to use the element "xhtml:ul" (an unordered list), it would use a reference. In order for schema validation to proceed normally, a schema would have to define that element. However, there is no such schema for Non-XML Schema specifications. The schema that is created to fulfill that role is the placeholder schema. Placeholder schemas should only represent the necessary components directly referred to from NIEM-conformant schemas.

Importing of External Namespaces

When NIEM namespaces are imported, the import statements are documented with a description of how the namespace is relevant to the namespace being defined. External (non-NIEM) namespaces should be documented with additional information, including:

1. An indication that the imported namespace is not NIEM-conformant.

2. The URI for a source of the reference schema for the namespace

3. Version information

4. Information about the body responsible for the standard, including:

      a. Contact information

      b. URI

Additional metadata will be defined, as the NIEM NDR is further defined. For the time being, the metadata should be included as documentation elements.

A NIEM external adapter type is a complex type that has the following qualities:

1. It is a special form of NIEM-conformant type. It may be used as the type of any NIEM-conformant element.
2. An adapter type should compose a single semantic entity. That is, the subparts of the type should appear together because they form the definition for some concept, not simply as a way of wrapping a block of external content.
3. An adapter type should be documented, as should any NIEM-conformant type.
4. It contains content from an external namespace, including:
a. Attributes from an external namespace
b. Attribute groups from an external namespace
c. A single XSD sequence containing zero or more of:
i. Elements from an external namespace
ii. Model Groups from an external namespace. These are named groups of elements defined schemas.
iii. External container elements, from a NIEM-conformant namespace. These are used when an external type must be used.

5. It must extend the "ComplexObjectType" from the NIEM structures namespace
6. It may not directly reference any other complex or simple types. Such types should be accessed via an external container element.
7. It may not directly reference other NIEM content. Apart from the "ComplexObjectType", all content of an external adapter type should be external.
8. The content it references may be from more than one external namespace.
9. Each referenced external component must be individually documented, describing the meaning of the external component

Additional annotations may be introduced as the NDR is developed.

An example of the simple case shows an adapter type directly referring to an external element:

<complexType name="PointType">

<annotation>

<documentation>

SUMMARY OF TYPE GOES HERE

</documentation>

</annotation>

<complexContent>

<extension base="s:ComplexObjectType">

<sequence>

<element ref="gml:Point">

<annotation>

<documentation>

DESCRIPTION OF EXTERNAL ELEMENT GOES HERE

</documentation>

</annotation>

</element>

</sequence>

</extension>

</complexContent>

</complexType>

An alternate case occurs when types from an external standard need to be used, instead of elements.

The term “External” is used as a suffix to element names in the NIEM conformant namespaces. An element with a name that ends in “External” is referred to as an external container element. Such an element is defined when a NIEM standard needs to reference XML Schema types from an external namespace.

If an external namespace defines elements that are appropriate for use, the elements should be referenced by external adapter types, and external container elements are unnecessary. External container elements are needed to create container elements for types from external namespaces.

An external container element has the following characteristics:

Its name ends in "External".
It is not a NIEM-conformant element.
It may only be referred to by external adapter types. It is an error for any other component to refer to an external container element.
The type of the element is a simple or complex type from an external namespace. The element definition may not reference any other external components.
An external container element may not specify a substitution group.

External container elements may not be referenced by standard conformant components.

They may only be referenced by external adapter types.

Here is an example definition of an external container element:

<element name="PointExternal" type="gml:PointType">

<annotation>

<documentation>

DESCRIPTION OF EXTERNAL TYPE GOES HERE

</documentation>

</annotation>

</element>

Note that the definition is very simple: it provides a container for an external type, and is clearly labeled as non-NIEM content by the suffix "External".

The external container element may be used by an adapter type, as the following example shows:

<complexType name="PointType">

<annotation>

<documentation>

SUMMARY OF TYPE GOES HERE

</documentation>

</annotation>

<complexContent>

<extension base="s:ComplexObjectType">

<sequence>

<element ref="this:PointExternal"/>

</sequence>

</extension>

</complexContent>

</complexType>

External container elements are not NIEM-conformant data model components. Instead, they create container for external types. They are clearly identified external by their names (suffixed with "External"). External elements (that come from non-NIEM namespaces) are clearly identified as external by their namespaces.

The syntax for an instance of an association is simple. Take, for example, the marriage of Adam and Barbara Smith:

<MarriageAssociation>
<SpouseRef s:ref="A"/>
<SpouseRef s:ref="B"/>
<MarriageDate>1937-05-12</MarriageDate>
<DivorceDate>1973-06-02</DivorceDate>
</MarriageAssociation>

Interpreting the above XML fragment is straightforward:

There is an association that we call a marriage. You can tell it is an association, and not a thing, because it is named “something association”.
This marriage association has two spouses, a marriage date, and a divorce date.
One spouse is referenced as the object with the identifier A. The other spouse is identified by the ID B.
These objects are specified elsewhere in the same XML instance: Object A is specified as follows:

<Person s:id="A">
<PersonName>
<PersonFullName>Adam Smith</PersonFullName>
</PersonName>
</Person>

Object B is specified as follows:

<Person s:id="B">
<PersonName>
<PersonFullName>Barbara Smith</PersonFullName>
</PersonName>
</Person>

Other elements in the association specify more information about the association:

<MarriageDate>1937-05-12</MarriageDate>
<DivorceDate>1973-06-02</DivorceDate>

The marriage date and divorce date are specific to the relationship between the two spouses, and so is a natural fit for an element of the association.

The definition of an association is composed of several parts:

1. An element that identifies the specific semantics of the association.

For each semantically distinct association, we define an element. Each element will have annotations indicating the specific meaning of the association. Such documentation is not shown in this document, but follows the guidelines established for GJXDM 3.0. The syntax is standard XML Schema. For example, here is the definition for a parent-child element:

<xs:element
name="ParentChildAssociation"
type="ParentChildAssociationType"/>

We may wish to define a more-specific type of parent-child association. For example, an adoptive parent-child association:

<xs:element
name="AdoptiveParentChildAssociation"
type="ParentChildAssociationType"/>

If we wanted to make the type specific to an adoptive parent-child situation, then we define a new type, instead of reusing the general parent-child type.

2. A type for the association. The type may be have precise semantics, or may be a more generally defined type.

The definition of types for associations is done as needed, depending on the content of the types. We do not, as a rule, define a new type for each use or semantic definition of an association. Instead, we define them as necessary, to accommodate the content required. Here is an example definition for a type for the parent-child association:

<xs:complexType name="ParentChildAssociationType">
<xs:complexContent>
<xs:extension base="u:AssociationType">
<xs:sequence>
<xs:element ref="this:ParentRef" minOccurs="0" maxOccurs="unbounded"/>
<xs:element ref="this:ChildRef" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>

The type definition has several parts:

The name of the type is “something AssociationType”. This makes associations between objects distinct from other types of object definitions.

The type is derived from another association type. This allows definition of type hierarchies for associations, and the definition of characteristics that are shared across multiple association types. The content of the association is a sequence of elements. The content of the association could be entirely related objects. The association could also contain characteristics of the associations, such as dates, names, identifiers, etc.