From 66b91c7bc5fcaaad9104a20919e397dea7582947 Mon Sep 17 00:00:00 2001 From: Webb Roberts Date: Fri, 18 Dec 2020 15:55:58 -0500 Subject: [PATCH] Updated text to avoid preferring the term "MPD" for a message specification. Closes https://github.com/NIEM/NIEM-NDR/issues/96. --- publish/niem-ndr.html | 4 ++-- publish/niem-ndr.txt | 6 +++--- src/ndr-doc.xml.m4 | 13 +++---------- 3 files changed, 8 insertions(+), 15 deletions(-) diff --git a/publish/niem-ndr.html b/publish/niem-ndr.html index 7fd6a70..e374cf3 100644 --- a/publish/niem-ndr.html +++ b/publish/niem-ndr.html @@ -1,6 +1,6 @@ -National Information Exchange Model Naming and Design Rules, 5.0beta1
National Information Exchange Model Naming and Design Rules
Version 5.0beta1
October 14, 2020
NIEM Technical Architecture Committee (NTAC)
Abstract

This document specifies the data model, XML Schema components, and XML data for use with the National Information Exchange Model (NIEM) version 5.0.

Authors

Webb Roberts, Georgia Tech Research Institute (<webb.roberts@gtri.gatech.edu>), Lead Author

Status

This document is a draft of the specification for XML Schema documents, components, and instances for use with NIEM 5.0. It presents a technical architecture that has evolved through the collaborative work of the NIEM Business Architecture Committee (NBAC), the NIEM Technical Architecture Committee (NTAC), and their predecessors.

This specification is a product of the NIEM Program Management Office (PMO).

Updates, revisions, and errata for this specification are posted to https://github.com/NIEM/NIEM-NDR. Please submit comments on this specification as issues at https://github.com/NIEM/NIEM-NDR/issues.

Contents
Table of Figures
Table of Tables
1. Introduction

This Naming and Design Rules (NDR) document specifies XML Schema documents for use with the National Information Exchange Model (NIEM). NIEM is an information sharing framework based on the World Wide Web Consortium (W3C) Extensible Markup Language (XML) Schema standard. In February 2005, the U.S. Departments of Justice (DOJ) and Homeland Security (DHS) signed a cooperative agreement to jointly develop NIEM by leveraging and expanding the Global Justice XML Data Model (GJXDM) into multiple domains.

NIEM is a product of a combined government and industry effort to improve information interoperability and exchange within the United States at federal, state, tribal, and local levels of government. NIEM may have started in the U.S., but its reach does not stop there. International governments and private sector organizations can benefit from the value of NIEM, as well. Communities in Europe, North America, and Australia already use NIEM for their information exchange efforts. NIEM 5.0 represents an initial step toward evolving NIEM to support a more-global exchange environment

NIEM specifies a set of reusable information components for defining standard information exchange messages, transactions, and documents on a large scale: across multiple communities of interest and lines of business. These reusable components are rendered in XML Schema documents as type, element, and attribute declarations that comply with the W3C XML Schema specification. The resulting reference schemas are available to government practitioners and developers at http://niem.gov/.

The W3C XML Schema standard enables information interoperability and sharing by providing a common language for describing data precisely. The constructs it defines are basic metadata building blocks — baseline data types and structural components. Developers employ these building blocks to describe their own domain-oriented data semantics and structures, as well as structures for specific information exchanges and components for reuse across multiple information exchanges. Rules that profile allowable XML Schema constructs and describe how to use them help ensure that those components are consistent and reusable.

This document specifies principles and enforceable rules for NIEM data components and schemas. Schemas and components that obey the rules set forth here are considered to be conformant to specific conformance targets. These targets are defined in order that they may be leveraged for comprehensive definitions of NIEM conformance. Such definitions may include more than the level of conformance defined by this NDR, and may include specific patterns of use, additional quality criteria, and requirements to reuse NIEM release schemas.

1.1. Scope

This document was developed to specify NIEM 5.0. Later releases of NIEM may be specified by later versions of this document. The document covers the following issues in depth:

  • The underlying NIEM data model
  • Guiding principles behind the design of NIEM
  • Rules for using XML Schema constructs in NIEM
  • Rules for modeling and structuring NIEM-conformant schemas
  • Rules for creating NIEM-conformant instances
  • Rules for naming NIEM components
  • Rules for extending NIEM-conformant components

This document does NOT address the following:

  • A formal definition of the NIEM data model. Such a definition would focus on the Resource Description Framework (RDF) and concepts not strictly required for interoperability. This document instead focuses on definition of schemas that work with the data model, to ensure translatability and interoperability.
  • A detailed discussion of NIEM architecture and schema versioning.
  • Aggregate artifacts that define information exchanges and models, including information exchange packages (IEPs) and their specifications, information exchange package descriptions (IEPDs) or other forms of information exchange specifications (IESs), as well as enterprise information exchange models (EIEMs), and other forms of model package descriptions (MPDs).
  • Normative guidance for the location of schema documents or for schema assembly.

This document is intended as a technical specification. It is not intended to be a tutorial or a user guide.

1.2. Audience

This document targets practitioners and developers who employ NIEM for information exchange and interoperability. Such information exchanges may be between organizations or within an organization. The NIEM reference schemas provide system implementers much content on which to build specific exchanges. However, there is a need for extended and additional content. The purpose of this document is to define the rules for such new content, so that it will be consistent with the NIEM reference schemas. These rules are intended to establish and, more importantly, enforce a degree of standardization across a broad set of users.

2. Document conventions and normative content

This document uses formatting and syntactic conventions to clarify meaning and avoid ambiguity.

2.1. Document references

This document relies on references to many outside documents. Such references are noted by bold, bracketed inline terms. For example, a reference to RFC 3986 is shown as [RFC 3986]. All reference documents are recorded in Appendix A, References, below.

2.2. Clark notation and qualified names

This document uses both Clark notation and QName notation to represent qualified names.

QName notation is defined by [XML Namespaces] Section 4, Qualified Names. A QName for the XML Schema string datatype is xs:string. Namespace prefixes used within this specification are listed in Section 2.3, Use of namespaces and namespace prefixes, below.

This document sometimes uses Clark notation to represent qualified names in normative text. Clark notation is described by [ClarkNS], and provides the information in a QName without the need to first define a namespace prefix, and then to reference that namespace prefix. A Clark notation representation for the qualified name for the XML Schema string datatype is {http://www.w3.org/2001/XMLSchema}string.

Each Clark notation value usually consists of a namespace URI surrounded by curly braces, concatenated with a local name. The exception to this is when Clark notation is used to represent the qualified name for an attribute with no namespace, which is ambiguous when represented using QName notation. For example, the element targetNamespace, which has no [namespace name] property, is represented in Clark notation as {}targetNamespace.

2.3. Use of namespaces and namespace prefixes

The following namespace prefixes are used consistently within this specification. These prefixes are not normative; this document issues no requirement that these prefixes be used in any conformant artifact. Although there is no requirement for a schema or XML document to use a particular namespace prefix, the meaning of the following namespace prefixes have fixed meaning in this document.

  • xs: The namespace for the XML Schema definition language as defined by [XML Schema Structures] and [XML Schema Datatypes], http://www.w3.org/2001/XMLSchema.
  • xsi: The XML Schema instance namespace, defined by [XML Schema Structures] Section 2.6, Schema-Related Markup in Documents Being Validated, for use in XML documents, http://www.w3.org/2001/XMLSchema-instance.
  • sch: The Schematron namespace, as defined by [Schematron], http://purl.oclc.org/dsdl/schematron.
  • nf: The namespace defined by this specification for XPath functions, http://reference.niem.gov/niem/specification/naming-and-design-rules/5.0/#NDRFunctions.
  • ct: The namespace defined by [CTAS] for the conformanceTargets attribute, http://release.niem.gov/niem/conformanceTargets/3.0/.
  • appinfo: The namespace for the appinfo namespace, http://release.niem.gov/niem/appinfo/5.0/.
  • structures: The namespace for the structures namespace, http://release.niem.gov/niem/structures/5.0/.

In addition to the prefixes above, the prefix example is used for XML examples, denoting a user-defined namespace, such as might be defined by an information exchange specification.

2.4. Normative and informative content

This document includes a variety of content. Some content of this document is normative, while other content is informative. In general, the informative material appears as supporting text, description, and rationales for the normative material.

[Definition: normative]

The term normative is as defined by [ConfReq] Section 7.2, Conformance by key words, which states:

NORMATIVE — statements provided for the prescriptive parts of the specification, providing that which is necessary in order to be able to claim conformance to the specification.

[Definition: informative]

The term informative is as defined by [ConfReq] Section 7.2, Conformance by key words, which states:

INFORMATIVE (NON-NORMATIVE) — statements provided for informational purposes, intended to assist the understanding or use of the specification and shall not contain provisions that are required for conformance.

Conventions used within this document include:

[Definition: <term>]

A formal definition of a term associated with NIEM.

Definitions are normative. Uses of these terms are given special formatting, using raised dots to identify the term, for example this use of the term conformance target.

[Principle <number>]

A guiding principle for NIEM.

The principles represent requirements, concepts, and goals that have helped shape NIEM. Principles are informative, not normative, but act as the basis on which the rules are defined.

Accompanying each principle is a short discussion that justifies the application of the principle to NIEM design.

Principles are numbered in the order in which they appear in the document.

2.4.1. Rules

A rule states a specific requirement on an artifact or on the interpretation of an artifact. The classes of artifacts are identified by conformance targets that are enumerated by this document in Section 4.1, Conformance targets defined, below. The rules are normative. Human-readable text in rules uses [BCP 14] terminology as described in Section 3.1, IETF Best Current Practice 14 terminology, below, for normative requirements and recommendations.

[Rule <section>-<number>] (<applicability>) (<classification>)

An enforceable rule for NIEM.

Each rule has a classification, which is either Constraint or Interpretation. If the classification is Constraint, then the rule is a constraint rule. If the classification is Interpretation, then the rule is an interpretation rule.

[Definition: constraint rule]

A constraint rule is a rule that sets a requirement on an artifact with respect to its conformance to a conformance target.

[Definition: interpretation rule]

An interpretation rule is a rule that sets the methodology, pattern, or procedure for understanding some aspect of an instance of a conformance target.

Each rule identifies its applicability. This identifies the conformance targets to which the rule applies. Each entry in the list is a code from Table 4-1, Codes representing conformance targets, below. If a code appears in the applicability list for a rule, then the rule applies to the corresponding conformance target. The conformance targets are defined in Section 4, Conformance targets, below. For example, a rule with applicability (REF, EXT) would be applicable to a reference schema document, as well as to an extension schema document.

Rules are stated with the help of XML Infoset terminology (e.g., elements and attributes), as described by Section 3.3, XML Information Set terminology, below, and XML Schema terminology (e.g., schema components), as described by Section 3.4, XML Schema terminology, below. The choice of terminology is driven by which terms best express a concept. Certain concepts are more clearly expressed using XML Infoset terms items, others using XML Schema terms; still others are best expressed using a combination of terminology drawn from each standard.

Rules are numbered according to the section in which they appear and the order in which they appear within that section. For example, the first rule in Section 7 is Rule 7-1.

2.4.2. Use of normative Schematron

This document defines many normative rules using Schematron rule-based validation syntax, as defined by [Schematron]. For example, see Rule 9-29, Complex type content is explicitly simple or complex (REF, EXT), below. Effort has been made to make the rules precise and unambiguous. Very detailed text descriptions of rules can introduce ambiguity, and they are not directly executable by users. Providing NDR rules that are expressed as Schematron rules ensures that the rules are precise, and that they are directly executable through commercially-available and free tools.

Many rules herein do not have executable Schematron supporting them. Some are not fit for automatic validation, and others may be difficult or cumbersome to express in Schematron. In neither case are such rules any less normative. A rule that has no Schematron is just as normative as a rule that does have Schematron. The level of requirements and recommendations within a rule is expressed using terminology from [BCP 14] as described in Section 3.1, IETF Best Current Practice 14 terminology, below.

The Schematron rules are written using XPath2 as defined by [XPath 2]. These executable rules are normative.

An execution of a Schematron pattern that issues a failed assertion (represented via sch:assert) represents a validation error, and signifies that the assessed artifact violates a requirement (i.e., a MUST) of a conformance rule. An example of a constraint rule that uses Schematron is Rule 9-10, Simple type definition is top-level (REF, EXT), below.

An execution of a Schematron pattern that issues a report (represented via sch:report) indicates a warning. This may be an indication that an automated rule has found that the assessed artifact violates a recommendation of the specification (i.e., a SHOULD, rather than a MUST), and that attention should be paid to ensure that the artifact maintains the spirit of the specification. For example, see Rule 10-42, Name of element that ends in Representation is abstract (REF, EXT), below.

In addition to the exclusive use of sch:report for warnings, this document annotates sch:report elements with attribute role="warning", which is interpreted by some Schematron platforms to indicate that a failure indicates a warning, rather than an error.

In either case, a diagnostic report generated by testing an XML document against the Schematron rules may identify specific locations (e.g., line numbers) within the document that need further attention.

2.4.3. Normative XPath functions

The Schematron within this document is supported by functions, to make the rules more comprehensible, and to abstract away process-specific operations. Each function has a normative XPath interface and a normative text definition. Any implementation provided for these functions should be considered informative, not normative, but may be useful for certain implementations of the rules.

The following XPath functions are defined normatively when used within Schematron by this specification:

  • nf:get-document-element($context as element()) as element()

    Yields the document element of the XML document in which $context occurs.

    This function provides the ability for a validator to consolidate multiple XML Schema documents and XML instance documents into a single XML document, which may simplify validation, and allow for preprocessing of xs:include elements.

  • nf:get-target-namespace($element as element()) as xs:anyURI?

    Yields the target namespace of the XML Schema document in which $element appears. If it is a schema document with no target namespace defined, then it yields the zero-length xs:anyURI value (xs:anyURI('')). If the XML document in which $element appears is not a schema document, then the function yields the empty sequence (()).

  • nf:resolve-namespace($context as element(), $namespace-uri as xs:anyURI) as element(xs:schema)?

    Yields the document element of the first available schema document that has the target namespace $namespace-uri. If there is no such schema document available, it yields the empty sequence (()).

  • nf:resolve-type($context as element(), $qname as xs:QName) as element()?

    Yields the first occurrence of an element xs:simpleType or xs:complexType that defines a type with a {target namespace} and {name} matching $qname, that is a [child] of the element yielded by nf:resolve-namespace(), above. If there is no such occurrence, it yields the empty sequence (()).

  • nf:resolve-element($context as element(), $qname as xs:QName) as element(xs:element)?

    Yields the first occurrence of an element xs:element that declares an element with a {target namespace} and {name} matching $qname, that is a [child] of the element yielded by nf:resolve-namespace(), above. If there is no occurrence available, it yields the empty sequence. (())

  • nf:has-effective-conformance-target-identifier($context as element(), $match as xs:anyURI) as xs:boolean

    Yields true if and only if an effective conformance target identifier of the XML document containing $context is $match.

2.4.4. Normative Schematron namespace declarations

The following Schematron namespace declarations are normative for the Schematron rules and supporting Schematron code within this specification:

Figure 2-1: Normative Schematron namespace declarations
<sch:ns prefix="xs" uri="http://www.w3.org/2001/XMLSchema"/>
+National Information Exchange Model Naming and Design Rules, 5.0beta1
National Information Exchange Model Naming and Design Rules
Version 5.0beta1
October 14, 2020
NIEM Technical Architecture Committee (NTAC)
Abstract
This document specifies the data model, XML Schema components, and XML data for use with the National Information Exchange Model (NIEM) version 5.0.
Authors
Webb Roberts, Georgia Tech Research Institute (<webb.roberts@gtri.gatech.edu>), Lead Author
Status
This document is a draft of the specification for XML Schema documents, components, and instances for use with NIEM 5.0. It presents a technical architecture that has evolved through the collaborative work of the NIEM Business Architecture Committee (NBAC), the NIEM Technical Architecture Committee (NTAC), and their predecessors.
This specification is a product of the NIEM Program Management Office (PMO).
Updates, revisions, and errata for this specification are posted to https://github.com/NIEM/NIEM-NDR. Please submit comments on this specification as issues at https://github.com/NIEM/NIEM-NDR/issues.
Contents
Table of Figures
Table of Tables
1. Introduction
This Naming and Design Rules (NDR) document specifies XML Schema documents for use with the National Information Exchange Model (NIEM). NIEM is an information sharing framework based on the World Wide Web Consortium (W3C) Extensible Markup Language (XML) Schema standard. In February 2005, the U.S. Departments of Justice (DOJ) and Homeland Security (DHS) signed a cooperative agreement to jointly develop NIEM by leveraging and expanding the Global Justice XML Data Model (GJXDM) into multiple domains.
NIEM is a product of a combined government and industry effort to improve information interoperability and exchange within the United States at federal, state, tribal, and local levels of government. NIEM may have started in the U.S., but its reach does not stop there. International governments and private sector organizations can benefit from the value of NIEM, as well. Communities in Europe, North America, and Australia already use NIEM for their information exchange efforts. NIEM 5.0 represents an initial step toward evolving NIEM to support a more-global exchange environment
NIEM specifies a set of reusable information components for defining standard information exchange messages, transactions, and documents on a large scale: across multiple communities of interest and lines of business. These reusable components are rendered in XML Schema documents as type, element, and attribute declarations that comply with the W3C XML Schema specification. The resulting reference schemas are available to government practitioners and developers at http://niem.gov/.
The W3C XML Schema standard enables information interoperability and sharing by providing a common language for describing data precisely. The constructs it defines are basic metadata building blocks — baseline data types and structural components. Developers employ these building blocks to describe their own domain-oriented data semantics and structures, as well as structures for specific information exchanges and components for reuse across multiple information exchanges. Rules that profile allowable XML Schema constructs and describe how to use them help ensure that those components are consistent and reusable.
This document specifies principles and enforceable rules for NIEM data components and schemas. Schemas and components that obey the rules set forth here are considered to be conformant to specific conformance targets. These targets are defined in order that they may be leveraged for comprehensive definitions of NIEM conformance. Such definitions may include more than the level of conformance defined by this NDR, and may include specific patterns of use, additional quality criteria, and requirements to reuse NIEM release schemas.
1.1. Scope
This document was developed to specify NIEM 5.0. Later releases of NIEM may be specified by later versions of this document. The document covers the following issues in depth:
  • The underlying NIEM data model
  • Guiding principles behind the design of NIEM
  • Rules for using XML Schema constructs in NIEM
  • Rules for modeling and structuring NIEM-conformant schemas
  • Rules for creating NIEM-conformant instances
  • Rules for naming NIEM components
  • Rules for extending NIEM-conformant components
This document does NOT address the following:
  • A formal definition of the NIEM data model. Such a definition would focus on the Resource Description Framework (RDF) and concepts not strictly required for interoperability. This document instead focuses on definition of schemas that work with the data model, to ensure translatability and interoperability.
  • A detailed discussion of NIEM architecture and schema versioning.
  • Aggregate artifacts that define information exchanges and models, such as message specifications, information exchange package descriptions (IEPDs) and other forms of model package descriptions (MPDs), information exchange specifications (IESs), and enterprise information exchange models (EIEMs).
  • Normative guidance for the location of schema documents or for schema assembly.
This document is intended as a technical specification. It is not intended to be a tutorial or a user guide.
1.2. Audience
This document targets practitioners and developers who employ NIEM for information exchange and interoperability. Such information exchanges may be between organizations or within an organization. The NIEM reference schemas provide system implementers much content on which to build specific exchanges. However, there is a need for extended and additional content. The purpose of this document is to define the rules for such new content, so that it will be consistent with the NIEM reference schemas. These rules are intended to establish and, more importantly, enforce a degree of standardization across a broad set of users.
2. Document conventions and normative content
This document uses formatting and syntactic conventions to clarify meaning and avoid ambiguity.
2.1. Document references
This document relies on references to many outside documents. Such references are noted by bold, bracketed inline terms. For example, a reference to RFC 3986 is shown as [RFC 3986]. All reference documents are recorded in Appendix A, References, below.
2.2. Clark notation and qualified names
This document uses both Clark notation and QName notation to represent qualified names.
QName notation is defined by [XML Namespaces] Section 4, Qualified Names. A QName for the XML Schema string datatype is xs:string. Namespace prefixes used within this specification are listed in Section 2.3, Use of namespaces and namespace prefixes, below.
This document sometimes uses Clark notation to represent qualified names in normative text. Clark notation is described by [ClarkNS], and provides the information in a QName without the need to first define a namespace prefix, and then to reference that namespace prefix. A Clark notation representation for the qualified name for the XML Schema string datatype is {http://www.w3.org/2001/XMLSchema}string.
Each Clark notation value usually consists of a namespace URI surrounded by curly braces, concatenated with a local name. The exception to this is when Clark notation is used to represent the qualified name for an attribute with no namespace, which is ambiguous when represented using QName notation. For example, the element targetNamespace, which has no [namespace name] property, is represented in Clark notation as {}targetNamespace.
2.3. Use of namespaces and namespace prefixes
The following namespace prefixes are used consistently within this specification. These prefixes are not normative; this document issues no requirement that these prefixes be used in any conformant artifact. Although there is no requirement for a schema or XML document to use a particular namespace prefix, the meaning of the following namespace prefixes have fixed meaning in this document.
  • xs: The namespace for the XML Schema definition language as defined by [XML Schema Structures] and [XML Schema Datatypes], http://www.w3.org/2001/XMLSchema.
  • xsi: The XML Schema instance namespace, defined by [XML Schema Structures] Section 2.6, Schema-Related Markup in Documents Being Validated, for use in XML documents, http://www.w3.org/2001/XMLSchema-instance.
  • sch: The Schematron namespace, as defined by [Schematron], http://purl.oclc.org/dsdl/schematron.
  • nf: The namespace defined by this specification for XPath functions, http://reference.niem.gov/niem/specification/naming-and-design-rules/5.0/#NDRFunctions.
  • ct: The namespace defined by [CTAS] for the conformanceTargets attribute, http://release.niem.gov/niem/conformanceTargets/3.0/.
  • appinfo: The namespace for the appinfo namespace, http://release.niem.gov/niem/appinfo/5.0/.
  • structures: The namespace for the structures namespace, http://release.niem.gov/niem/structures/5.0/.
In addition to the prefixes above, the prefix example is used for XML examples, denoting a user-defined namespace, such as might be defined by an information exchange specification.
2.4. Normative and informative content
This document includes a variety of content. Some content of this document is normative, while other content is informative. In general, the informative material appears as supporting text, description, and rationales for the normative material.
[Definition: normative]
The term normative is as defined by [ConfReq] Section 7.2, Conformance by key words, which states:
NORMATIVE — statements provided for the prescriptive parts of the specification, providing that which is necessary in order to be able to claim conformance to the specification.
[Definition: informative]
The term informative is as defined by [ConfReq] Section 7.2, Conformance by key words, which states:
INFORMATIVE (NON-NORMATIVE) — statements provided for informational purposes, intended to assist the understanding or use of the specification and shall not contain provisions that are required for conformance.
Conventions used within this document include:
[Definition: <term>]
A formal definition of a term associated with NIEM.
Definitions are normative. Uses of these terms are given special formatting, using raised dots to identify the term, for example this use of the term conformance target.
[Principle <number>]
A guiding principle for NIEM.
The principles represent requirements, concepts, and goals that have helped shape NIEM. Principles are informative, not normative, but act as the basis on which the rules are defined.
Accompanying each principle is a short discussion that justifies the application of the principle to NIEM design.
Principles are numbered in the order in which they appear in the document.
2.4.1. Rules
A rule states a specific requirement on an artifact or on the interpretation of an artifact. The classes of artifacts are identified by conformance targets that are enumerated by this document in Section 4.1, Conformance targets defined, below. The rules are normative. Human-readable text in rules uses [BCP 14] terminology as described in Section 3.1, IETF Best Current Practice 14 terminology, below, for normative requirements and recommendations.
[Rule <section>-<number>] (<applicability>) (<classification>)
An enforceable rule for NIEM.
Each rule has a classification, which is either Constraint or Interpretation. If the classification is Constraint, then the rule is a constraint rule. If the classification is Interpretation, then the rule is an interpretation rule.
[Definition: constraint rule]
A constraint rule is a rule that sets a requirement on an artifact with respect to its conformance to a conformance target.
[Definition: interpretation rule]
An interpretation rule is a rule that sets the methodology, pattern, or procedure for understanding some aspect of an instance of a conformance target.
Each rule identifies its applicability. This identifies the conformance targets to which the rule applies. Each entry in the list is a code from Table 4-1, Codes representing conformance targets, below. If a code appears in the applicability list for a rule, then the rule applies to the corresponding conformance target. The conformance targets are defined in Section 4, Conformance targets, below. For example, a rule with applicability (REF, EXT) would be applicable to a reference schema document, as well as to an extension schema document.
Rules are stated with the help of XML Infoset terminology (e.g., elements and attributes), as described by Section 3.3, XML Information Set terminology, below, and XML Schema terminology (e.g., schema components), as described by Section 3.4, XML Schema terminology, below. The choice of terminology is driven by which terms best express a concept. Certain concepts are more clearly expressed using XML Infoset terms items, others using XML Schema terms; still others are best expressed using a combination of terminology drawn from each standard.
Rules are numbered according to the section in which they appear and the order in which they appear within that section. For example, the first rule in Section 7 is Rule 7-1.
2.4.2. Use of normative Schematron
This document defines many normative rules using Schematron rule-based validation syntax, as defined by [Schematron]. For example, see Rule 9-29, Complex type content is explicitly simple or complex (REF, EXT), below. Effort has been made to make the rules precise and unambiguous. Very detailed text descriptions of rules can introduce ambiguity, and they are not directly executable by users. Providing NDR rules that are expressed as Schematron rules ensures that the rules are precise, and that they are directly executable through commercially-available and free tools.
Many rules herein do not have executable Schematron supporting them. Some are not fit for automatic validation, and others may be difficult or cumbersome to express in Schematron. In neither case are such rules any less normative. A rule that has no Schematron is just as normative as a rule that does have Schematron. The level of requirements and recommendations within a rule is expressed using terminology from [BCP 14] as described in Section 3.1, IETF Best Current Practice 14 terminology, below.
The Schematron rules are written using XPath2 as defined by [XPath 2]. These executable rules are normative.
An execution of a Schematron pattern that issues a failed assertion (represented via sch:assert) represents a validation error, and signifies that the assessed artifact violates a requirement (i.e., a MUST) of a conformance rule. An example of a constraint rule that uses Schematron is Rule 9-10, Simple type definition is top-level (REF, EXT), below.
An execution of a Schematron pattern that issues a report (represented via sch:report) indicates a warning. This may be an indication that an automated rule has found that the assessed artifact violates a recommendation of the specification (i.e., a SHOULD, rather than a MUST), and that attention should be paid to ensure that the artifact maintains the spirit of the specification. For example, see Rule 10-42, Name of element that ends in Representation is abstract (REF, EXT), below.
In addition to the exclusive use of sch:report for warnings, this document annotates sch:report elements with attribute role="warning", which is interpreted by some Schematron platforms to indicate that a failure indicates a warning, rather than an error.
In either case, a diagnostic report generated by testing an XML document against the Schematron rules may identify specific locations (e.g., line numbers) within the document that need further attention.
2.4.3. Normative XPath functions
The Schematron within this document is supported by functions, to make the rules more comprehensible, and to abstract away process-specific operations. Each function has a normative XPath interface and a normative text definition. Any implementation provided for these functions should be considered informative, not normative, but may be useful for certain implementations of the rules.
The following XPath functions are defined normatively when used within Schematron by this specification:
  • nf:get-document-element($context as element()) as element()
    Yields the document element of the XML document in which $context occurs.
    This function provides the ability for a validator to consolidate multiple XML Schema documents and XML instance documents into a single XML document, which may simplify validation, and allow for preprocessing of xs:include elements.
  • nf:get-target-namespace($element as element()) as xs:anyURI?
    Yields the target namespace of the XML Schema document in which $element appears. If it is a schema document with no target namespace defined, then it yields the zero-length xs:anyURI value (xs:anyURI('')). If the XML document in which $element appears is not a schema document, then the function yields the empty sequence (()).
  • nf:resolve-namespace($context as element(), $namespace-uri as xs:anyURI) as element(xs:schema)?
    Yields the document element of the first available schema document that has the target namespace $namespace-uri. If there is no such schema document available, it yields the empty sequence (()).
  • nf:resolve-type($context as element(), $qname as xs:QName) as element()?
    Yields the first occurrence of an element xs:simpleType or xs:complexType that defines a type with a {target namespace} and {name} matching $qname, that is a [child] of the element yielded by nf:resolve-namespace(), above. If there is no such occurrence, it yields the empty sequence (()).
  • nf:resolve-element($context as element(), $qname as xs:QName) as element(xs:element)?
    Yields the first occurrence of an element xs:element that declares an element with a {target namespace} and {name} matching $qname, that is a [child] of the element yielded by nf:resolve-namespace(), above. If there is no occurrence available, it yields the empty sequence. (())
  • nf:has-effective-conformance-target-identifier($context as element(), $match as xs:anyURI) as xs:boolean
    Yields true if and only if an effective conformance target identifier of the XML document containing $context is $match.
2.4.4. Normative Schematron namespace declarations
The following Schematron namespace declarations are normative for the Schematron rules and supporting Schematron code within this specification:
Figure 2-1: Normative Schematron namespace declarations
<sch:ns prefix="xs" uri="http://www.w3.org/2001/XMLSchema"/>
 <sch:ns prefix="xsl" uri="http://www.w3.org/1999/XSL/Transform"/>
 <sch:ns prefix="nf" uri="http://reference.niem.gov/niem/specification/naming-and-design-rules/5.0/#NDRFunctions"/>
 <sch:ns prefix="ct" uri="http://release.niem.gov/niem/conformanceTargets/3.0/"/>
@@ -8,7 +8,7 @@
 <sch:ns prefix="appinfo" uri="http://release.niem.gov/niem/appinfo/5.0/"/>
 <sch:ns prefix="structures" uri="http://release.niem.gov/niem/structures/5.0/"/>
Note that the binding of the prefix xml to the XML namespace (http://www.w3.org/XML/1998/namespace) is implicit.
2.5. Additional formatting
In addition to the special formatting above, this document uses additional formatting conventions.
[square brackets]: Terms in plain [square brackets] are properties of XML information set information items, as defined by [XML Infoset]. The information items and many of the information items’ properties are defined in that document. [XML Schema Structures] defines additional information item properties that are contributed by validation of an XML document against an XML Schema.
{curly brackets}: Terms in plain {curly brackets} are properties of schema components, as defined by [XML Schema Structures].
Courier: All words appearing in Courier font are values, objects, keywords, or literal XML text.
Italics: A phrase appearing in italics is one of:
  • a title of a section of document or a rule,
  • a locally-defined term, often one that is not normatively defined, or
  • is emphasized for importance or prominence.
Bold: A phrase appearing in bold is one of:
  • a term being defined within a definition,
  • a term that was bold in the original source text for a quote
  • a heading, such as for a section, a figure, a principle, definition, or rule, or
  • a cross-reference within the document, to a reference to an outside document, or to a normative heading.
Throughout the document, fragments of XML Schema or XML instances are used to clarify a principle or rule. These fragments are specially formatted in Courier font and appear in text boxes. An example of such a fragment follows:
Figure 2-2: Example of an XML fragment
<xs:complexType name="PersonType">
   ...
-</xs:complexType>
3. Terminology
This document uses standard terminology from other standards to explain the principles and rules that describe NIEM. In addition, it defines terms related to these other standards. This section enumerates this externally-dependent terminology.
3.1. IETF Best Current Practice 14 terminology
The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, NOT RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in [BCP 14] [RFC 2119] [RFC 8174] when, and only when, they appear in all capitals, as shown here.
3.2. XML terminology
[Definition: XML document]
The term XML document is as defined by [XML] Section 2, Documents, which states:
A data object is an XML document if it is well-formed, as defined in this specification. In addition, the XML document is valid if it meets certain further constraints.
3.3. XML Information Set terminology
When discussing XML documents, this document uses terminology and language as defined by [XML Infoset].
[XML Infoset] uses the term information item to describe pieces of XML documents. Documents, elements, and attributes are types of information items. The use of the term element information item, for example, refers to the term as defined by [XML Infoset]. Shorthand terms may also be used to refer to information items, such as element, as defined below. The information items are identified and defined by [XML Infoset] Section 2, Information Items.
[Definition: element]
An element is an element information item, as defined by [XML Infoset] Section 2.2, Element Information Items
[Definition: attribute]
An attribute is an attribute information item, as defined by [XML Infoset] Section 2.3, Attribute Information Items
[XML Infoset] also describes properties of information items. Each class of information item carries a set of properties. Each property has a name, and the property is identified by putting the name into square brackets. For example, the element that contains an attribute is described as the [owner element] of an attribute information item, as defined in [XML Infoset] Section 2.3, Attribute Information Items.
Shorthand terms for properties of information items include:
  • parent (of an element): the value of the [parent] property of an element information item
  • child (of an element): a member of the list of information items that is the value of the [children] property of an element information item
  • owner (of an attribute): the value of the [owner element] property of an attribute information item
  • document element: the value of the [document element] property of a document information item; preferred over the term root element.
3.4. XML Schema terminology
This document uses many terms from [XML Schema Structures] and [XML Schema Datatypes] in a normative way.
[Definition: schema component]
The term schema component is as defined by [XML Schema Structures] Section 2.2, XML Schema Abstract Data Model, which states:
Schema component is the generic term for the building blocks that comprise the abstract data model of the schema.
Note that this defines an abstract concept. This is not a direct reference to elements that are defined by the XML Schema definition language; this is an abstract concept that might be realized within a tool as an in-memory model of data objects.
[Definition: XML Schema]
The term XML Schema is as defined by [XML Schema Structures] Section 2.2, XML Schema Abstract Data Model, which states:
An XML Schema is a set of schema components.
Note, again, that this is an abstract concept: the set of abstract schema components that are put together to define a schema against which an XML document might be validated.
[Definition: XML Schema definition language]
The term XML Schema definition language is as defined by [XML Schema Structures] subsection Abstract, which states:
XML Schema: Structures specifies the XML Schema definition language, which offers facilities for describing the structure and constraining the contents of XML 1.0 documents, including those which exploit the XML Namespace facility. The schema language, which is itself represented in XML 1.0 and uses namespaces, substantially reconstructs and considerably extends the capabilities found in XML 1.0 document type definitions (DTDs).
This describes the XML syntax (and related semantics) defined by the XML Schema specifications. It is through the XML Schema definition language that a complex type definition schema component is created using the xs:complexType element.
[Definition: schema document]
The term schema document is as defined by [XML Schema Structures] Section 3.1.2, XML Representations of Components, which states:
A document in this form (i.e. a <schema> element information item) is a schema document.
This definition describes an XML document that follows the syntax of the XML Schema definition language.
[Definition: valid]
The term valid is as defined by [XML Schema Structures] Section 2.1, Overview of XML Schema, which states:
[Definition:] the word valid and its derivatives are used to refer to clause 1 above, the determination of local schema-validity.
The referenced clause 1 is a part of a description of schema-validity:
Schema-validity assessment has two aspects:
  1. Determining local schema-validity, that is whether an element or attribute information item satisfies the constraints embodied in the relevant components of an XML Schema;
  2. Synthesizing an overall validation outcome for the item, combining local schema-validity with the results of schema-validity assessments of its descendants, if any, and adding appropriate augmentations to the infoset to record this outcome.
In addition, this specification locally defines terms relevant to XML Schema concepts:
[Definition: instance document]
An instance document (of an XML Schema) is an XML document that is valid against the XML Schema.
The term instance document is used with [XML Schema Structures], but is not defined therein.
[Definition: XML Schema document set]
An XML Schema document set is a set of schema documents that together define an XML Schema suitable for assessing the validity of an XML document.
Schema assembly is a tricky topic that is not resolved by this document. Other specifications may express specifics about the process of turning a set of schema documents into an XML Schema. Methods used may include use of tool-specific schema caches and mappings, use of XML catalogs and entity resolvers, use of schemaLocation attributes on xs:import elements, and xsi:schemaLocation attributes in XML documents, among others. The topic of schema assembly is discussed in Section 6.2.10, Schema locations provided in schema documents are hints, below. This specification abstracts away details of schema assembly through the use of XPath functions described by Section 2.4.3, Normative XPath functions, above.
3.4.1. Schema components
In this document, the name of a referenced schema component may appear without the suffix schema component to enhance readability of the text. For example, the term complex type definition may be used instead of complex type definition schema component.
[Definition: base type definition]
The term base type definition is as defined by [XML Schema Structures] Section 2.2.1.1, Type Definition Hierarchy, which states:
A type definition used as the basis for an extension or restriction is known as the base type definition of that definition.
[Definition: simple type definition]
The term simple type definition is as defined by [XML Schema Structures] Section 2.2.1.2, Simple Type Definition.
[Definition: complex type definition]
The term complex type definition is as defined by [XML Schema Structures] Section 2.2.1.3, Complex Type Definition.
[Definition: element declaration]
The term element declaration is as defined by [XML Schema Structures] Section 2.2.2.1, Element Declaration.
3.4.2. Schema information set contributions
As described in Section 3.3, XML Information Set terminology, above, the XML Information Set specification defined properties of the content of XML documents. The XML Schema specification also provides properties of the content of XML documents. These properties are called Schema information set contribution, as described by [XML Schema Structures] Section 2.3, Constraints and Validation Rules, which defines them as:
Augmentations to post-schema-validation infosets expressed by schema components, which follow as a consequence of validation and/or assessment.
This document uses these property terms within definitions and other text. Terms used include:
3.5. XML Namespaces terminology
This document uses XML Namespaces as defined by [XML Namespaces].
3.6. Conformance Targets Attribute Specification terminology
[CTAS] defines several terms used normatively within this specification.
[Definition: conformance target]
The term conformance target is as defined by [CTAS], which states:
A conformance target is a class of artifact, such as an interface, protocol, document, platform, process or service, that is the subject of conformance clauses and normative statements. There may be several conformance targets defined within a specification, and these targets may be diverse so as to reflect different aspects of a specification. For example, a protocol message and a protocol engine may be different conformance targets.
[Definition: conformance target identifier]
The term conformance target identifier is as defined by [CTAS], which states:
A conformance target identifier is an internationalized resource identifier that uniquely identifies a conformance target.
[Definition: effective conformance target identifier]
The term effective conformance target identifier is as defined by [CTAS] Section 4, Semantics and Use, which states:
An effective conformance target identifier of a conformant document is an internationalized resource identifier reference that occurs in the document’s effective conformance targets attribute.
4. Conformance targets
4.1. Conformance targets defined
This section defines and describes conformance targets of this specification. Each conformance target has a formal definition, along with a notional description of the characteristics and intent of each. These include:
4.1.1. Reference schema document
[Definition: reference schema document]
A reference schema document is a schema document that is intended to provide the authoritative definitions of broadly reusable schema components. It is a conformance target of this specification. A reference schema document MUST conform to all rules of this specification that apply to this conformance target. An XML document with a conformance target identifier of http://reference.niem.gov/niem/specification/naming-and-design-rules/5.0/#ReferenceSchemaDocument MUST be a conformant reference schema document.
A reference schema document is a schema document that is intended to be the authoritative definition schema for a namespace. Examples include NIEM Core and NIEM domains.
Some characteristics of a reference schema document:
  • It is explicitly designated as a reference schema via the conformance targets attribute, per Rule 4-5, Schema claims reference schema conformance target (REF), below.
  • It provides the broadest, most fundamental definitions of components in its namespace.
  • It provides the authoritative definition of business semantics for components in its namespace.
  • It is intended to serve as the basis for components in information exchanges and extension schema documents.
  • It satisfies all rules specified in the Naming and Design Rules for reference schemas.
Any schema that defines components that are intended to be incorporated into NIEM Core or a NIEM domain will be defined as a reference schema.
The rules for reference schema documents are more stringent than are the rules for other classes of NIEM-conformant schemas. Reference schema documents are intended to support the broadest reuse. They are very uniform in their structure. As they are the primary definitions for schema components, they do not need to restrict other data definitions, and they are not allowed to use XML Schema’s restriction mechanism (e.g., Rule 9-30, Complex content uses extension (REF), below). Reference schema documents are intended to be as regular and simple as possible.
Many reference schemas are optional and over-inclusive. Data definitions in namespaces defined by reference schemas are designed with parts that are intended to be omitted or refined as needed for a particular exchange. Many reference schemas define more complex types than any individual exchange will need and define complex types that have more properties, with broader cardinality, than an individual exchange will need. Data definitions within reference schemas are designed to be a basis that is refined and specialized for a particular exchange. Developers of information exchanges are expected to subset, profile, and extend reference schemas to construct precise data definitions to match their information exchange requirements.
4.1.2. Extension schema document
[Definition: extension schema document]
An extension schema document is a schema document that is intended to provide definitions of schema components that are intended for reuse within a more narrow scope than those defined by a reference schema document. It is a conformance target of this specification. An extension schema document MUST conform to all rules of this specification that apply to this conformance target. An XML document with a conformance target identifier of http://reference.niem.gov/niem/specification/naming-and-design-rules/5.0/#ExtensionSchemaDocument MUST be an extension schema document.
Characteristics of an extension schema document include:
  • It is explicitly designated as an extension schema document via the conformance targets attribute.
  • It provides the authoritative definition of business semantics for components in its namespace.
  • It contains components that, when appropriate, use or are derived from the components in reference schema documents.
  • It is intended to express the additional vocabulary required for an information exchange, above and beyond the vocabulary available from reference schemas, and to also support additional XML Schema validation requirements for an exchange.
  • It satisfies all rules specified in this document for extension schema documents.
An extension schema in an information exchange specification serves several functions. First, it defines new content within a new namespace, which may be an exchange-specific namespace or a namespace shared by several exchanges. This content is NIEM-conformant but has fewer restrictions on it than do reference schema documents. Second, the extension schema document bases its content on content from reference schema documents, where appropriate. Methods of deriving content include using (by reference) existing schema components, as well as creating extensions and restrictions of existing components.
For example, an information exchange specification may define a type for an exchange-specific phone number and base that type on a type defined by the NIEM Core reference schema document. This exchange-specific phone number type may restrict the NIEM Core type to limit those possibilities that are permitted of the base type. Exchange extensions and restrictions must include annotations and documentation to be conformant, but they are allowed to use restriction, choice, and some other constructs that are not allowed in reference schema documents.
Note that exchange specifications may define schemas that meet the criteria of reference schemas for those components that its developers wish to nominate for later inclusion in NIEM Core or in domains.
4.1.3. Schema document set
A conformant schema document set is a set of schema documents that are capable of validating XML documents.
[Definition: conformant schema document set]
A conformant schema document set is a collection of schema documents that together are capable of validating a conformant instance XML document. It is a conformance target of this specification. A conformant schema document set MUST conform to all rules of this specification that apply to this conformance target.
A conformant schema document set has strong dependencies on reference schema documents and extension schema documents. Without the guarantees provided by those conformance targets, the rules for a conformant schema document set would not be helpful. Those schemas in a schema set that are marked as reference or extension schemas are required to conform to the appropriate conformance targets.
Rule 4-1. Schema marked as reference schema document must conform
[Rule 4-1] (SET) (Constraint)
Any schema document with an effective conformance target identifier of http://reference.niem.gov/niem/specification/naming-and-design-rules/5.0/#ReferenceSchemaDocument MUST be a reference schema document.
Rule 4-2. Schema marked as extension schema document must conform
[Rule 4-2] (SET) (Constraint)
Any schema document with an effective conformance target identifier of http://reference.niem.gov/niem/specification/naming-and-design-rules/5.0/#ExtensionSchemaDocument MUST be an extension schema document.
4.1.4. Instance documents and elements
This document has specific rules about how NIEM content should be used in XML documents. As well as containing rules for XML Schema documents, this NDR contains rules for NIEM-conformant XML content at a finer granularity than the XML document.
[Definition: conformant instance XML document]
A conformant instance XML document is an XML document that is an instance document valid to a conformant schema document set. It is a conformance target of this specification. A conformant instance XML document MUST conform to all rules of this specification that apply to this conformance target.
Characteristics of a conformant instance XML document include:
Schema-validity may be assessed against a single set of schemas or against multiple sets of schemas.
Assessment against schemas may be directed by a Model Package Description (MPD), by other instructions, or by other tools.
Note that this specification does not require the document element of a conformant instance XML document to be a conformant element information item. Other specifications, such as the MPD specification, may add additional constraints to these in order to specify MPD-specific or exchange-specific conformance constraints.
[Definition: conformant element information item]
A conformant element information item is an element information item that satisfies all of the following criteria:
Because each NIEM-conformant element information item must be locally schema-valid, each element must validate against the schema definition of the element, even if the element information item is allowed within the document because of a wildcard that the {process contents} with a value of skip. As described by [XML Schema Structures] Section 3.10.1, The Wildcard Schema Component, the content of an element introduced by a wildcard with {process contents} set to skip does not have any schema validity constraint; it is only required to be well-formed XML. Within a NIEM-conformant XML document, each element that is from a NIEM namespace conforms to its schema specification.
4.2. Applicability of rules to conformance targets
Each rule within this document is applicable to one or more of the conformance targets identified by Section 4.1, Conformance targets defined, above. Each rule identifies its applicability as described in Section 2.4.1, Rules, above. The applicability field of each rule will contain one or more code values from Table 4-1, Codes representing conformance targets, below. A rule is applicable to the identified conformance targets.
Table 4-1: Codes representing conformance targets
CodeConformance target
REFreference schema document
EXTextension schema document
SETconformant schema document set
INSconformant instance XML document
4.3. Conformance target identifiers
A conformant schema document claims to be conformant thorough the use of a set of conformance target identifiers.
Rule 4-3. Schema is CTAS-conformant
[Rule 4-3] (REF, EXT) (Constraint)
The schema document MUST be a conformant document as defined by the NIEM Conformance Targets Attribute Specification.
The term conformant document is defined by [CTAS] Section 3.2, Conformance to this Specification.
Rule 4-4. Document element has attribute ct:conformanceTargets
[Rule 4-4] (REF, EXT) (Constraint)
<sch:pattern>
+</xs:complexType>
3. Terminology
This document uses standard terminology from other standards to explain the principles and rules that describe NIEM. In addition, it defines terms related to these other standards. This section enumerates this externally-dependent terminology.
3.1. IETF Best Current Practice 14 terminology
The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, NOT RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in [BCP 14] [RFC 2119] [RFC 8174] when, and only when, they appear in all capitals, as shown here.
3.2. XML terminology
[Definition: XML document]
The term XML document is as defined by [XML] Section 2, Documents, which states:
A data object is an XML document if it is well-formed, as defined in this specification. In addition, the XML document is valid if it meets certain further constraints.
3.3. XML Information Set terminology
When discussing XML documents, this document uses terminology and language as defined by [XML Infoset].
[XML Infoset] uses the term information item to describe pieces of XML documents. Documents, elements, and attributes are types of information items. The use of the term element information item, for example, refers to the term as defined by [XML Infoset]. Shorthand terms may also be used to refer to information items, such as element, as defined below. The information items are identified and defined by [XML Infoset] Section 2, Information Items.
[Definition: element]
An element is an element information item, as defined by [XML Infoset] Section 2.2, Element Information Items
[Definition: attribute]
An attribute is an attribute information item, as defined by [XML Infoset] Section 2.3, Attribute Information Items
[XML Infoset] also describes properties of information items. Each class of information item carries a set of properties. Each property has a name, and the property is identified by putting the name into square brackets. For example, the element that contains an attribute is described as the [owner element] of an attribute information item, as defined in [XML Infoset] Section 2.3, Attribute Information Items.
Shorthand terms for properties of information items include:
  • parent (of an element): the value of the [parent] property of an element information item
  • child (of an element): a member of the list of information items that is the value of the [children] property of an element information item
  • owner (of an attribute): the value of the [owner element] property of an attribute information item
  • document element: the value of the [document element] property of a document information item; preferred over the term root element.
3.4. XML Schema terminology
This document uses many terms from [XML Schema Structures] and [XML Schema Datatypes] in a normative way.
[Definition: schema component]
The term schema component is as defined by [XML Schema Structures] Section 2.2, XML Schema Abstract Data Model, which states:
Schema component is the generic term for the building blocks that comprise the abstract data model of the schema.
Note that this defines an abstract concept. This is not a direct reference to elements that are defined by the XML Schema definition language; this is an abstract concept that might be realized within a tool as an in-memory model of data objects.
[Definition: XML Schema]
The term XML Schema is as defined by [XML Schema Structures] Section 2.2, XML Schema Abstract Data Model, which states:
An XML Schema is a set of schema components.
Note, again, that this is an abstract concept: the set of abstract schema components that are put together to define a schema against which an XML document might be validated.
[Definition: XML Schema definition language]
The term XML Schema definition language is as defined by [XML Schema Structures] subsection Abstract, which states:
XML Schema: Structures specifies the XML Schema definition language, which offers facilities for describing the structure and constraining the contents of XML 1.0 documents, including those which exploit the XML Namespace facility. The schema language, which is itself represented in XML 1.0 and uses namespaces, substantially reconstructs and considerably extends the capabilities found in XML 1.0 document type definitions (DTDs).
This describes the XML syntax (and related semantics) defined by the XML Schema specifications. It is through the XML Schema definition language that a complex type definition schema component is created using the xs:complexType element.
[Definition: schema document]
The term schema document is as defined by [XML Schema Structures] Section 3.1.2, XML Representations of Components, which states:
A document in this form (i.e. a <schema> element information item) is a schema document.
This definition describes an XML document that follows the syntax of the XML Schema definition language.
[Definition: valid]
The term valid is as defined by [XML Schema Structures] Section 2.1, Overview of XML Schema, which states:
[Definition:] the word valid and its derivatives are used to refer to clause 1 above, the determination of local schema-validity.
The referenced clause 1 is a part of a description of schema-validity:
Schema-validity assessment has two aspects:
  1. Determining local schema-validity, that is whether an element or attribute information item satisfies the constraints embodied in the relevant components of an XML Schema;
  2. Synthesizing an overall validation outcome for the item, combining local schema-validity with the results of schema-validity assessments of its descendants, if any, and adding appropriate augmentations to the infoset to record this outcome.
In addition, this specification locally defines terms relevant to XML Schema concepts:
[Definition: instance document]
An instance document (of an XML Schema) is an XML document that is valid against the XML Schema.
The term instance document is used with [XML Schema Structures], but is not defined therein.
[Definition: XML Schema document set]
An XML Schema document set is a set of schema documents that together define an XML Schema suitable for assessing the validity of an XML document.
Schema assembly is a tricky topic that is not resolved by this document. Other specifications may express specifics about the process of turning a set of schema documents into an XML Schema. Methods used may include use of tool-specific schema caches and mappings, use of XML catalogs and entity resolvers, use of schemaLocation attributes on xs:import elements, and xsi:schemaLocation attributes in XML documents, among others. The topic of schema assembly is discussed in Section 6.2.10, Schema locations provided in schema documents are hints, below. This specification abstracts away details of schema assembly through the use of XPath functions described by Section 2.4.3, Normative XPath functions, above.
3.4.1. Schema components
In this document, the name of a referenced schema component may appear without the suffix schema component to enhance readability of the text. For example, the term complex type definition may be used instead of complex type definition schema component.
[Definition: base type definition]
The term base type definition is as defined by [XML Schema Structures] Section 2.2.1.1, Type Definition Hierarchy, which states:
A type definition used as the basis for an extension or restriction is known as the base type definition of that definition.
[Definition: simple type definition]
The term simple type definition is as defined by [XML Schema Structures] Section 2.2.1.2, Simple Type Definition.
[Definition: complex type definition]
The term complex type definition is as defined by [XML Schema Structures] Section 2.2.1.3, Complex Type Definition.
[Definition: element declaration]
The term element declaration is as defined by [XML Schema Structures] Section 2.2.2.1, Element Declaration.
3.4.2. Schema information set contributions
As described in Section 3.3, XML Information Set terminology, above, the XML Information Set specification defined properties of the content of XML documents. The XML Schema specification also provides properties of the content of XML documents. These properties are called Schema information set contribution, as described by [XML Schema Structures] Section 2.3, Constraints and Validation Rules, which defines them as:
Augmentations to post-schema-validation infosets expressed by schema components, which follow as a consequence of validation and/or assessment.
This document uses these property terms within definitions and other text. Terms used include:
3.5. XML Namespaces terminology
This document uses XML Namespaces as defined by [XML Namespaces].
3.6. Conformance Targets Attribute Specification terminology
[CTAS] defines several terms used normatively within this specification.
[Definition: conformance target]
The term conformance target is as defined by [CTAS], which states:
A conformance target is a class of artifact, such as an interface, protocol, document, platform, process or service, that is the subject of conformance clauses and normative statements. There may be several conformance targets defined within a specification, and these targets may be diverse so as to reflect different aspects of a specification. For example, a protocol message and a protocol engine may be different conformance targets.
[Definition: conformance target identifier]
The term conformance target identifier is as defined by [CTAS], which states:
A conformance target identifier is an internationalized resource identifier that uniquely identifies a conformance target.
[Definition: effective conformance target identifier]
The term effective conformance target identifier is as defined by [CTAS] Section 4, Semantics and Use, which states:
An effective conformance target identifier of a conformant document is an internationalized resource identifier reference that occurs in the document’s effective conformance targets attribute.
4. Conformance targets
4.1. Conformance targets defined
This section defines and describes conformance targets of this specification. Each conformance target has a formal definition, along with a notional description of the characteristics and intent of each. These include:
4.1.1. Reference schema document
[Definition: reference schema document]
A reference schema document is a schema document that is intended to provide the authoritative definitions of broadly reusable schema components. It is a conformance target of this specification. A reference schema document MUST conform to all rules of this specification that apply to this conformance target. An XML document with a conformance target identifier of http://reference.niem.gov/niem/specification/naming-and-design-rules/5.0/#ReferenceSchemaDocument MUST be a conformant reference schema document.
A reference schema document is a schema document that is intended to be the authoritative definition schema for a namespace. Examples include NIEM Core and NIEM domains.
Some characteristics of a reference schema document:
  • It is explicitly designated as a reference schema via the conformance targets attribute, per Rule 4-5, Schema claims reference schema conformance target (REF), below.
  • It provides the broadest, most fundamental definitions of components in its namespace.
  • It provides the authoritative definition of business semantics for components in its namespace.
  • It is intended to serve as the basis for components in information exchanges and extension schema documents.
  • It satisfies all rules specified in the Naming and Design Rules for reference schemas.
Any schema that defines components that are intended to be incorporated into NIEM Core or a NIEM domain will be defined as a reference schema.
The rules for reference schema documents are more stringent than are the rules for other classes of NIEM-conformant schemas. Reference schema documents are intended to support the broadest reuse. They are very uniform in their structure. As they are the primary definitions for schema components, they do not need to restrict other data definitions, and they are not allowed to use XML Schema’s restriction mechanism (e.g., Rule 9-30, Complex content uses extension (REF), below). Reference schema documents are intended to be as regular and simple as possible.
Many reference schemas are optional and over-inclusive. Data definitions in namespaces defined by reference schemas are designed with parts that are intended to be omitted or refined as needed for a particular exchange. Many reference schemas define more complex types than any individual exchange will need and define complex types that have more properties, with broader cardinality, than an individual exchange will need. Data definitions within reference schemas are designed to be a basis that is refined and specialized for a particular exchange. Developers of information exchanges are expected to subset, profile, and extend reference schemas to construct precise data definitions to match their information exchange requirements.
4.1.2. Extension schema document
[Definition: extension schema document]
An extension schema document is a schema document that is intended to provide definitions of schema components that are intended for reuse within a more narrow scope than those defined by a reference schema document. It is a conformance target of this specification. An extension schema document MUST conform to all rules of this specification that apply to this conformance target. An XML document with a conformance target identifier of http://reference.niem.gov/niem/specification/naming-and-design-rules/5.0/#ExtensionSchemaDocument MUST be an extension schema document.
Characteristics of an extension schema document include:
  • It is explicitly designated as an extension schema document via the conformance targets attribute.
  • It provides the authoritative definition of business semantics for components in its namespace.
  • It contains components that, when appropriate, use or are derived from the components in reference schema documents.
  • It is intended to express the additional vocabulary required for an information exchange, above and beyond the vocabulary available from reference schemas, and to also support additional XML Schema validation requirements for an exchange.
  • It satisfies all rules specified in this document for extension schema documents.
An extension schema in an information exchange specification serves several functions. First, it defines new content within a new namespace, which may be an exchange-specific namespace or a namespace shared by several exchanges. This content is NIEM-conformant but has fewer restrictions on it than do reference schema documents. Second, the extension schema document bases its content on content from reference schema documents, where appropriate. Methods of deriving content include using (by reference) existing schema components, as well as creating extensions and restrictions of existing components.
For example, an information exchange specification may define a type for an exchange-specific phone number and base that type on a type defined by the NIEM Core reference schema document. This exchange-specific phone number type may restrict the NIEM Core type to limit those possibilities that are permitted of the base type. Exchange extensions and restrictions must include annotations and documentation to be conformant, but they are allowed to use restriction, choice, and some other constructs that are not allowed in reference schema documents.
Note that exchange specifications may define schemas that meet the criteria of reference schemas for those components that its developers wish to nominate for later inclusion in NIEM Core or in domains.
4.1.3. Schema document set
A conformant schema document set is a set of schema documents that are capable of validating XML documents.
[Definition: conformant schema document set]
A conformant schema document set is a collection of schema documents that together are capable of validating a conformant instance XML document. It is a conformance target of this specification. A conformant schema document set MUST conform to all rules of this specification that apply to this conformance target.
A conformant schema document set has strong dependencies on reference schema documents and extension schema documents. Without the guarantees provided by those conformance targets, the rules for a conformant schema document set would not be helpful. Those schemas in a schema set that are marked as reference or extension schemas are required to conform to the appropriate conformance targets.
Rule 4-1. Schema marked as reference schema document must conform
[Rule 4-1] (SET) (Constraint)
Any schema document with an effective conformance target identifier of http://reference.niem.gov/niem/specification/naming-and-design-rules/5.0/#ReferenceSchemaDocument MUST be a reference schema document.
Rule 4-2. Schema marked as extension schema document must conform
[Rule 4-2] (SET) (Constraint)
Any schema document with an effective conformance target identifier of http://reference.niem.gov/niem/specification/naming-and-design-rules/5.0/#ExtensionSchemaDocument MUST be an extension schema document.
4.1.4. Instance documents and elements
This document has specific rules about how NIEM content should be used in XML documents. As well as containing rules for XML Schema documents, this NDR contains rules for NIEM-conformant XML content at a finer granularity than the XML document.
[Definition: conformant instance XML document]
A conformant instance XML document is an XML document that is an instance document valid to a conformant schema document set. It is a conformance target of this specification. A conformant instance XML document MUST conform to all rules of this specification that apply to this conformance target.
Characteristics of a conformant instance XML document include:
Schema-validity may be assessed against a single set of schemas or against multiple sets of schemas.
Assessment against schemas may be directed by a message specification, such as an information exchange package description (IEPD), model package description (MPD), or information exchange specification, or by other instructions or tools.
Note that this specification does not require the document element of a conformant instance XML document to be a conformant element information item. Other specifications may add additional conformance constraints for elements within an exchange.
[Definition: conformant element information item]
A conformant element information item is an element information item that satisfies all of the following criteria:
Because each NIEM-conformant element information item must be locally schema-valid, each element must validate against the schema definition of the element, even if the element information item is allowed within the document because of a wildcard that the {process contents} with a value of skip. As described by [XML Schema Structures] Section 3.10.1, The Wildcard Schema Component, the content of an element introduced by a wildcard with {process contents} set to skip does not have any schema validity constraint; it is only required to be well-formed XML. Within a NIEM-conformant XML document, each element that is from a NIEM namespace conforms to its schema specification.
4.2. Applicability of rules to conformance targets
Each rule within this document is applicable to one or more of the conformance targets identified by Section 4.1, Conformance targets defined, above. Each rule identifies its applicability as described in Section 2.4.1, Rules, above. The applicability field of each rule will contain one or more code values from Table 4-1, Codes representing conformance targets, below. A rule is applicable to the identified conformance targets.
Table 4-1: Codes representing conformance targets
CodeConformance target
REFreference schema document
EXTextension schema document
SETconformant schema document set
INSconformant instance XML document
4.3. Conformance target identifiers
A conformant schema document claims to be conformant thorough the use of a set of conformance target identifiers.
Rule 4-3. Schema is CTAS-conformant
[Rule 4-3] (REF, EXT) (Constraint)
The schema document MUST be a conformant document as defined by the NIEM Conformance Targets Attribute Specification.
The term conformant document is defined by [CTAS] Section 3.2, Conformance to this Specification.
Rule 4-4. Document element has attribute ct:conformanceTargets
[Rule 4-4] (REF, EXT) (Constraint)
<sch:pattern>
   <sch:rule context="*[. is nf:get-document-element(.)
                        or exists(@ct:conformanceTargets)]">
     <sch:assert test="(. is nf:get-document-element(.)) = exists(@ct:conformanceTargets)"
diff --git a/publish/niem-ndr.txt b/publish/niem-ndr.txt
index 1c0e654..6dafb6e 100644
--- a/publish/niem-ndr.txt
+++ b/publish/niem-ndr.txt
@@ -70,7 +70,7 @@ Table of Tables
 
       *  A detailed discussion of NIEM architecture and schema versioning.
 
-      *  Aggregate artifacts that define information exchanges and models, including information exchange packages (IEPs) and their specifications, information exchange package descriptions (IEPDs) or other forms of information exchange specifications (IESs), as well as enterprise information exchange models (EIEMs), and other forms of model package descriptions (MPDs).
+      *  Aggregate artifacts that define information exchanges and models, such as message specifications, information exchange package descriptions (IEPDs) and other forms of model package descriptions (MPDs), information exchange specifications (IESs), and enterprise information exchange models (EIEMs).
 
       *  Normative guidance for the location of [schema documents] or for schema assembly.
 
@@ -539,9 +539,9 @@ Rule 4-2. Schema marked as extension schema document must conform
 
    Schema-validity may be assessed against a single set of schemas or against multiple sets of schemas.
 
-   Assessment against schemas may be directed by a Model Package Description (MPD), by other instructions, or by other tools.
+   Assessment against schemas may be directed by a message specification, such as an information exchange package description (IEPD), model package description (MPD), or information exchange specification, or by other instructions or tools.
 
-   Note that this specification does not require the [document element] of a [conformant instance XML document] to be a [conformant element information item]. Other specifications, such as the MPD specification, may add additional constraints to these in order to specify MPD-specific or exchange-specific conformance constraints.
+   Note that this specification does not require the [document element] of a [conformant instance XML document] to be a [conformant element information item]. Other specifications may add additional conformance constraints for elements within an exchange.
 
    [Definition: conformant element information item]
 
diff --git a/src/ndr-doc.xml.m4 b/src/ndr-doc.xml.m4
index 67d2eed..1f31182 100644
--- a/src/ndr-doc.xml.m4
+++ b/src/ndr-doc.xml.m4
@@ -161,11 +161,7 @@
         
  • 
           
    A detailed discussion of NIEM architecture and schema versioning.
    
         
    • 
-        
  • Aggregate artifacts that define information exchanges and models, including
-            information exchange packages (IEPs) and their specifications, information exchange package
-            descriptions (IEPDs) or other forms of information exchange specifications (IESs),
-            as well as enterprise information exchange models (EIEMs),
-            and other forms of model package descriptions (MPDs).
    • 
+        
  • Aggregate artifacts that define information exchanges and models, such as message specifications, information exchange package descriptions (IEPDs) and other forms of model package descriptions (MPDs), information exchange specifications (IESs), and enterprise information exchange models (EIEMs).
    • 
         
  • Normative guidance for the location of schema documents
             or for schema assembly.
    • 
       
@@ -930,14 +926,11 @@
       
    Schema-validity may be assessed against a single set of schemas or against multiple sets of
         schemas.
    
 
-      
    Assessment against schemas may be directed by a Model Package Description (MPD), by other instructions,
-      or by other tools.
    
+      
    Assessment against schemas may be directed by a message specification, such as an information exchange package description (IEPD), model package description (MPD), or information exchange specification, or by other instructions or tools.
    
 
       
    Note that this specification does not require the document element
         of a conformant instance XML
-        document to be a conformant element information item. Other specifications,
-        such as the MPD specification, may add additional constraints to these in order to specify MPD-specific
-        or exchange-specific conformance constraints.
    
+        document to be a conformant element information item. Other specifications may add additional conformance constraints for elements within an exchange.
    
 
       
         
    A conformant element information item is an element information item that satisfies all of