This document specifies normative rules and non-normative guidance for building a National Information Exchange Model (NIEM) information exchange package documentation (IEPD).
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.
c:iepdName)c:iepdConformanceTargetIdentifierURIList)c:iepdVersionID)c:iepdURI)c:externalURI)c:pathURI)c:resourceURI)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].
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.
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.
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:
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.
The following groups should review and be familiar with this specification:
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.
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].
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].
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.
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.
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).
The following namespaces are referenced and used in this specification:
c http://reference.niem.gov/niem/resource/iepd/catalog/5.0/ + Documentation Specification, 5.0beta1National Information Exchange Model — Information Exchange Package Documentation SpecificationVersion 5.0beta1February 4, 2021NIEM Technical Architecture Committee (NTAC)This document specifies normative rules and non-normative guidance for building a National Information Exchange Model (NIEM) information exchange package documentation (IEPD).
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.
- 1. Introduction
- 2. Basic Concepts and Terminology
- 3. Conformance Targets
- 4. IEPD XML Schema Document Artifacts
- 5. IEPD Documentation Artifacts
- 5.1. NIEM IEPD Catalog
- 5.2. Metadata Concepts
- 5.2.1. IEPD Name Syntax (
c:iepdName)- 5.2.2. IEPD Conformance Target Identifier (
c:iepdConformanceTargetIdentifierURIList)- 5.2.3. IEPD Version Numbering Scheme (
c:iepdVersionID)- 5.2.4. URI Schemes
- 5.2.4.1. IEPD URI Scheme (
c:iepdURI)- 5.2.4.2. URI Scheme for IEPD Artifacts (
c:externalURI)- 5.2.4.3. URI Scheme for Local IEPD Artifacts (
c:pathURI)- 5.2.4.4. IEPD Relationships and Lineage (
c:resourceURI)- 5.2.4.5. Resolving an IEPD URI with a Fragment
- 5.2.4.6. URI Resolution Involving Reference Elements
- 5.2.4.7. XML Catalog URI
- 5.2.4.8. Summary of IEPD URIs
- 5.3. Change Log
- 5.4. ReadMe Artifact
- 5.5. XML Catalogs
- 5.6. Defining Information Exchange Packages
- 5.7. Conformance Assertion
- 6. Optional IEPD Artifacts
- 7. Organization, Packaging, and Other Criteria
- Appendix A. IEPD Catalog XML Schema Document
- Appendix B. Example IEPD Catalog Document for Cursor on Target
- Appendix C. Common IEPD Artifacts
- Appendix D. Conformance Assertion Example
- Appendix E. Guidance for IEPD Directories (non-normative)
- Appendix F. Acronyms and Abbreviations
- Appendix G. References
- Appendix H. Index of Definitions
- Appendix I. Index of Rules
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:
- [NIEM Conformance Specification]
- [NIEM Conformance Targets Attribute Specification]
- [NIEM Naming and Design Rules]
- [NIEM Code List Specification]
- [NIEM High-Level Version Architecture]
This specification uses and is a peer to the [NIEM Naming and Design Rules].
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.
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.
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.
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.
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.
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].
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].
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.
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.
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 thexs:schema/@targetNamespaceattribute 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).
The following namespaces are referenced and used in this specification:
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 SpecificationVersion 5.0beta1December 17, 2020NIEM Technical Architecture Committee (NTAC)This document specifies normative rules and non-normative guidance for building a National Information Exchange Model (NIEM) information exchange package documentation (IEPD).
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.
- 1. Introduction
- 2. Basic Concepts and Terminology
- 3. Conformance Targets
- 4. IEPD XML Schema Document Artifacts
- 5. IEPD Documentation Artifacts
- 5.1. NIEM IEPD Catalog
- 5.2. Metadata Concepts
- 5.2.1. IEPD Name Syntax (
c:iepdName)- 5.2.2. IEPD Conformance Target Identifier (
c:iepdConformanceTargetIdentifierURIList)- 5.2.3. IEPD Version Numbering Scheme (
c:iepdVersionID)- 5.2.4. URI Schemes
- 5.2.4.1. IEPD URI Scheme (
c:iepdURI)- 5.2.4.2. URI Scheme for IEPD Artifacts (
c:externalURI)- 5.2.4.3. URI Scheme for Local IEPD Artifacts (
c:pathURI)- 5.2.4.4. IEPD Relationships and Lineage (
c:resourceURI)- 5.2.4.5. Resolving an IEPD URI with a Fragment
- 5.2.4.6. URI Resolution Involving Reference Elements
- 5.2.4.7. XML Catalog URI
- 5.2.4.8. Summary of IEPD URIs
- 5.3. Change Log
- 5.4. ReadMe Artifact
- 5.5. XML Catalogs
- 5.6. Defining Information Exchange Packages
- 5.7. Conformance Assertion
- 6. Optional IEPD Artifacts
- 7. Organization, Packaging, and Other Criteria
- Appendix A. IEPD Catalog XML Schema Document
- Appendix B. Example IEPD Catalog Document for Cursor on Target
- Appendix C. Common IEPD Artifacts
- Appendix D. Conformance Assertion Example
- Appendix E. Guidance for IEPD Directories (non-normative)
- Appendix F. Acronyms and Abbreviations
- Appendix G. References
- Appendix H. Index of Definitions
- Appendix I. Index of Rules
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:
- [NIEM Conformance Specification]
- [NIEM Conformance Targets Attribute Specification]
- [NIEM Naming and Design Rules]
- [NIEM Code List Specification]
- [NIEM High-Level Version Architecture]
This specification uses and is a peer to the [NIEM Naming and Design Rules].
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.
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.
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.
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.
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.
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].
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].
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.
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.
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 thexs:schema/@targetNamespaceattribute 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).
The following namespaces are referenced and used in this specification:
c http://reference.niem.gov/niem/resource/iepd/catalog/5.0/ + Documentation Specification, 5.0beta1National Information Exchange Model — Information Exchange Package Documentation SpecificationVersion 5.0beta1February 4, 2021NIEM Technical Architecture Committee (NTAC)This document specifies normative rules and non-normative guidance for building a National Information Exchange Model (NIEM) information exchange package documentation (IEPD).
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.
- 1. Introduction
- 2. Basic Concepts and Terminology
- 3. Conformance Targets
- 4. IEPD XML Schema Document Artifacts
- 5. IEPD Documentation Artifacts
- 5.1. NIEM IEPD Catalog
- 5.2. Metadata Concepts
- 5.2.1. IEPD Name Syntax (
c:iepdName)- 5.2.2. IEPD Conformance Target Identifier (
c:iepdConformanceTargetIdentifierURIList)- 5.2.3. IEPD Version Numbering Scheme (
c:iepdVersionID)- 5.2.4. URI Schemes
- 5.2.4.1. IEPD URI Scheme (
c:iepdURI)- 5.2.4.2. URI Scheme for IEPD Artifacts (
c:externalURI)- 5.2.4.3. URI Scheme for Local IEPD Artifacts (
c:pathURI)- 5.2.4.4. IEPD Relationships and Lineage (
c:resourceURI)- 5.2.4.5. Resolving an IEPD URI with a Fragment
- 5.2.4.6. URI Resolution Involving Reference Elements
- 5.2.4.7. XML Catalog URI
- 5.2.4.8. Summary of IEPD URIs
- 5.3. Change Log
- 5.4. ReadMe Artifact
- 5.5. XML Catalogs
- 5.6. Defining Information Exchange Packages
- 5.7. Conformance Assertion
- 6. Optional IEPD Artifacts
- 7. Organization, Packaging, and Other Criteria
- Appendix A. IEPD Catalog XML Schema Document
- Appendix B. Example IEPD Catalog Document for Cursor on Target
- Appendix C. Common IEPD Artifacts
- Appendix D. Conformance Assertion Example
- Appendix E. Guidance for IEPD Directories (non-normative)
- Appendix F. Acronyms and Abbreviations
- Appendix G. References
- Appendix H. Index of Definitions
- Appendix I. Index of Rules
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:
- [NIEM Conformance Specification]
- [NIEM Conformance Targets Attribute Specification]
- [NIEM Naming and Design Rules]
- [NIEM Code List Specification]
- [NIEM High-Level Version Architecture]
This specification uses and is a peer to the [NIEM Naming and Design Rules].
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.
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.
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.
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.
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.
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].
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].
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.
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.
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 thexs:schema/@targetNamespaceattribute 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).
The following namespaces are referenced and used in this specification:
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)