From 82d085c7d2bc464912157e0e8cae71d27c983a5b Mon Sep 17 00:00:00 2001 From: Tom Carlson Date: Thu, 4 Feb 2021 16:35:10 -0500 Subject: [PATCH] Regenerated specs with current date in-document --- docs/draft/niem-iepd-spec.html | 2 +- docs/draft/niem-iepd-spec.txt | 2 +- publish/niem-iepd-spec.html | 2 +- publish/niem-iepd-spec.txt | 2 +- src/niem-iepd-spec.xml.m4 | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/draft/niem-iepd-spec.html b/docs/draft/niem-iepd-spec.html index 25d23ea..8df940e 100644 --- a/docs/draft/niem-iepd-spec.html +++ b/docs/draft/niem-iepd-spec.html @@ -1,7 +1,7 @@ National Information Exchange Model Information Exchange Package - Documentation Specification, 5.0beta1
National Information Exchange Model — Information Exchange Package Documentation Specification
Version 5.0beta1
December 17, 2020
NIEM Technical Architecture Committee (NTAC)
Abstract

This document specifies normative rules and non-normative guidance for building a National Information Exchange Model (NIEM) information exchange package documentation (IEPD).

Status

This document deprecates the Model Package Description (MPD) construct as of NIEM 5.0.

This specification represents the work of the NIEM Technical Architecture Committee (NTAC), the NIEM Business Architecture Committee (NBAC), and their predecessors. It is a product of the NIEM Management Office (NMO).

Email comments on this specification to information@niem.gov or submit them via the GitHub issue tracker.

Contents
1. Introduction

This specification defines rules and practices for constructing and packaging a National Information Exchange Model (NIEM)information exchange package documentation (IEPD). To the NIEM program, the IEPD is considered the point of interoperability.

This specification assumes familiarity with NIEM, its basic concepts, architecture, processes, design rules, and general conformance rules. NIEM training and reference materials are located on the [NIEM TechHub]. In addition to those materials, readers of this specification may wish to be familiar with the current versions of the following:

This specification uses and is a peer to the [NIEM Naming and Design Rules].

1.1. Background

An IEPD is a normative specification for XML data components in the format of the World Wide Web Consortium (W3C) XML Schema Definition Language [W3C XML Schema Part 2 Datatypes], [W3C XML Schema Part 1 Structures]. IEPD schema documents define implementable NIEM exchange instance XML documents in W3C Extensible Markup Language (XML) [W3C XML 1.0].

An IEPD is ready to publish and use when it conforms to NIEM specifications, and has been properly packaged with the schemas, documentation, and supplemental files needed to implement or reuse it. IEPD content design, development, and assembly may be difficult and time-consuming, especially if done manually. Developers will often prefer to build and modify an IEPD with the help of software tools, which can significantly reduce the complexity of designing, constructing, changing, and managing IEPDs. In order to reduce ambiguity and to facilitate interoperable and effective tool support, this baseline specification imposes some degree of consistency on the terminology, syntax, semantics, and composition of IEPDs.

1.2. Purpose

This document is a normative specification for NIEM information exchange package documentation (IEPD). The rules and guidance herein are designed to encourage and facilitate NIEM use and tools by balancing consistency, simplicity, and flexibility. Consistency and simplicity make IEPDs easy to design correctly, build rapidly, and find easily (for reuse or adaptation). Consistency also facilitates tool support. Flexibility enables more latitude to design and tailor IEPDs for complex data exchange requirements. As such, this document does not necessarily prescribe mandates or rules for all possible situations or organizational needs. If an organization desires to impose additional requirements or constraints on its IEPDs beyond those specified in this document (for example, mandate that an IEPD contain a normative set of business requirements or a domain model), then it is free to do so, as long as no conflicts exist with this specification or the [NIEM Naming and Design Rules].

This document defines terminology; identifies required and optional (but common) artifacts; defines metadata; specifies normative constraints, schemes, syntax, and processes as rules; provides non-normative guidance; and as needed, refers to other related NIEM specifications for more detail.

1.3. Scope

This specification applies to all NIEM information exchange package documentation (IEPD), and in particular it focuses on the normative rules for IEPDs.

NIEM is a data layer for an information architecture. Files in an IEPD generally define XML Schema types and declare XML elements and attributes to use in payloads for information exchanges. While an IEPD may also contain files from layers beyond the data layer, this specification is not intended to define details of other architectural layers. Such files are generally present only to provide additional context, understanding, or assistance for implementing the exchange of payloads.

This specification defines several incremental stages of conformance to support iterative IEPD development, with conformance testing possible at each step instead of delayed to the end. Tool vendors should be able to build, adapt, and integrate software tools to assist in IEPD development and assembly, from raw parts to finished product.

This specification provides a standard version numbering scheme Section 5.2.3, IEPD Version Numbering Scheme (c:iepdVersionID), below. However, it does not provide guidance for managing or processing IEPD versions or their associated information exchange packages (IEPs). Creation and management of IEPDs is the responsibility of stakeholders and developers. As such, IEPDs have their own versioning processes, and are managed independently of the NIEM core and domains. The NIEM Management Office defines IEPD conformance, but IEPD development and management fall outside its scope. Nonetheless, the NIEM Management Office has developed guidance (through the NTAC) for managing IEPDs, versioning IEPDs, and processing their associated IEPs. This reference material can be found at https://niem.github.io/reference/artifacts/messages/iepd/.

An IEPD defines one or more data exchanges, each occurring in the form of an IEP. This specification supports a variety of data exchange use cases, in which the IEP may be:

  • An XML document with a NIEM-defined XML document element.
  • An XML document with a NIEM-defined payload element wrapped inside a non-NIEM envelope element (for example, SOAP, [Logical Entity Exchange Specifications] (LEXS), Trusted Data Format (TDF), or an OGC Web Service document element).
  • Multiple NIEM-defined payloads packaged together in a single document.

IEPD developers are not required to revise IEPDs that existed before this specification becomes effective. However, they are always encouraged to consider revising an IEPD to meet this specification, especially when making other significant changes.

1.4. Audience

The following groups should review and be familiar with this specification:

  • NIEM IEPD developers, reviewers, individuals or groups responsible for approving IEPDs, and implementers.
  • NIEM-aware tool developers.
2. Basic Concepts and Terminology

The section defines and discusses baseline terms and concepts that will be used throughout this document. Presentation in this section is sequenced for understanding. Each subsection builds upon previous ones.

2.1. IETF Best Current Practice 14 terminology

The key words MUST, MUST NOT, SHALL, SHALL NOT, SHOULD, SHOULD NOT, MAY, RECOMMENDED, REQUIRED, and OPTIONAL in this document are to be interpreted as described in [BCP 14][RFC 2119][RFC 8174].

2.2. Character Case Sensitivity

This specification imposes many constraints on the syntax for identifiers, names, labels, strings, etc. In all cases, unless otherwise explicitly noted, syntax is case sensitive. In particular, XML files in appendices that define particular artifacts, transformations, and examples are case sensitive.

Also, note that as a general principle, lower case characters are used whenever such will not conflict with the [NIEM Naming and Design Rules].

2.3. Artifacts

IEPDs are generally composed of files and file sets grouped for a particular purpose. Each file is referred to as an artifact, and each logical set of such files is called an artifact set.

[Definition: artifact]

A single file with a defined purpose.

[Definition: artifact set]

A collection of artifacts logically grouped for a defined purpose.

An IEPD is itself an artifact set, the purpose for which is to define and document the intended use of the IEPD. While the key IEPD artifacts are its XML schema document artifacts, there are also other kinds of IEPD artifacts. These may include (but are not limited to) HTML, XSLT, text, or graphic files used for human-readable documentation. An IEPD may also have artifacts intended to help assist in or accelerate the use and implementation of the IEPD. For example, these may be XML, UML, or binary files that are inputs to or outputs from software tools used to build, generate, or edit the IEPD or its schema document artifacts. Appendix C, Common IEPD Artifacts, below, contains a listing of mandatory and common optional artifacts for IEPDs. Common types of artifacts are described in more detail in subsequent sections. Section 7.1, Artifact Sets, below, discusses the different methods for grouping IEPD artifacts into sets.

2.4. Schema Document and Namespace Correspondence in NIEM

To simplify automatic schema processing and reduce the potential for confusion and error, [NIEM Naming and Design Rules] principles state that each NIEM-conformant namespace SHOULD be defined by exactly one reference or extension schema document. To support this concept, the [NIEM Naming and Design Rules] disallows the use of xs:include, and mandates the use of the xs:schema/@targetNamespace attribute in NIEM-conformant schema documents.

So, (1) each NIEM namespace is defined by a single NIEM-conformant schema document, and (2) each NIEM-conformant schema document declares a target namespace. NIEM does not permit schema documents without target namespaces, unless they are from sources outside of NIEM (e.g., an external schema document).

2.5. Namespaces Used in this Specification

The following namespaces are referenced and used in this specification:

Figure 2-1: Namespaces Used
c           http://reference.niem.gov/niem/resource/iepd/catalog/5.0/
+		Documentation Specification, 5.0beta1
National Information Exchange Model — Information Exchange Package Documentation Specification
Version 5.0beta1
February 4, 2021
NIEM Technical Architecture Committee (NTAC)
Abstract
This document specifies normative rules and non-normative guidance for building a National Information Exchange Model (NIEM) information exchange package documentation (IEPD).
Status
This document deprecates the Model Package Description (MPD) construct as of NIEM 5.0.
This specification represents the work of the NIEM Technical Architecture Committee (NTAC), the NIEM Business Architecture Committee (NBAC), and their predecessors. It is a product of the NIEM Management Office (NMO).
Email comments on this specification to information@niem.gov or submit them via the GitHub issue tracker.
Contents
1. Introduction
This specification defines rules and practices for constructing and packaging a National Information Exchange Model (NIEM)information exchange package documentation (IEPD). To the NIEM program, the IEPD is considered the point of interoperability.
This specification assumes familiarity with NIEM, its basic concepts, architecture, processes, design rules, and general conformance rules. NIEM training and reference materials are located on the [NIEM TechHub]. In addition to those materials, readers of this specification may wish to be familiar with the current versions of the following:
This specification uses and is a peer to the [NIEM Naming and Design Rules].
1.1. Background
An IEPD is a normative specification for XML data components in the format of the World Wide Web Consortium (W3C) XML Schema Definition Language [W3C XML Schema Part 2 Datatypes], [W3C XML Schema Part 1 Structures]. IEPD schema documents define implementable NIEM exchange instance XML documents in W3C Extensible Markup Language (XML) [W3C XML 1.0].
An IEPD is ready to publish and use when it conforms to NIEM specifications, and has been properly packaged with the schemas, documentation, and supplemental files needed to implement or reuse it. IEPD content design, development, and assembly may be difficult and time-consuming, especially if done manually. Developers will often prefer to build and modify an IEPD with the help of software tools, which can significantly reduce the complexity of designing, constructing, changing, and managing IEPDs. In order to reduce ambiguity and to facilitate interoperable and effective tool support, this baseline specification imposes some degree of consistency on the terminology, syntax, semantics, and composition of IEPDs.
1.2. Purpose
This document is a normative specification for NIEM information exchange package documentation (IEPD). The rules and guidance herein are designed to encourage and facilitate NIEM use and tools by balancing consistency, simplicity, and flexibility. Consistency and simplicity make IEPDs easy to design correctly, build rapidly, and find easily (for reuse or adaptation). Consistency also facilitates tool support. Flexibility enables more latitude to design and tailor IEPDs for complex data exchange requirements. As such, this document does not necessarily prescribe mandates or rules for all possible situations or organizational needs. If an organization desires to impose additional requirements or constraints on its IEPDs beyond those specified in this document (for example, mandate that an IEPD contain a normative set of business requirements or a domain model), then it is free to do so, as long as no conflicts exist with this specification or the [NIEM Naming and Design Rules].
This document defines terminology; identifies required and optional (but common) artifacts; defines metadata; specifies normative constraints, schemes, syntax, and processes as rules; provides non-normative guidance; and as needed, refers to other related NIEM specifications for more detail.
1.3. Scope
This specification applies to all NIEM information exchange package documentation (IEPD), and in particular it focuses on the normative rules for IEPDs.
NIEM is a data layer for an information architecture. Files in an IEPD generally define XML Schema types and declare XML elements and attributes to use in payloads for information exchanges. While an IEPD may also contain files from layers beyond the data layer, this specification is not intended to define details of other architectural layers. Such files are generally present only to provide additional context, understanding, or assistance for implementing the exchange of payloads.
This specification defines several incremental stages of conformance to support iterative IEPD development, with conformance testing possible at each step instead of delayed to the end. Tool vendors should be able to build, adapt, and integrate software tools to assist in IEPD development and assembly, from raw parts to finished product.
This specification provides a standard version numbering scheme Section 5.2.3, IEPD Version Numbering Scheme (c:iepdVersionID), below. However, it does not provide guidance for managing or processing IEPD versions or their associated information exchange packages (IEPs). Creation and management of IEPDs is the responsibility of stakeholders and developers. As such, IEPDs have their own versioning processes, and are managed independently of the NIEM core and domains. The NIEM Management Office defines IEPD conformance, but IEPD development and management fall outside its scope. Nonetheless, the NIEM Management Office has developed guidance (through the NTAC) for managing IEPDs, versioning IEPDs, and processing their associated IEPs. This reference material can be found at https://niem.github.io/reference/artifacts/messages/iepd/.
An IEPD defines one or more data exchanges, each occurring in the form of an IEP. This specification supports a variety of data exchange use cases, in which the IEP may be:
  • An XML document with a NIEM-defined XML document element.
  • An XML document with a NIEM-defined payload element wrapped inside a non-NIEM envelope element (for example, SOAP, [Logical Entity Exchange Specifications] (LEXS), Trusted Data Format (TDF), or an OGC Web Service document element).
  • Multiple NIEM-defined payloads packaged together in a single document.
IEPD developers are not required to revise IEPDs that existed before this specification becomes effective. However, they are always encouraged to consider revising an IEPD to meet this specification, especially when making other significant changes.
1.4. Audience
The following groups should review and be familiar with this specification:
  • NIEM IEPD developers, reviewers, individuals or groups responsible for approving IEPDs, and implementers.
  • NIEM-aware tool developers.
2. Basic Concepts and Terminology
The section defines and discusses baseline terms and concepts that will be used throughout this document. Presentation in this section is sequenced for understanding. Each subsection builds upon previous ones.
2.1. IETF Best Current Practice 14 terminology
The key words MUST, MUST NOT, SHALL, SHALL NOT, SHOULD, SHOULD NOT, MAY, RECOMMENDED, REQUIRED, and OPTIONAL in this document are to be interpreted as described in [BCP 14][RFC 2119][RFC 8174].
2.2. Character Case Sensitivity
This specification imposes many constraints on the syntax for identifiers, names, labels, strings, etc. In all cases, unless otherwise explicitly noted, syntax is case sensitive. In particular, XML files in appendices that define particular artifacts, transformations, and examples are case sensitive.
Also, note that as a general principle, lower case characters are used whenever such will not conflict with the [NIEM Naming and Design Rules].
2.3. Artifacts
IEPDs are generally composed of files and file sets grouped for a particular purpose. Each file is referred to as an artifact, and each logical set of such files is called an artifact set.
[Definition: artifact]
A single file with a defined purpose.
[Definition: artifact set]
A collection of artifacts logically grouped for a defined purpose.
An IEPD is itself an artifact set, the purpose for which is to define and document the intended use of the IEPD. While the key IEPD artifacts are its XML schema document artifacts, there are also other kinds of IEPD artifacts. These may include (but are not limited to) HTML, XSLT, text, or graphic files used for human-readable documentation. An IEPD may also have artifacts intended to help assist in or accelerate the use and implementation of the IEPD. For example, these may be XML, UML, or binary files that are inputs to or outputs from software tools used to build, generate, or edit the IEPD or its schema document artifacts. Appendix C, Common IEPD Artifacts, below, contains a listing of mandatory and common optional artifacts for IEPDs. Common types of artifacts are described in more detail in subsequent sections. Section 7.1, Artifact Sets, below, discusses the different methods for grouping IEPD artifacts into sets.
2.4. Schema Document and Namespace Correspondence in NIEM
To simplify automatic schema processing and reduce the potential for confusion and error, [NIEM Naming and Design Rules] principles state that each NIEM-conformant namespace SHOULD be defined by exactly one reference or extension schema document. To support this concept, the [NIEM Naming and Design Rules] disallows the use of xs:include, and mandates the use of the xs:schema/@targetNamespace attribute in NIEM-conformant schema documents.
So, (1) each NIEM namespace is defined by a single NIEM-conformant schema document, and (2) each NIEM-conformant schema document declares a target namespace. NIEM does not permit schema documents without target namespaces, unless they are from sources outside of NIEM (e.g., an external schema document).
2.5. Namespaces Used in this Specification
The following namespaces are referenced and used in this specification:
Figure 2-1: Namespaces Used
c           http://reference.niem.gov/niem/resource/iepd/catalog/5.0/
 er	    urn:oasis:names:tc:entity:xmlns:xml:catalog
 nc	    http://release.niem.gov/niem/niem-core/5.0/
 structures  http://release.niem.gov/niem/structures/5.0/
diff --git a/docs/draft/niem-iepd-spec.txt b/docs/draft/niem-iepd-spec.txt
index 7b39f1e..9c2f41a 100644
--- a/docs/draft/niem-iepd-spec.txt
+++ b/docs/draft/niem-iepd-spec.txt
@@ -2,7 +2,7 @@ National Information Exchange Model -- Information Exchange Package Documentatio
 
 Version 5.0beta1
 
-December 17, 2020
+February 4, 2021
 
 NIEM Technical Architecture Committee (NTAC)
 
diff --git a/publish/niem-iepd-spec.html b/publish/niem-iepd-spec.html
index 25d23ea..8df940e 100644
--- a/publish/niem-iepd-spec.html
+++ b/publish/niem-iepd-spec.html
@@ -1,7 +1,7 @@
 
 National Information Exchange Model  Information Exchange Package
-		Documentation Specification, 5.0beta1
National Information Exchange Model — Information Exchange Package Documentation Specification
Version 5.0beta1
December 17, 2020
NIEM Technical Architecture Committee (NTAC)
Abstract
This document specifies normative rules and non-normative guidance for building a National Information Exchange Model (NIEM) information exchange package documentation (IEPD).
Status
This document deprecates the Model Package Description (MPD) construct as of NIEM 5.0.
This specification represents the work of the NIEM Technical Architecture Committee (NTAC), the NIEM Business Architecture Committee (NBAC), and their predecessors. It is a product of the NIEM Management Office (NMO).
Email comments on this specification to information@niem.gov or submit them via the GitHub issue tracker.
Contents
1. Introduction
This specification defines rules and practices for constructing and packaging a National Information Exchange Model (NIEM)information exchange package documentation (IEPD). To the NIEM program, the IEPD is considered the point of interoperability.
This specification assumes familiarity with NIEM, its basic concepts, architecture, processes, design rules, and general conformance rules. NIEM training and reference materials are located on the [NIEM TechHub]. In addition to those materials, readers of this specification may wish to be familiar with the current versions of the following:
This specification uses and is a peer to the [NIEM Naming and Design Rules].
1.1. Background
An IEPD is a normative specification for XML data components in the format of the World Wide Web Consortium (W3C) XML Schema Definition Language [W3C XML Schema Part 2 Datatypes], [W3C XML Schema Part 1 Structures]. IEPD schema documents define implementable NIEM exchange instance XML documents in W3C Extensible Markup Language (XML) [W3C XML 1.0].
An IEPD is ready to publish and use when it conforms to NIEM specifications, and has been properly packaged with the schemas, documentation, and supplemental files needed to implement or reuse it. IEPD content design, development, and assembly may be difficult and time-consuming, especially if done manually. Developers will often prefer to build and modify an IEPD with the help of software tools, which can significantly reduce the complexity of designing, constructing, changing, and managing IEPDs. In order to reduce ambiguity and to facilitate interoperable and effective tool support, this baseline specification imposes some degree of consistency on the terminology, syntax, semantics, and composition of IEPDs.
1.2. Purpose
This document is a normative specification for NIEM information exchange package documentation (IEPD). The rules and guidance herein are designed to encourage and facilitate NIEM use and tools by balancing consistency, simplicity, and flexibility. Consistency and simplicity make IEPDs easy to design correctly, build rapidly, and find easily (for reuse or adaptation). Consistency also facilitates tool support. Flexibility enables more latitude to design and tailor IEPDs for complex data exchange requirements. As such, this document does not necessarily prescribe mandates or rules for all possible situations or organizational needs. If an organization desires to impose additional requirements or constraints on its IEPDs beyond those specified in this document (for example, mandate that an IEPD contain a normative set of business requirements or a domain model), then it is free to do so, as long as no conflicts exist with this specification or the [NIEM Naming and Design Rules].
This document defines terminology; identifies required and optional (but common) artifacts; defines metadata; specifies normative constraints, schemes, syntax, and processes as rules; provides non-normative guidance; and as needed, refers to other related NIEM specifications for more detail.
1.3. Scope
This specification applies to all NIEM information exchange package documentation (IEPD), and in particular it focuses on the normative rules for IEPDs.
NIEM is a data layer for an information architecture. Files in an IEPD generally define XML Schema types and declare XML elements and attributes to use in payloads for information exchanges. While an IEPD may also contain files from layers beyond the data layer, this specification is not intended to define details of other architectural layers. Such files are generally present only to provide additional context, understanding, or assistance for implementing the exchange of payloads.
This specification defines several incremental stages of conformance to support iterative IEPD development, with conformance testing possible at each step instead of delayed to the end. Tool vendors should be able to build, adapt, and integrate software tools to assist in IEPD development and assembly, from raw parts to finished product.
This specification provides a standard version numbering scheme Section 5.2.3, IEPD Version Numbering Scheme (c:iepdVersionID), below. However, it does not provide guidance for managing or processing IEPD versions or their associated information exchange packages (IEPs). Creation and management of IEPDs is the responsibility of stakeholders and developers. As such, IEPDs have their own versioning processes, and are managed independently of the NIEM core and domains. The NIEM Management Office defines IEPD conformance, but IEPD development and management fall outside its scope. Nonetheless, the NIEM Management Office has developed guidance (through the NTAC) for managing IEPDs, versioning IEPDs, and processing their associated IEPs. This reference material can be found at https://niem.github.io/reference/artifacts/messages/iepd/.
An IEPD defines one or more data exchanges, each occurring in the form of an IEP. This specification supports a variety of data exchange use cases, in which the IEP may be:
  • An XML document with a NIEM-defined XML document element.
  • An XML document with a NIEM-defined payload element wrapped inside a non-NIEM envelope element (for example, SOAP, [Logical Entity Exchange Specifications] (LEXS), Trusted Data Format (TDF), or an OGC Web Service document element).
  • Multiple NIEM-defined payloads packaged together in a single document.
IEPD developers are not required to revise IEPDs that existed before this specification becomes effective. However, they are always encouraged to consider revising an IEPD to meet this specification, especially when making other significant changes.
1.4. Audience
The following groups should review and be familiar with this specification:
  • NIEM IEPD developers, reviewers, individuals or groups responsible for approving IEPDs, and implementers.
  • NIEM-aware tool developers.
2. Basic Concepts and Terminology
The section defines and discusses baseline terms and concepts that will be used throughout this document. Presentation in this section is sequenced for understanding. Each subsection builds upon previous ones.
2.1. IETF Best Current Practice 14 terminology
The key words MUST, MUST NOT, SHALL, SHALL NOT, SHOULD, SHOULD NOT, MAY, RECOMMENDED, REQUIRED, and OPTIONAL in this document are to be interpreted as described in [BCP 14][RFC 2119][RFC 8174].
2.2. Character Case Sensitivity
This specification imposes many constraints on the syntax for identifiers, names, labels, strings, etc. In all cases, unless otherwise explicitly noted, syntax is case sensitive. In particular, XML files in appendices that define particular artifacts, transformations, and examples are case sensitive.
Also, note that as a general principle, lower case characters are used whenever such will not conflict with the [NIEM Naming and Design Rules].
2.3. Artifacts
IEPDs are generally composed of files and file sets grouped for a particular purpose. Each file is referred to as an artifact, and each logical set of such files is called an artifact set.
[Definition: artifact]
A single file with a defined purpose.
[Definition: artifact set]
A collection of artifacts logically grouped for a defined purpose.
An IEPD is itself an artifact set, the purpose for which is to define and document the intended use of the IEPD. While the key IEPD artifacts are its XML schema document artifacts, there are also other kinds of IEPD artifacts. These may include (but are not limited to) HTML, XSLT, text, or graphic files used for human-readable documentation. An IEPD may also have artifacts intended to help assist in or accelerate the use and implementation of the IEPD. For example, these may be XML, UML, or binary files that are inputs to or outputs from software tools used to build, generate, or edit the IEPD or its schema document artifacts. Appendix C, Common IEPD Artifacts, below, contains a listing of mandatory and common optional artifacts for IEPDs. Common types of artifacts are described in more detail in subsequent sections. Section 7.1, Artifact Sets, below, discusses the different methods for grouping IEPD artifacts into sets.
2.4. Schema Document and Namespace Correspondence in NIEM
To simplify automatic schema processing and reduce the potential for confusion and error, [NIEM Naming and Design Rules] principles state that each NIEM-conformant namespace SHOULD be defined by exactly one reference or extension schema document. To support this concept, the [NIEM Naming and Design Rules] disallows the use of xs:include, and mandates the use of the xs:schema/@targetNamespace attribute in NIEM-conformant schema documents.
So, (1) each NIEM namespace is defined by a single NIEM-conformant schema document, and (2) each NIEM-conformant schema document declares a target namespace. NIEM does not permit schema documents without target namespaces, unless they are from sources outside of NIEM (e.g., an external schema document).
2.5. Namespaces Used in this Specification
The following namespaces are referenced and used in this specification:
Figure 2-1: Namespaces Used
c           http://reference.niem.gov/niem/resource/iepd/catalog/5.0/
+		Documentation Specification, 5.0beta1
National Information Exchange Model — Information Exchange Package Documentation Specification
Version 5.0beta1
February 4, 2021
NIEM Technical Architecture Committee (NTAC)
Abstract
This document specifies normative rules and non-normative guidance for building a National Information Exchange Model (NIEM) information exchange package documentation (IEPD).
Status
This document deprecates the Model Package Description (MPD) construct as of NIEM 5.0.
This specification represents the work of the NIEM Technical Architecture Committee (NTAC), the NIEM Business Architecture Committee (NBAC), and their predecessors. It is a product of the NIEM Management Office (NMO).
Email comments on this specification to information@niem.gov or submit them via the GitHub issue tracker.
Contents
1. Introduction
This specification defines rules and practices for constructing and packaging a National Information Exchange Model (NIEM)information exchange package documentation (IEPD). To the NIEM program, the IEPD is considered the point of interoperability.
This specification assumes familiarity with NIEM, its basic concepts, architecture, processes, design rules, and general conformance rules. NIEM training and reference materials are located on the [NIEM TechHub]. In addition to those materials, readers of this specification may wish to be familiar with the current versions of the following:
This specification uses and is a peer to the [NIEM Naming and Design Rules].
1.1. Background
An IEPD is a normative specification for XML data components in the format of the World Wide Web Consortium (W3C) XML Schema Definition Language [W3C XML Schema Part 2 Datatypes], [W3C XML Schema Part 1 Structures]. IEPD schema documents define implementable NIEM exchange instance XML documents in W3C Extensible Markup Language (XML) [W3C XML 1.0].
An IEPD is ready to publish and use when it conforms to NIEM specifications, and has been properly packaged with the schemas, documentation, and supplemental files needed to implement or reuse it. IEPD content design, development, and assembly may be difficult and time-consuming, especially if done manually. Developers will often prefer to build and modify an IEPD with the help of software tools, which can significantly reduce the complexity of designing, constructing, changing, and managing IEPDs. In order to reduce ambiguity and to facilitate interoperable and effective tool support, this baseline specification imposes some degree of consistency on the terminology, syntax, semantics, and composition of IEPDs.
1.2. Purpose
This document is a normative specification for NIEM information exchange package documentation (IEPD). The rules and guidance herein are designed to encourage and facilitate NIEM use and tools by balancing consistency, simplicity, and flexibility. Consistency and simplicity make IEPDs easy to design correctly, build rapidly, and find easily (for reuse or adaptation). Consistency also facilitates tool support. Flexibility enables more latitude to design and tailor IEPDs for complex data exchange requirements. As such, this document does not necessarily prescribe mandates or rules for all possible situations or organizational needs. If an organization desires to impose additional requirements or constraints on its IEPDs beyond those specified in this document (for example, mandate that an IEPD contain a normative set of business requirements or a domain model), then it is free to do so, as long as no conflicts exist with this specification or the [NIEM Naming and Design Rules].
This document defines terminology; identifies required and optional (but common) artifacts; defines metadata; specifies normative constraints, schemes, syntax, and processes as rules; provides non-normative guidance; and as needed, refers to other related NIEM specifications for more detail.
1.3. Scope
This specification applies to all NIEM information exchange package documentation (IEPD), and in particular it focuses on the normative rules for IEPDs.
NIEM is a data layer for an information architecture. Files in an IEPD generally define XML Schema types and declare XML elements and attributes to use in payloads for information exchanges. While an IEPD may also contain files from layers beyond the data layer, this specification is not intended to define details of other architectural layers. Such files are generally present only to provide additional context, understanding, or assistance for implementing the exchange of payloads.
This specification defines several incremental stages of conformance to support iterative IEPD development, with conformance testing possible at each step instead of delayed to the end. Tool vendors should be able to build, adapt, and integrate software tools to assist in IEPD development and assembly, from raw parts to finished product.
This specification provides a standard version numbering scheme Section 5.2.3, IEPD Version Numbering Scheme (c:iepdVersionID), below. However, it does not provide guidance for managing or processing IEPD versions or their associated information exchange packages (IEPs). Creation and management of IEPDs is the responsibility of stakeholders and developers. As such, IEPDs have their own versioning processes, and are managed independently of the NIEM core and domains. The NIEM Management Office defines IEPD conformance, but IEPD development and management fall outside its scope. Nonetheless, the NIEM Management Office has developed guidance (through the NTAC) for managing IEPDs, versioning IEPDs, and processing their associated IEPs. This reference material can be found at https://niem.github.io/reference/artifacts/messages/iepd/.
An IEPD defines one or more data exchanges, each occurring in the form of an IEP. This specification supports a variety of data exchange use cases, in which the IEP may be:
  • An XML document with a NIEM-defined XML document element.
  • An XML document with a NIEM-defined payload element wrapped inside a non-NIEM envelope element (for example, SOAP, [Logical Entity Exchange Specifications] (LEXS), Trusted Data Format (TDF), or an OGC Web Service document element).
  • Multiple NIEM-defined payloads packaged together in a single document.
IEPD developers are not required to revise IEPDs that existed before this specification becomes effective. However, they are always encouraged to consider revising an IEPD to meet this specification, especially when making other significant changes.
1.4. Audience
The following groups should review and be familiar with this specification:
  • NIEM IEPD developers, reviewers, individuals or groups responsible for approving IEPDs, and implementers.
  • NIEM-aware tool developers.
2. Basic Concepts and Terminology
The section defines and discusses baseline terms and concepts that will be used throughout this document. Presentation in this section is sequenced for understanding. Each subsection builds upon previous ones.
2.1. IETF Best Current Practice 14 terminology
The key words MUST, MUST NOT, SHALL, SHALL NOT, SHOULD, SHOULD NOT, MAY, RECOMMENDED, REQUIRED, and OPTIONAL in this document are to be interpreted as described in [BCP 14][RFC 2119][RFC 8174].
2.2. Character Case Sensitivity
This specification imposes many constraints on the syntax for identifiers, names, labels, strings, etc. In all cases, unless otherwise explicitly noted, syntax is case sensitive. In particular, XML files in appendices that define particular artifacts, transformations, and examples are case sensitive.
Also, note that as a general principle, lower case characters are used whenever such will not conflict with the [NIEM Naming and Design Rules].
2.3. Artifacts
IEPDs are generally composed of files and file sets grouped for a particular purpose. Each file is referred to as an artifact, and each logical set of such files is called an artifact set.
[Definition: artifact]
A single file with a defined purpose.
[Definition: artifact set]
A collection of artifacts logically grouped for a defined purpose.
An IEPD is itself an artifact set, the purpose for which is to define and document the intended use of the IEPD. While the key IEPD artifacts are its XML schema document artifacts, there are also other kinds of IEPD artifacts. These may include (but are not limited to) HTML, XSLT, text, or graphic files used for human-readable documentation. An IEPD may also have artifacts intended to help assist in or accelerate the use and implementation of the IEPD. For example, these may be XML, UML, or binary files that are inputs to or outputs from software tools used to build, generate, or edit the IEPD or its schema document artifacts. Appendix C, Common IEPD Artifacts, below, contains a listing of mandatory and common optional artifacts for IEPDs. Common types of artifacts are described in more detail in subsequent sections. Section 7.1, Artifact Sets, below, discusses the different methods for grouping IEPD artifacts into sets.
2.4. Schema Document and Namespace Correspondence in NIEM
To simplify automatic schema processing and reduce the potential for confusion and error, [NIEM Naming and Design Rules] principles state that each NIEM-conformant namespace SHOULD be defined by exactly one reference or extension schema document. To support this concept, the [NIEM Naming and Design Rules] disallows the use of xs:include, and mandates the use of the xs:schema/@targetNamespace attribute in NIEM-conformant schema documents.
So, (1) each NIEM namespace is defined by a single NIEM-conformant schema document, and (2) each NIEM-conformant schema document declares a target namespace. NIEM does not permit schema documents without target namespaces, unless they are from sources outside of NIEM (e.g., an external schema document).
2.5. Namespaces Used in this Specification
The following namespaces are referenced and used in this specification:
Figure 2-1: Namespaces Used
c           http://reference.niem.gov/niem/resource/iepd/catalog/5.0/
 er	    urn:oasis:names:tc:entity:xmlns:xml:catalog
 nc	    http://release.niem.gov/niem/niem-core/5.0/
 structures  http://release.niem.gov/niem/structures/5.0/
diff --git a/publish/niem-iepd-spec.txt b/publish/niem-iepd-spec.txt
index 7b39f1e..9c2f41a 100644
--- a/publish/niem-iepd-spec.txt
+++ b/publish/niem-iepd-spec.txt
@@ -2,7 +2,7 @@ National Information Exchange Model -- Information Exchange Package Documentatio
 
 Version 5.0beta1
 
-December 17, 2020
+February 4, 2021
 
 NIEM Technical Architecture Committee (NTAC)
 
diff --git a/src/niem-iepd-spec.xml.m4 b/src/niem-iepd-spec.xml.m4
index 028019d..69731a0 100644
--- a/src/niem-iepd-spec.xml.m4
+++ b/src/niem-iepd-spec.xml.m4
@@ -7,7 +7,7 @@
 	National Information Exchange Model <char name="mdash"/> Information Exchange Package
 		Documentation Specification
 	MACRO_document_version
-	2020-12-17
+	2021-02-04
 	NIEM Technical Architecture Committee (NTAC)