From 6b86c3885df7def6c4d279ee774bbd8bde7687ea Mon Sep 17 00:00:00 2001 From: Webb Roberts Date: Fri, 18 Dec 2020 16:17:44 -0500 Subject: [PATCH] Updated front matter for final release. --- changelog.md | 37 +++++++------------------------------ publish/niem-ndr.html | 2 +- publish/niem-ndr.txt | 6 +++--- src/ndr-doc.xml.m4 | 5 +---- src/ndr-macros.m4 | 4 ++-- 5 files changed, 14 insertions(+), 40 deletions(-) diff --git a/changelog.md b/changelog.md index 7498b43..ef0ddeb 100644 --- a/changelog.md +++ b/changelog.md @@ -1,41 +1,31 @@ -# NIEM NDR 5.0beta1 +# NIEM Naming and Design Rules, version 5.0rc1 -Integrated source and publication repositories. Moved all published artifacts to /publish directory. +- Issue https://github.com/NIEM/NIEM-NDR/issues/96: Updated text to avoid preferring the term "MPD" for a message specification. +- Updated front matter for final release. -Installed build system using GNU autoconf/configure, using Makefile.in. - -Added run script "run.in" for easy execution of common targets, without cluttering up the Makefile. - -## Tracked issues: +# NIEM Naming and Design Rules, version 5.0beta1 +- Integrated source and publication repositories. Moved all published artifacts to /publish directory. +- Installed build system using GNU autoconf/configure, using Makefile.in. +- Added run script "run.in" for easy execution of common targets, without cluttering up the Makefile. - Issue https://github.com/NIEM/NIEM-NDR/issues/95: Fixed error "used to by" in section 10.4. - - Issue https://github.com/NIEM/NIEM-NDR/issues/82: Remove metadata from `structures:AugmentationType`. - - Issue https://github.com/NIEM/NIEM-NDR/issues/86: Added documentation to components in the structures namespace. - - Issue https://github.com/NIEM/NIEM-NDR/issues/88: Update utility schemas for NIEM 5.0beta1. - structures: Added sequenceID. Removed structures:metadata attribute from structures:AugmentationType. Added xml:lang. Added documentation. - appinfo: Added xml:lang. Revised documentation of attribute `appinfo:deprecated`. - - Issue https://github.com/NIEM/NIEM-NDR/issues/94: Updated structures, appinfo, and schema examples, and NIEM schemas for validation, to NIEM 5.0 draft versions. - Updated example XSD NIEM subset to entire NIEM 5.0rc1 tree. - Updated structures & appinfo schemas to UTF-8. - - Issue https://github.com/NIEM/NIEM-NDR/issues/81: Add text and rules supporting attribute `structures:sequenceID`. - Added new interpretation rule defining order of properties when `structures:sequenceID` is used. - Added text in Section 5.3 clarifying that NIEM expresses order of properties of an object via `structures:sequenceID`. - - Issue https://github.com/NIEM/NIEM-NDR/issues/90.: Changed type of @structures:sequenceID to positive integer. - - Issue https://github.com/NIEM/NIEM-NDR/issues/89: Updated NIEM version to 5.0. - - Issue https://github.com/NIEM/NIEM-NDR/issues/87: Required attribute `xml:lang` on component names and xs:documentation. - - Issue https://github.com/NIEM/NIEM-NDR/issues/83: Added RDF entailment for use of structures:metadata. - Stood up a section for schema components mapping to RDF. - - Issue https://github.com/NIEM/NIEM-NDR/issues/84: Added RDF entailment for @structures:relationshipMetadata. - Added description of properties being put into named graphs using structures:relationshipMetadata. - Added introduction of RDF datasets. @@ -46,30 +36,17 @@ Added run script "run.in" for easy execution of common targets, without clutteri - Redefined RDF for elements and attributes applied via an augmentation type. Removed the separate sections for elements and attributes. Added new section for both elements and attributes, which defers to the sections for elements and attributes as simple properties. - Updated text & example in section 12 "instance metadata" section. - Broke out section on RDF mappings of instances to type information. - - Issue https://github.com/NIEM/NIEM-NDR/issues/43: Renamed table 10-2 to "Property representation terms". - - Issue https://github.com/NIEM/NIEM-NDR/issues/58: The term "linked data" now links to the W3C landing page for Linked Data. - - Issue https://github.com/NIEM/NIEM-NDR/issues/79: Added new rule 5-1, which defines the interpretation of XML data as defined by RDF mappings. - - Issue https://github.com/NIEM/NIEM-NDR/issues/72: Removed use of in rules. - - Issue https://github.com/NIEM/NIEM-NDR/issues/91: Clarify that properties are unordered in §5. - - Issue https://github.com/NIEM/NIEM-NDR/issues/92: Added principle of "optional and over-inclusive". Added to the section defining the "reference schema document" conformance target - - Issue https://github.com/NIEM/NIEM-NDR/issues/93: Revised definition of Representation Term "Date". - Revised to "A continuous or recurring period of time, of a duration greater than or equal to a day." - - Issue https://github.com/NIEM/NIEM-NDR/issues/76: Corrected name of RDF. - - Issue https://github.com/NIEM/NIEM-NDR/issues/75: Added new MUST rule that requires a component with a name ending in 'SimpleType' be a simple type definition, and with a name ending in 'Type' be a complex type definition. - - Issue https://github.com/NIEM/NIEM-NDR/issues/74: Fixed missing "an" in definition of conformant instance XML document. - - Issue https://github.com/NIEM/NIEM-NDR/issues/80: Added representation term "Representation" to table "Property representation terms". - - Issue https://github.com/NIEM/NIEM-NDR/issues/71: Revised section heading that repeated "id" instead of using "ref". - - Issue https://github.com/NIEM/NIEM-NDR/issues/70: Fix whitespace/blank lines in 5.6.2. RDF Literals diff --git a/publish/niem-ndr.html b/publish/niem-ndr.html index e374cf3..7a8c2ac 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, 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"/>
+National Information Exchange Model Naming and Design Rules, 5.0
National Information Exchange Model Naming and Design Rules
Version 5.0
December 18, 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 specifies the data model, XML Schema components, and XML data for use with the National Information Exchange Model (NIEM) version 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/"/>
diff --git a/publish/niem-ndr.txt b/publish/niem-ndr.txt
index 6dafb6e..48fb5eb 100644
--- a/publish/niem-ndr.txt
+++ b/publish/niem-ndr.txt
@@ -1,8 +1,8 @@
 National Information Exchange Model Naming and Design Rules
 
-Version 5.0beta1
+Version 5.0
 
-October 14, 2020
+December 18, 2020
 
 NIEM Technical Architecture Committee (NTAC)
 
@@ -16,7 +16,7 @@ Authors
 
 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 document specifies the data model, XML Schema components, and XML data for use with the National Information Exchange Model (NIEM) version 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).
 
diff --git a/src/ndr-doc.xml.m4 b/src/ndr-doc.xml.m4
index 1f31182..e58b583 100644
--- a/src/ndr-doc.xml.m4
+++ b/src/ndr-doc.xml.m4
@@ -60,10 +60,7 @@
 
   Status
 
-    
This document is a draft of the specification for XML Schema documents, components, and instances
-      for use with NIEM MACRO_NIEM_VERSION. 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 document specifies the data model, XML Schema components, and XML data for use with the National Information Exchange Model (NIEM) version MACRO_NIEM_VERSION.  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).

 
diff --git a/src/ndr-macros.m4 b/src/ndr-macros.m4
index 9d0ead9..1d8c816 100644
--- a/src/ndr-macros.m4
+++ b/src/ndr-macros.m4
@@ -2,8 +2,8 @@ m4_define([[[MACRO_COMMENT]]],)m4_dnl
 m4_define([[[MACRO_DOCUMENT_URI]]],[[[http://reference.niem.gov/niem/specification/naming-and-design-rules/5.0/]]])m4_dnl
 m4_define([[[MACRO_NIEM_VERSION]]],[[[5.0]]])m4_dnl version of niem this NDR is for
 m4_define([[[MACRO_NDR_VERSION]]],[[[5.0]]])m4_dnl
-m4_define([[[MACRO_NDR_DOCUMENT_VERSION]]],[[[5.0beta1]]])m4_dnl
-m4_define([[[MACRO_NDR_DATE]]],[[[2020-10-14]]])m4_dnl
+m4_define([[[MACRO_NDR_DOCUMENT_VERSION]]],[[[5.0]]])m4_dnl
+m4_define([[[MACRO_NDR_DATE]]],[[[2020-12-18]]])m4_dnl
 m4_dnl
 m4_dnl HREFs...
 m4_dnl