model-package-description-3.0.1.txt

National Information Exchange Model -- Model Package Description Specification

Version 3.0.1

April 27, 2015

NIEM Technical Architecture Committee (NTAC)

URI

   http://reference.niem.gov/niem/specification/model-package-description/3.0.1/

Contents

   The table of contents is omitted from this edition.

Abstract

   This document specifies normative rules and non-normative guidance for building Model Package Descriptions (MPDs) that conform to the National Information Exchange Model (NIEM) version 3.0.

Status

   This document is the normative specification for NIEM [model package descriptions] (MPDs). It supersedes both [NIEM MPD Specification 1.0] and [NIEM MPD Specification 1.1], as well as [IEPD] guidance previously published in [Requirements for a NIEM IEPD 2.1].

   This specification focuses on the rules for MPDs in general, and for [information exchange package documentation] (IEPD) MPDs specifically. Relevant NIEM specifications will address the rules for other [MPD classes] in the future.

   At some time in the future NTAC will design, test, and publish a set of Schematron rules that correspond to constraint rules in this this MPD Specification.

   The MPD Specification represents the collaborative work of the NIEM Technical Architecture Committee (NTAC), the NIEM Business Architecture Committee (NBAC), and their predecessors. It is a product of the NIEM Program Management Office (PMO).

   Email comments on this specification to niem-comments@lists.gatech.edu.

1. Introduction

   This specification assumes familiarity with the National Information Exchange Model (NIEM), its basic concepts, architecture, processes, design rules, and general conformance rules. For novices to NIEM, the recommended reading list includes:

      *  [NIEM Introduction]

      *  [NIEM Conformance 3.0]

      *  [NIEM Conformance Targets Attribute Specification 3.0]

      *  [NIEM Naming and Design Rules 3.0]

      *  [NIEM High-Level Version Architecture 3.0]

      *  [NIEM High-Level Tool Architecture 1.1]

      *  [NIEM Implementation Guide]

   Even those already knowledgeable of NIEM should be familiar with [NIEM Conformance 3.0], [NIEM Naming and Design Rules 3.0], [NIEM Conformance Targets Attribute Specification 3.0], and [NIEM High-Level Version Architecture 3.0].

   The NIEM documents listed above are available at http://reference.niem.gov/niem/. See [NIEM Implementation Guide] for the NIEM implementation guidelines Web page.

   [NIEM MPD Specification 3.0] uses and is a peer to the NIEM Naming and Design Rules [NIEM Naming and Design Rules 3.0].

1.1. Background

   Many fundamental concepts, processes, and products in the NIEM generally involve aggregating electronic files into logical sets that serve a specific purpose. Examples of such sets include, but are not necessarily limited to, a NIEM release, domain update, [information exchange package documentation] (IEPD), and Enterprise Information Exchange Model (EIEM). Each of these is an example of a NIEM [model package description] (MPD).

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

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

1.2. Purpose

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

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

1.3. Scope

   This specification applies to all NIEM [model package descriptions] (MPD). Currently, NIEM MPDs include the following:

      *  [information exchange package documentation] (IEPD) -- Defines a NIEM data exchange, and is the primary focus of this specification.

      *  Release -- Includes a major, minor, or micro release of the NIEM model, or a core supplement applicable to one or more releases. See [NIEM High-Level Version Architecture 3.0].

      *  Domain update -- Allows a NIEM domain to change or add to the content of its own domain schema document in a published release. See [NIEM Domain Update Specification 1.0].

      *  Enterprise Information Exchange Model (EIEM) -- A model derived from a NIEM release on which one or more IEPDs can be based. See the NIEM concept paper [NIEM Business Information Exchange Components 1.0]. A normative specification for this concept does not yet exist.

   This document is the baseline specification for all MPDs, and in particular, it focuses on the normative rules for IEPDs. In the future, detailed rules that apply to other MPDs (listed above) will be published in other NIEM specifications. Also, in the future, other types of MPDs may be added to this list.

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

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

   An MPD developer is not required to revise an MPD that existed before this specification becomes effective. However, he is always encouraged to consider revising an MPD to meet this specification, especially when making other significant changes.

1.3.1. Information Exchange Package Documentation

   This specification defines rules and practices for constructing and packaging conformant [MPDs], and in particular, [information exchange package documentation] (IEPDs). To the NIEM program, the [IEPD] is considered the point of interoperability. This specification provides a standard version numbering scheme Section 5.2.3, MPD Version Numbering Scheme (c:mpdVersionID), below. However, it does not provide guidance for managing or processing [IEPD] versions or their associated [IEPs]. Creation and management of [IEPDs] is the responsibility of stakeholders and developers. As such, [IEPDs] have their own versioning processes, and are managed independently of the NIEM core and domains. NIEM PMO defines [IEPD] conformance, but [IEPD] development and management fall outside its scope. Nonetheless, in the near term, the PMO intends to develop guidance (through the NTAC) for managing [IEPDs], versioning [IEPDs], and processing their associated [IEPs].

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

      *  An XML document with a NIEM-defined XML document element.

      *  An XML document with a NIEM-defined payload element wrapped inside a non-NIEM envelope element (for example, SOAP, [Logical Entity Exchange Specification] (LEXS), Trusted Data Format (TDF), or an OGC Web Service document element).

      *  Multiple NIEM-defined payloads packaged together in a single document.

      *  A non-NIEM format defined with no NIEM content at all (for example, a data exchange specified by a GML application schema). 

      *  A non-NIEM format in which optional NIEM elements do not occur (for example, optional hospital information, provided as a NIEM element). 

1.4. Audience

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

      *  NIEM [MPD] developers, reviewers, and individuals or groups responsible for approving MPDs.

      *  NIEM [IEPD] developers, reviewers, and implementers.

      *  NIEM-aware tool developers.

2. Basic Concepts and Terminology

   The section defines and discusses baseline terms and concepts that will be used throughout this document. Presentation in this section is sequenced for understanding. Each subsection builds upon previous ones. The section concludes with a more detailed discussion of MPDs and more specifically, IEPDs.

2.1. Key Words for Requirement Levels

   Within normative content rules and definitions, the key words MUST, MUST NOT, SHALL, SHALL NOT, SHOULD, SHOULD NOT, MAY, RECOMMENDED, REQUIRED, and OPTIONAL in this document are to be interpreted as described in [RFC 2119 Key Words].

2.2. Character Case Sensitivity

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

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

2.3. Artifacts

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

   [Definition: artifact]

      A single file with a defined purpose.

   [Definition: artifact set]

      A collection of artifacts logically grouped for a defined purpose.

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

2.4. Schema Document and Namespace Correspondence in NIEM

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

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

2.5. Namespaces Used in this Specification

   The following namespaces are referenced and used in this specification:

   Figure 2-1: Namespaces Used

      
      	c		http://reference.niem.gov/niem/resource/mpd/catalog/3.0/
      	er		urn:oasis:names:tc:entity:xmlns:xml:catalog
      	nc		http://release.niem.gov/niem/niem-core/3.0/
      	structures	http://release.niem.gov/niem/structures/3.0/
      	xs		http://www.w3.org/2001/XMLSchema
      		

2.6. Harmonization

   A key NIEM concept important to [harmonization] and used throughout this specification is [data component].

   [Definition: data component]

      An XML Schema type or attribute group definition; or an XML Schema element or attribute declaration.

   [Harmonization] is a process that NIEM governance committees and domain stewards iteratively apply to NIEM content (specifically, its semantics, structure, and relationships) during the preparation of a NIEM major or minor release. On a more restricted scale a domain steward harmonizes his/her own content (schema documents) in preparation for a domain update [MPD]. Multiple domain stewards may collaborate in a coordinated domain update. In this case, to the extent possible, harmonization may be applied across the content of all the collaborating domains. Harmonization results in model change and evolution with the intent of removing semantic duplication and overlap while improving representational quality and usability.

   [Definition: harmonization]

      The process of reviewing a data model's existing data definitions and declarations; reviewing how it structures and represents data; integrating new [data components]; and refactoring [data components] as necessary to remove (or reduce to the maximum extent feasible) semantic duplication and/or overlap among all data structures and definitions resulting in quality improvements to representation and usability.

2.7. XML Validation

   A discussion of XML validation requires an understanding of basic XML terminology. The following definitions are necessary.

   [Definition: XML document]

      A document in XML format.

      (as defined by [W3C XML 1.0],  section 2, "Documents")

   [Definition: schema component]

      The generic term for the building blocks that comprise the abstract data model of a schema.

      (as defined by [W3C XML Schema Part 1 Structures],  section 2.2, "XML Schema Abstract Data Model")

   [Definition: XML Schema]

      A set of schema components.

      (as defined by [W3C XML Schema Part 1 Structures],  section 2.2, "XML Schema Abstract Data Model")

   [Definition: XML schema validation]

      The process of checking an [XML document] to confirm that it is both well-formed (as defined by [W3C XML 1.0],  section 2.1, "Well-Formed XML Documents") and valid (as defined by [W3C XML Schema Part 1 Structures],  section 2.3, "Constraints and Validation Rules"), in that it follows the structure defined by an associated [XML Schema]. A well-formed document follows the syntactic rules of XML, which are the same for all XML documents.

   [Definition: XML schema document]

      A physical (file) representation of part or all of an [XML Schema]. One or more XML schema documents are used to assemble [schema components] into an [XML Schema].

   [Definition: XML schema assembly]

      A process that uses [XML schema documents] to identify the constituent [schema components] for an [XML Schema], and correctly sequences and structures these components to construct a single entity, the [XML Schema].

   In other words, an [XML Schema] is the result of [XML schema assembly], i.e., processing a set of one or more [XML schema documents] into a single entity. That entity is most commonly an electronic image in the memory of a computer.

   This specification often refers to the process of [XML schema validation], that is, validation of an instance XML document to confirm it adheres to the structure defined by a particular [XML Schema]. Generally, this should occur periodically during and after design time to ensure the conformance and quality of an information exchange definition (i.e., [XML schema documents]) and associated instance XML documents. However, local architecture or policy may dictate the need to validate more often, and in some cases may even require runtime validation. To be clear, NIEM conformance does not require that instance documents be validated at runtime.

   XML schema document sets that define a NIEM information exchange must be authoritative. Application developers may use other schemas (e.g., constraint or Schematron schema documents) for various purposes, but for the purposes of determining NIEM conformance, the authoritative reference schema documents (NIEM releases) are relevant. This does not mean that XML validation must be performed on all instance XML documents as they are served or consumed; only that the instance XML documents validate if and when XML validation is performed. Therefore, even when validation is not performed, instance XML documents must be valid against the XML schema that is assembled from XML schema document sets that specify these instance XML documents.

2.8. Reference Schema Documents

   [Definition: reference schema document]

      As defined by [NIEM Naming and Design Rules 3.0]:

         An [XML schema document] that is intended to provide the authoritative definitions of broadly reusable [schema components]. It is a [conformance target] of [NIEM Naming and Design Rules 3.0]. A reference schema document MUST conform to all rules of [NIEM Naming and Design Rules 3.0] that apply to this conformance target. An [instance XML document] with a [conformance target identifier] of http://reference.niem.gov/niem/specification/naming-and-design-rules/3.0/#ReferenceSchemaDocument MUST be a conformant reference schema document.

   A NIEM [reference schema document] is an [XML schema document] that is intended to be the authoritative definition of business semantics for components within its target namespace. The NIEM core schema documents, NIEM domain schema documents, and NIEM domain update schema documents are all [reference schema documents]. A reference schema document meets all of the following criteria:

      *  It is a NIEM conformant schema document.

      *  It is explicitly designated as a reference schema document by its own conformance targets attribute. This can be declared by an [MPD catalog document] or by a tool-specific mechanism outside the schema document.

      *  It provides the broadest, most fundamental definitions of [data components] in its namespace.

      *  It provides the authoritative definition of business semantics for [data components] in its namespace.

      *  It is intended to serve as a basis for components in [IEPD] schema documents, including [schema document subsets], [constraint schema document sets], and [extension schema documents].

   [Definition: reference schema document set]

      A set of related [reference schema documents], such as a NIEM release.

   The [NIEM Naming and Design Rules 3.0] conformance rules for reference schema documents are generally stricter than those for other classes of NIEM-conformant schema documents. For example, [reference schema documents] are not allowed to employ particular XML Schema model groups such as xs:choice or xs:any that other schema documents may contain.

   NIEM reference schemas are very uniform in their structure. As they are the primary definitions for [data components], they do not need to restrict other data definitions, and so they are not allowed to use XML Schema's complex type restriction mechanisms.

2.9. Rules

   Rules define specific constraints on artifacts or on the interpretation of artifacts. The classes of artifacts are identified by [conformance targets] that are enumerated by this document in Section 3, Conformance Targets, below. Rules are normative.

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

      An enforceable rule for NIEM.

   Each rule has a classification, which is either Constraint or Interpretation. These terms are defined below:

   [Definition: constraint rule]

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

   [Definition: interpretation rule]

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

   Each rule may apply to one or more [conformance targets]. Each rule lists its applicable [conformance target(s)] encoded per Table Table 3-1, Rule Applicability Codes, below. The conformance targets for this specification are detailed in Section 3, Conformance Targets, below.

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

3. Conformance Targets

   This section introduces [conformance targets], a concept fundamental to understanding the normative rules defined in this specification. This section also defines and explains [conformance targets] used in this specification.

   There are several purposes for defining conformance targets in NIEM specifications. A [conformance target] establishes and identifies a class of artifact associated with a set of rules. Based on these rules, tools and operations may be developed to process or use these artifacts consistently.

   Conformance targets also satisfy a need to ensure developers do not conform to NIEM in name only. Once committed to using NIEM, developers and organizations need well-defined conformance targets and rules to know exactly how to conform. Funding agencies require conformance targets that correspond to interoperability goals. An agency that is funding development of a set of systems will need to ensure it funds the development of NIEM-conformant IEPDs that support the exchange of NIEM-conformant IEPs. Tools and system developers need conformance targets that identify real world requirements corresponding to their use cases and tool capabilities. Many of these tools have not yet been developed. Therefore, this specification attempts to cover a broad range of general use cases.

3.1. Conformance Target Terminology

   [NIEM Conformance Targets Attribute Specification 3.0] defines two terms used normatively and often within this specification.

   [Definition: conformance target]

      As defined by [NIEM Conformance Targets Attribute Specification 3.0]:

         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]

      As defined by [NIEM Conformance Targets Attribute Specification 3.0]:

         An internationalized resource identifier [RFC 3987 IRI] that uniquely identifies a conformance target.

   It will also be useful to define [MPD class].

   [Definition: MPD class]

      A [conformance target identifier] to which a given [MPD] claims to conform. The [MPD class] of an [MPD] is established by Rule 5-9, MPD Class Determined by Conformance Target Identifier in c:mpdClassURIList.

3.2. MPD Conformance Targets

   This specification establishes two primary [MPD] [conformance targets]: [model package description] and [information exchange package documentation].

   An [MPD] may be constructed manually, but it is far more efficient to generate an MPD entirely or in part using NIEM-aware software tools. The existence of a [model package description] [conformance target] has several advantages:

      *  Facilitates the existence of many incremental states from start to finish that are checkpoints for well-formedness.

      *  Enables multiple paths to completion; no single pre-determined sequence of rule applications is required.

      *  Provides tool developers with the flexibility to construct an [MPD] incrementally in many different sequences.

      *  Avoids a need to build a complete [MPD] before automated correctness checks can be applied (since well-formedness can be checked at many stages of development).

      *  Facilitates the interoperability and use of multiple tools that can export/import a [model package description].

      *  A [model package description] is a basis for consistency across all [MPD] classes.

   Because an MPD is always a directory tree, for the purpose of transporting, up/downloading, and archiving for long term storage, an MPD is packaged as a [ZIP file].

   [Definition: ZIP file]

      As defined by [PKZIP], which states that it defines:

         ... a cross-platform, interoperable file storage and transfer format ... used to aggregate, compress, and encrypt files into a single interoperable container.

3.2.1. The Model Package Description Conformance Target

   The concept of [model package description] provides a common framework for classes of NIEM file sets, each with a specific purpose. A NIEM release is a harmonized [reference schema document] set that defines and declares all content for a single (major, minor, or micro) version of NIEM (See [NIEM High-Level Version Architecture 3.0]). A core supplement is a special type of release. It is a [reference schema document] set of additive changes that append data components to the core of a NIEM release without modifying the original niem-core schema document. A domain update is a [reference schema document] set that represents changes to one or more domains in a NIEM release. An Enterprise Information Exchange Model (EIEM) is a [XML schema document] set that may contain one or more [subset schema documents], [extension schema documents], and [external schema documents] that are employed to construct IEPDs.

   All MPDs share several commonalities; each MPD:

      *  Is a set of [artifacts], whose principal content is [XML schema documents] (XSD), the purpose for which is to define and declare reusable [data components] for information exchanges or to define the exchanges themselves.

      *  Requires a self-documenting mpd-catalog.xml artifact containing metadata and a listing of its key artifacts. This artifact establishes identification metadata, [conformance targets], purpose, general content, lineage, and other metadata.

      *  Requires the following metadata:

            *  Uniform Resource Identifier (URI) (See Section 5.2.4.1, MPD URI Scheme (c:mpdURI), below)

            *  Name (See Section 5.2.1, MPD Name Syntax (c:mpdName), below)

            *  Version number (See Section 5.2.3, MPD Version Numbering Scheme (c:mpdVersionID), below)

            *  The [conformance target identifier] http://reference.niem.gov/niem/specification/model-package-description/3.0/#MPD (See Section 5.2.2, MPD Class (c:mpdClassURIList), below)

      *  Contains a copy of (not just URLs or references to) all schema documents needed to validate any [instance XML document] class it defines.

      *  May contain optional alternate representations in addition to XML Schema (e.g., generic diagram, UML/XMI, database format, spreadsheet, etc.).

      *  May contain miscellaneous other documentation or file artifacts for assisting with usage or implementation.

   [Definition: model package description]

      A [model package description] is a set of [artifacts] (possibly in a [ZIP file]) that:

         *  includes a set of logically cohesive W3C XML Schema documents and other supporting files that represent one or more reusable or implementable XML information models, and

         *  has an [MPD class] of http://reference.niem.gov/niem/specification/model-package-description/3.0/#MPD, and

         *  adheres to all the rules within this specification for the [model package description] [conformance target].

      This term may be abbreviated "MPD". Rules specifying this conformance target use the applicability code "WF-MPD".

   The schemas and other files within a [model package description] are built on other specifications, including:

      *  [NIEM Naming and Design Rules 3.0]

      *  [NIEM Conformance Targets Attribute Specification 3.0]

      *  [NIEM Conformance 3.0]

   The following rule applies to all MPDs:

Rule 3-1. MPD Conformance Target Identifier

   [Rule 3-1] (WF-MPD)

      An [MPD] MUST have an [MPD class] of http://reference.niem.gov/niem/specification/model-package-description/3.0/#MPD.

   A [model package description] satisfies the need for a set of [artifacts] (or a [ZIP file]) with an [MPD catalog document] that validates to the MPD catalog schema, and contains no broken links to local artifacts it references. This definition enables a developer to build an [MPD] by iteratively adding artifacts and expanding the MPD catalog to reference them.

   Most rules in this [MPD] specification are applicable to a [model package description] [conformance target]. Rules for this conformance target are less concerned with the correct use of NIEM and completeness, and more concerned with proper format, proper structure (e.g., link integrity), and correct use of artifacts. Adherence to these rules can produce an [IEPD] that is well-formed (WF-MPD), but that does not necessarily satisfy all general and specific requirements for an [IEPD]. The following rule ensures that a complete [IEPD] adheres to all applicable NIEM conformance rules.

3.2.2. IEPD Conformance Target

   [Definition: information exchange package documentation]

      An [information exchange package documentation] is a [model package description] that:

         *  has an [MPD class] of http://reference.niem.gov/niem/specification/model-package-description/3.0/#IEPD, and

         *  conforms to all the rules in this specification for the conformance target [information exchange package documentation] (i.e., applicability code "IEPD").

      This term may be abbreviated "IEPD". Rules specifying this conformance target use the applicability code "IEPD".

   Because it is an [MPD], an IEPD must also conform to all WF-MPD rules.

   An [IEPD] has one or more c:IEPConformanceTarget elements within its [MPD catalog document], each defining a class of [information exchange packages] (IEP), in which each [IEP] is an [instance XML document].

   [Definition: instance XML document]

      An [instance XML document] is an [XML document] that is valid against an [XML Schema]. An [instance XML document] is said to be an instance of the schema to which it validates.

   An IEPD also defines one or more data exchanges, one per [conformance target]. Each data exchange occurs at runtime in the form of an [instance XML document], which is an [IEP] that conforms to the rules defined in the c:IEPConformanceTarget element.

   An [IEPD] contains a NIEM-conformant XML schema document set that may include portions of a NIEM core schema document (and supplements), portions of NIEM Domain schema documents (and updates), and enterprise-specific or IEPD-specific [extension schema documents]. The [XML schema documents] contained in an [IEPD] work together to define one or more classes of [instance XML documents] that consistently encapsulate data for meaningful information exchanges. Any [instance XML document] that is valid for the [XML schema document] set and that satisfies the conditions of the [IEP conformance target] is a member of that [IEP conformance target] class (or IEP Class).

   [XML schema documents] in an [IEPD] conform to the [NIEM Naming and Design Rules 3.0] and may use or extend data component definitions drawn from NIEM. An [IEPD] may also incorporate and use XML schema documents from other standards that do not conform to NIEM. (See [NIEM Naming and Design Rules 3.0] for details.) An [IEPD] consists of a set of artifacts (XML schema documents, documentation, sample instance XML documents, etc.) that together define and describe one or more implementable data exchanges. An [IEPD] should contain all materials necessary to:

      *  Understand information exchange context, content, semantics, and structure.

      *  Create and validate XML documents defined by the [IEPD], and used for information exchanges.

      *  Identify the lineage of the [IEPD] itself and optionally its artifacts.

   (The terms [information exchange package] (IEP) and [information exchange package documentation] (IEPD) first appeared in [FEA Data Reference Model 1.0] and [GJXDM IEPD Guidelines 1.1], respectively.)

   The following rule specifies an [IEPD] as a [conformance target]:

Rule 3-2. MPD with MPD class of IEPD is an IEPD

   [Rule 3-2] (MPD)

      A [model package description] with an [MPD class] of http://reference.niem.gov/niem/specification/model-package-description/3.0/#IEPD MUST be an [information exchange package documentation].

   The following rule is applicable to all IEPDs:

Rule 3-3. IEPD Conformance Target Identifier

   [Rule 3-3] (IEPD)

      An [IEPD] MUST have the [conformance target identifier] http://reference.niem.gov/niem/specification/model-package-description/3.0/#IEPD as a value of its c:mpdClassURIList attribute.

   How to declare validity constraints for one or more IEP classes within an [IEPD] will be covered in more depth in Section 5.6, Defining Information Exchange Packages, below.

   Note that NIEM conformance does not require that an IEP be native XML on the transmission medium. A NIEM-conformant IEP may be encrypted, compressed (e.g., using [PKZIP], [EXI Format 1.0], etc.), or wrapped within an envelope mechanism, as long as its original native XML form can be retrieved by the receiver.

   Common to [IEPD] MPDs:

      *  Requires a readme artifact.

      *  Its [XML schema document] set defines data exchanges ([information exchange packages] or IEPs).

      *  Can contain subset, extension, external, or constraint schema documents.

      *  Must declare at least one or more [IEP conformance targets].

      *  Contains sample instance XML documents that validate to XML schema document set.

3.2.3. IEP Conformance Targets

   In NIEM, an information exchange instance is an [information exchange package] (IEP). An IEP is also a [conformance target] and in that connotation is defined as follows:

   [Definition: information exchange package]

      An XML [instance XML document] that conforms to the conformance target defined by a c:IEPConformanceTarget element in the [MPD catalog document] of a [model package description].

      This term may be abbreviated "IEP". Rules specifying this conformance target use the applicability code "IEP".

   The definition of an [information exchange package] conformance target does not ensure that an [IEP] uses NIEM-defined elements for its information content. That is the function of the [full NIEM IEP] [conformance target], defined as follows:

   [Definition: full NIEM information exchange package]

      An [information exchange package] that satisfies all the validity constraints for its class as defined by a [model package description], and that has an XML document element that is declared in either a NIEM reference or extension schema document.

      This term may be abbreviated "full NIEM IEP". Rules specifying this conformance target use the applicability code "FN-IEP".

3.2.4. Artifact Conformance Targets

   Conformance targets that correspond to artifacts internal to an [MPD] include:

      *  [schema document subset] (rule applicability code: Schema-subset)

      *  [MPD catalog document] (rule applicability code: MPD-catalog)

      *  [XML catalog document] (rule applicability code: XML-catalog)

3.3. Rule Applicability Codes for Conformance Targets

   The table below lists the codes that represent standard [conformance targets] used in this specification and that appear in the applicability attribute for each rule.

   Table 3-1: Rule Applicability Codes

      Conformance Target|Rule Applicability Code

      [model package description]|WF-MPD

      [information exchange package documentation]|IEPD

      [information exchange package]|IEP

      [full NIEM IEP]|FN-IEP

      [schema document subset]|Schema-subset

      [MPD catalog document]|MPD-catalog

      [XML catalog document]|XML-catalog

4. MPD XML Schema Document Artifacts

   [XML schema document] artifacts are the essential content of MPDs because they normatively define and declare [data components]. The purpose of an [MPD] is determined by the [XML schema document] or document set(s) it contains; furthermore, each [ XML schema document] may have a different purpose. The [NIEM Naming and Design Rules 3.0] addresses some schema documents as [conformance targets] including reference schema documents, extension schema documents, and schema document sets. Each conformance target may adhere to a different (though possibly overlapping) set of conformance rules. Consult the [NIEM Naming and Design Rules 3.0] for these rules. NIEM also employs a special technique that relies on [constraint schema document sets] (See Section 4.5, Constraint Schema Document Sets, below).

   The following subsections define each type of NIEM schema document and document set, and identify the types of MPDs that contain them.

4.1. Reference Schema Documents

   This section generally applies to NIEM releases and their associated core supplements, and domain updates. Though not common, it is also valid to use a [reference schema document] or document set within an [IEPD]. The [reference schema document] and [reference schema document set] were defined earlier in Section 2.8, Reference Schema Documents, above.

   A NIEM [reference schema document] is intended to be the authoritative definition schema document for a NIEM target namespace. All NIEM releases, associated core supplements, and domain updates are standalone sets of namespaced reference schema documents. NIEM content governance bodies have reviewed and attempted to harmonize each set to the extent possible by refactoring as needed. This means that most (not necessarily all) types and properties are semantically unique (i.e., multiple versions of semantically identical types or properties do not exist within a set).

   As authoritative definitions, NIEM reference schema document sets satisfy more rigorous documentation requirements. The [NIEM Naming and Design Rules 3.0] requires that each type definition, and element and attribute declaration in a reference schema document contain an xs:annotation element that defines its semantic meaning.

   Typically reference schema documents contain [data components] with the most relaxed cardinality (zero to unbounded). However, this is not an absolute requirement. If necessary, cardinality in reference schema documents may be constrained to model reality. For example, in NIEM 3.0 a nc:Location2DGeospatialCoordinateType contains both a nc:GeographicCoordinateLatitude element and a nc:GeographicCoordinateLongitude element. Each of these elements has cardinality minOccurs="1" and maxOccurs="1". Any other cardinality for these elements has no meaning. On the other hand, one might claim that NIEM should constrain nc:PersonType to a single occurrence of the element nc:PersonBirthDate. Every person has one and only one birth date. Unfortunately, also in reality, criminal persons often present multiple identities with multiple birth dates; and so the capability to represent such is an important data requirement for NIEM.

4.2. Subset Document Schemas

4.2.1. Basic Subset Concepts

   A NIEM schema document subset is a set of XML schema documents that constitutes a reduced set of components derived from a NIEM reference schema document or document set associated with a given numbered release or domain update.

   [Definition: schema document subset]

      An XML schema document set based on a reference schema document set intended to ensure that any [instance XML document] valid to the schema document subset is also valid to the reference schema document set.

   The primary purpose for a schema document subset is to reduce and constrain the scope and size of a full NIEM reference schema document set for use within an [IEPD]. A schema document subset is derived from a reference schema document set (such as a NIEM release) by applying subset operations (See Section 4.2.2, Constructing a Schema Document Subset, below). Also, note that employing a subset of a reference schema document set within an [IEPD] is optional; it is completely valid to reuse NIEM reference schema documents as-is within IEPDs.

   The fundamental rule for a valid NIEM schema document subset is formally stated follows:

Rule 4-1. Fundamental NIEM Subset Rule

   [Rule 4-1] (Schema-subset)

      A schema document subset ($SUBSET) for a given reference schema document set ($REFERENCE) MUST be defined such that for all instance XML documents ($XML), where $XML is valid to $SUBSET, $XML is valid to $REFERENCE.

   A [schema document subset] is composed of [XML schema documents]. A [schema document subset] can essentially be a [reference schema document set] (i.e., a NIEM release) that has been modified by applying subset operations to support business requirements represented in an [IEPD]. A subset derived from a reference schema document set may differ from that reference such that its content has been reduced and/or constrained.

   [Definition: subset schema document]

      An XML schema document that meets all of the following criteria:

         *  It is built from a reference schema document set where one or more reference schema documents have been substituted by corresponding subset schema documents.

         *  It is built from a reference schema document by applying subset operations to the XML schema statements in a reference schema document.

         *  It is explicitly designated as a subset schema document. This is accomplished by declaration in the relevant MPD catalog or by a tool-specific mechanism outside the subset schema document.

         *  It has a target namespace previously defined by a reference schema document. That is, it does not provide original definitions and declarations for schema components, but instead provides an alternate schema representation of components that are defined by a reference schema document.

         *  It does not alter the business semantics of components in its namespace. The reference schema document defines these business semantics.

         *  It is intended to express the limited vocabulary necessary for an [IEPD] and to support XML Schema validation for an [IEPD].

4.2.2. Constructing a Schema Document Subset

   This section is non-normative. Use the subset operations in this section with caution.

   NIEM subset operations are essentially reduction operations that remove or constrain portions of a reference schema document set, thereby building a profile of the set. They do not expand the scope (i.e., relax constraints) or change the semantics of reference schema document set content.

   Because NIEM adopts an optional and over-inclusive data representation strategy, most elements in a NIEM reference schema have zero to unbounded cardinality. So, elements with cardinality minOccurs="0" are optional and may be omitted from a subset schema document if not needed for business reasons. It is also valid to constrain element cardinality within a subset schema document, as long as doing so does not break the subset relationship with the reference schema document set. For example, a reference schema document element with cardinality (minOccurs="0", maxOccurs="unbounded") may be constrained to (0,1) or (1,1) in a subset schema document. However, if a reference schema document element's cardinality is (1,unbounded), it may not be constrained to (0,1) since this breaks the subset relationship. The interval (0,1) is not contained within, and instead, overlaps the interval (1,unbounded).

   The following list describes valid subset operations that are considered non-normative and informative only. In most cases, they can be applied to a schema document set and result in a corresponding [schema document subset]. However, it is possible to apply them in combinations that will break the subset relationship, or even result in invalid schemas. Apply these operations carefully and thoughtfully!

      1.  Remove an XML comment.

      2.  Remove an xs:annotation and its children xs:documentation and xs:appinfo.

      3.  Increase the value of an xs:element/@minOccurs as long as it remains less than or equal to its corresponding @maxOccurs value).

      4.  Decrease the value of an xs:element/@maxOccurs as long as it remains greater than or equal to its corresponding @minOccurs value.

      5.  Remove an xs:element if its @minOccurs="0".

      6.  Remove an xs:complexType or xs:simpleType if not supporting an xs:element or xs:attribute declaration, or another xs:complexType or xs:simpleType definition.

      7.  Remove an xs:attribute with @use="optional" from an xs:complexType.

      8.  Change an xs:attribute/@use="optional" to @use="prohibited".

      9.  Change an xs:attribute/@use="optional" to @use="required".

      10. Remove an xs:element declaration if it is not supporting an element use.

      11. Remove an xs:enumeration from an xs:simpleType as long as it is not the only remaining xs:enumeration.

      12. Remove an element with representation term AugmentationPoint if it is not being used for element substitution.

      13. Add or apply a constraining facet to an xs:simpleType.

      14. Remove an xs:import and its associated schema document if the schema document is not used within the document set.

      15. Change a concrete xs:element declaration to @abstract="true".

      16. Change an xs:element/@nillable="true" to @nillable="false".

      17. Substitute an xs:element/@substitutionGroup member for its associated substitution group head.

      18. Substitute a composition of xs:element/@substitutionGroup members for their associated substitution head (subject to cardinality and unique particle attribution (UPA) constraints [W3C XML Schema Part 1 Structures],  section  "Schema Component Constraint: Unique Particle Attribution"). The composition is an ordered sequence of the @substitutionGroup member elements. Each substitute element may bound its cardinality such that the total cardinality sum is within the bounds of the @substitutionGroup head cardinality. Order and cardinality of the replacement sequence must conform to XML Schema UPA constraints.

      19. Replace a wildcard (subject to cardinality, UPA, and namespace constraints) with a composition, i.e., an ordered sequence of elements. Each element may further bound cardinality within the bounds of the wildcard. Order and cardinality of replacement sequence must conform to XML Schema UPA constraints. The namespace of each element must conform with namespace constraints specified by the wildcard (if any).

4.3. Extension Schema Documents

   [Definition: extension schema document]

      As defined by [NIEM Naming and Design Rules 3.0]:

         An [XML 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 [NIEM Naming and Design Rules 3.0]. An extension schema document MUST conform to all rules of [NIEM Naming and Design Rules 3.0] 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/3.0/#ExtensionSchemaDocument MUST be an extension schema document.

   In general, an [extension schema document] contains components that use or are derived from the components in reference schema documents. It is intended to express additional vocabulary above and beyond the vocabulary available from reference schema documents.

   A developer who determines that NIEM is missing elements required for a given information exchange has several options for providing the missing elements. Using rules and techniques defined in the [NIEM Naming and Design Rules 3.0]:

      *  Extend an existing NIEM [data component] (if possible).

      *  Augment an existing NIEM data type (through NIEM Type Augmentation).

      *  Build a new NIEM-conformant data component.

      *  Employ NIEM adapter types for components from an external standard that does not conform to NIEM.

   A NIEM extension schema document may contain [data components] built from any of the options above. Employment of extension schema documents in an [IEPD] is entirely optional.

   Multiple extension schema documents are allowed in a single [IEPD]. Developers will likely want to reuse many of their extension schema documents in other IEPDs. Therefore, the best practice for extension is to group all [data components] designed to be reused into one extension schema document or document set, and group IEPD-specific [data components] into another. Then the reusable extension components can be more easily redeployed in other IEPDs as needed.

   Extension schema documents generally contain new [data component] declarations that may (though not necessarily) be derived from or reference existing NIEM [data components]. This being the case, reference schema documents do not exist for new [data components] found within extension schema documents. Therefore, extension schema documents must satisfy the more rigorous documentation requirements of reference schema documents. Per the [NIEM Naming and Design Rules 3.0], the definition or declaration of each new [data component] in an extension schema document must include an xs:annotation element that provides its semantics and NIEM-specific relationships.

4.4. External Schema Documents

   [Definition: external schema document]

      As defined by [NIEM Naming and Design Rules 3.0]:

         Any [XML schema document] that is not one of:

            *  a [reference schema document],

            *  an [extension schema document], or

            *  an [XML schema document] that has the structures namespace as its target namespace.

   All [MPD] classes may contain external schema documents that do not conform to NIEM. Data components declared and defined in external schema documents require NIEM external adapter types to identify the fact they do not conform to NIEM.

   [Definition: external adapter type]

      As defined by [NIEM Naming and Design Rules 3.0]:

         A NIEM-conformant type that adapts external components for use within NIEM. An external adapter type creates a new class of object that embodies a single concept composed of external components. External adapter types are defined in NIEM-conformant schemas.

   Refer to the [NIEM Naming and Design Rules 3.0] for details about external schema documents, external adapter types, and the rules defining their use.

4.5. Constraint Schema Document Sets

   [Definition: constraint schema document set]

      A set of related constraint schema documents that work together; for example, a constraint schema document set could be built by adding constraints to a schema document subset.

   A [constraint schema document set] is an [XML schema document] set that is used to express business rules for a class of [instance XML documents]; it is not intended to provide definitions for the semantics of the individual components it contains. Instead, a constraint schema document set uses the XML Schema Definition Language to add constraints to components defined or declared by other schema documents, usually a [schema document subset]; but they can be applied to [extension schema documents] as well.

   A [constraint schema document set] validates additional constraints imposed on an [instance XML document] only after it is known to be NIEM-conformant (i.e., has been validated with a [reference schema document set], or [schema document subset], and applicable [extension schema documents]).

   To use a [constraint schema document set] to tighten constraints on an IEP, a two-pass validation technique is employed. In the first pass, an IEP is validated against the schema document subset and extension schema documents. This pass ensures that IEP semantics and structure conform to the NIEM model and [NIEM Naming and Design Rules 3.0]. In the second pass, an IEP is checked against a constraint schema document set, which may contain constrained versions of the [subset schema documents] and [extension schema documents]. This pass ensures that the IEP also satisfies the additional constraints (i.e., business rules that the first pass was unable to validate). A constraint schema document set need not validate constraints that are applied by other schema documents.

   Constraint schema document sets are generally useful when it is necessary to impose restrictions that are more complex than cardinality. If only cardinality restrictions are needed, then it is easier and more efficient to set these directly in the subset schema documents and avoid the use of a constraint schema document set. Otherwise, a constraint schema document set may be necessary.

   Use of a constraint schema document set is one option for tightening constraints on NIEM IEPs beyond what NIEM itself provides. This particular technique uses the XML Schema Definition Language [W3C XML Schema Part 2 Datatypes], [W3C XML Schema Part 1 Structures]. NIEM also allows other methods that do not use XML Schema. For example, the use of [ISO Schematron] is the preferred method for applying business rules. However, other constraint or business rule methods are also acceptable. That said, at this time there are no normative rules for how these business rule techniques should be employed in NIEM IEPDs. Therefore, if other techniques are used, it is a developer responsibility to incorporate appropriate artifacts and clear documentation.

   Note that one disadvantage to use of constraint schema document sets is that they do not provide clear visibility or explanation of the constraints they enforce; nor do they provide clear validation failure messages. On the other hand, a standard business rule language such as [ISO Schematron] provides facilities for better understanding of the business rules, their intent, and error handling of failures.

   A common practice for creating an [IEPD] constraint schema document set is to start with a valid NIEM schema document subset and modify it to further restrict the class of instance XML documents (IEPs) that will validate with this constraint schema set. However, an extension schema document can also be used to derive a constraint schema document. Using this technique, the namespace of that schema document would reuse the target namespace of the schema document from which it is derived.

   There is no restriction on the number of constraint schema document sets (and validation passes) that an [IEPD] can employ. As in other advanced situations, developers must clearly document their intentions for and use of multiple constraint schema document sets.

   In general, constraint schema documents in a [constraint schema document set] have far fewer requirements than other classes of NIEM schema documents. Since they work in tandem with NIEM normative schema documents, these schema documents are allowed to use the XML Schema Definition language in any way necessary to express business rules. This means that to constrain instance XML documents, these schema document can employ XML Schema constructs that are not allowed in NIEM conformant schema documents.

5. MPD Documentation Artifacts

   XML schema documents (and the schemas that result from them) are the essence of a NIEM [MPD]. However, a variety of documentation files may be incorporated into a NIEM [MPD]. One particular documentation file is required in every MPD: mpd-catalog.xml, the MPD catalog document. This file contains basic metadata, relationship and lineage data, [conformance target] specifications, and validation information.

   A [readme artifact] (formerly known as a master document) is mandatory for IEPDs. IEPDs are often built by different developers, and may be registered into a repository for reuse by many other users, developers, and implementers; therefore, a minimal form of documentation is absolutely necessary. An [IEPD] readme file is the primary source and starting point for human readable documentation, and should reference (and describe) any other separate documentation artifacts. This requirement ensures that baseline documentation is consistently rooted in a clearly visible artifact within each [MPD].

   The following subsections address these documentation artifacts and the concepts, metadata, and content each supports.

5.1. NIEM MPD Catalog

   [Definition: MPD catalog document]

      An [instance XML document] that:

         *  conforms to all the rules in this specification for the conformance target [MPD catalog document] (i.e., applicability code "MPD-catalog"), and

         *  contains metadata describing:

               *  MPD unique identification

               *  [Conformance targets]

               *  Basic characteristics and properties

               *  Key artifacts and directory structure

               *  Relationships to other MPDs and their artifacts

      This term may be abbreviated "MPD-catalog". Rules specifying this conformance target use the applicability code "MPD-catalog".

   Each [MPD class] may have somewhat different catalog requirements. The catalog metadata are formally defined by the XML Schema document in Appendix A, MPD Catalog XML Schema Document, below. MPD catalog metadata are designed to be the minimal needed to facilitate human understanding, tool support, and machine processing. The metadata can support a number of [MPD] uses and functions including (but not limited to):

      *  Identification of key artifacts

      *  Generation of a hyperlinked content display using XSLT

      *  Browsing and understanding of artifacts and their content

      *  Automatic registration into a registry/repository

      *  Search, discovery, retrieval of MPDs (through metadata and relationships)

      *  Reuse of MPDs and their artifacts

      *  Tracing and analysis of MPD lineage

      *  General conformance and validation of the [MPD] itself

      *  Definition, identification, and validation of IEP conformance targets

Rule 5-1. MPD Has an mpd-catalog.xml in its Root Directory

   [Rule 5-1] (WF-MPD)

      Within its [root directory], an [MPD] MUST contain an [MPD catalog document] artifact with name mpd-catalog.xml.

Rule 5-2. MPD Catalog Document Valid to mpd-catalog-3.0.xsd

   [Rule 5-2] (MPD-catalog)

      An [MPD catalog document] MUST be valid to mpd-catalog-3.0.xsd Appendix A, MPD Catalog XML Schema Document.

   This rule requires validation with mpd-catalog-3.0.xsd, which also imports a NIEM schema subset. So, validation of the [MPD catalog document] must be done in the context of the catalog schema document, its associated NIEM subset, and mpd-catalog.xml. This does not require the [MPD] to contain copies of the catalog schema document or the schema subset (since these are standard for all MPDs). However, a validation tool must have access to all three XML documents.

   The XML schema documents required to validate an [MPD catalog document] are available in the [NIEM MPD Toolkit]. Note that validators often require references to schemas and their imports. This may be done through a command line instruction or by adding a schemaLocation attribute to xs:import statements.

5.1.1. MPD Catalog as a Table of Contents

   One function of the MPD catalog is to serve as a table of contents that identifies, locates, and classifies key artifacts and artifact sets. For that purpose, Appendix A, MPD Catalog XML Schema Document, below, provides a number of classifier elements for most common artifacts and artifact sets in MPDs. For other less common or generic artifacts two general classifiers exist: c:Documentation and c:ApplicationInfo. These elements loosely correspond to the meaning of the XML Schema xs:annotation child elements, xs:documentation and xs:appinfo. General visual, audio, and textual explanatory documentation should be classified as c:Documentation, while tool-specific artifacts (such as imports, exports, executables, etc.) should be classified as c:ApplicationInfo.

   The classifier elements are designed to identify, categorize, and describe any artifacts and artifact sets (including its [path name], dependencies, and lineage). Employing XSLT, mpd-catalog.xml can be transformed into an index.html artifact that displays a hyperlinked MPD table of contents and metadata summary in a browser.

   In general, only an [IEPD] would contain c:Documentation and c:ApplicationInfo artifacts. So, for an [IEPD], a best practice is to use the readme artifact (i.e., the [readme artifact] required in the [MPD root directory]) to reference c:Documentation and c:ApplicationInfo artifacts whether or not they have been classified in the MPD catalog.

   An IEPD's MPD catalog is not required to record all its artifacts. The [IEPD] author decides which artifacts (both files and sets) are important enough to explicitly include in the MPD catalog. The author may choose to classify all, some, or none in the catalog.

   The MPD catalog provides a supplement or an alternative to organizing [MPD] artifacts and sets with a standard file directory. An author can use it to identify, classify, and describe particular artifacts or sets, instead of having to do so with only file names and directory structure. An author can also employ the guidance in Appendix E, Guidance for IEPD Directories (non-normative), below.

5.1.2. Extending an MPD Catalog

   An MPD catalog may be extended to accommodate new or additional metadata, artifact classifiers, or validity constraints that are not already defined in Appendix A, MPD Catalog XML Schema Document, below.

   To extend the MPD catalog, an [MPD] author must provide both an XML catalog extension document (XML) and one or more MPD extension schema documents (XSD). The XML catalog extension identifies that one or more MPD catalog extensions are present, and resolves their namespaces to local URIs. The MPD catalog extension is a schema that defines and declares the new [data components] for metadata, classifiers, and/or constraints. Both general [NIEM Conformance 3.0] and specific [NIEM Naming and Design Rules 3.0] conformance rules apply to these components. The XML catalog extension document must reside in the [MPD root directory]. The MPD extension schema documents may bear any file name and reside anywhere in the [MPD]. This is because the XML catalog is expected to [resolve] all local URIs. MPD processing tools are expected to look for and recognize the XML catalog (that identifies MPD catalog extensions exist) by its file name.

   The following rules specify the requirements for an MPD catalog extension XML catalog document:

Rule 5-3. MPD Catalog Extension XML Catalog Document in Root Directory

   [Rule 5-3] (MPD-catalog)

      An MPD catalog extension XML catalog document MUST reside in the same relative directory as the mpd-catalog.xml artifact (normally in the [MPD root directory])

Rule 5-4. MPD Catalog Extension XML Catalog Document Name Is mpd-catalog-extension-xml-catalog.xml

   [Rule 5-4] (MPD-catalog)

      An MPD catalog extension XML catalog document MUST bear the file name (and type) mpd-catalog-extension-xml-catalog.xml.

Rule 5-5. MPD Catalog Extension XML Catalog Document Resolves Namespaces to URIs

   [Rule 5-5] (MPD-catalog)

      An MPD catalog extension XML catalog document MUST [resolve] all MPD catalog schema extension document namespaces to the correct corresponding local URIs in the MPD.

   So, when a processor identifies a file named mpd-catalog-extension-xml-catalog.xml in the [MPD root directory], it can assume that it contains references to one or more MPD catalog extension schema documents that adhere to the following rules:

Rule 5-6. MPD Catalog Extension Schema Document Conforms to NDR Extension Rules

   [Rule 5-6] (MPD-catalog)

      An MPD catalog extension schema document MUST conform to the [NIEM Naming and Design Rules 3.0] extension schema conformance target rules.

Rule 5-7. MPD Catalog Schema and Its Extensions Conform to NDR Schema Set Rules

   [Rule 5-7] (MPD-catalog)

      Within an MPD, the schema set formed by mpd-catalog-3.0.xsd and all MPD catalog extension schema documents MUST conform to the [NIEM Naming and Design Rules 3.0] schema set conformance target rules.

   Whether extending an MPD catalog with new metadata elements, artifact classifier elements, or validity constraint elements, Appendix A, MPD Catalog XML Schema Document, below, provides an abstract element as a substitution group head in each case. The user simply derives a new type (through extension or restriction), or reuses an existing type, then declares a new element (of that type), and identifies it with the appropriate substitution group. Whenever possible, the user should reuse types, elements, and attributes that are already defined/declared within the Appendix A, MPD Catalog XML Schema Document, below.

   If an MPD catalog schema document extension uses NIEM [data components] that are not already contained in the NIEM core subset provided with [NIEM MPD Toolkit], then the additional components must be additive. In other words:

Rule 5-8. MPD Schema Document Extension Support Schemas Are Supersets of Spec Subsets

   [Rule 5-8] (MPD-catalog)

      Subset schema documents provided to support an MPD schema document extension MUST be a superset of the subset schema documents provided with this specification to support the MPD catalog schema document.

5.2. Metadata Concepts

   The MPD catalog also contains both required and optional metadata for the [MPD] and its artifacts and artifact sets. The following subsections specify the syntax, formats, and semantics for that metadata.

5.2.1. MPD Name Syntax (c:mpdName)

   An MPD's official name is the value of the c:mpdName attribute owned by the c:MPD element in the MPD's catalog document. This value is constrained by the regular expression pattern on c:mpdName within the MPD catalog schema Appendix A, MPD Catalog XML Schema Document, below:

      [A-Za-z]([-_ ]?[A-Za-z0-9]+)*

   The regular expression above indicates that an MPD name:

      *  Begins with an alpha character (upper or lower case).

      *  Ends with an alphanumeric character (upper or lower case).

      *  May contain alphanumeric characters.

      *  May contain single spaces, single dashes, and single underscores as separators.

   [IEPD] author's often reuse the official [MPD] name in metadata within the file name. Note that c:mpdName is of xs:token type and allows single spaces and upper case alpha characters. That said, be sure to consider differences in operating system or file system treatment of spaces and character case within file and directory names. (See Rule 7-5, IEPD ZIP file Name Syntax.

   c:mpdName is not the same thing as the name of the file containing the MPD, described in Section 7.2, IEPD File Name Syntax, below.

5.2.2. MPD Class (c:mpdClassURIList)

   An [MPD class] is a [conformance target identifier] to which the given [MPD] claims to conform. The MPD catalog c:mpdClassURIList attribute declares a list of [conformance target identifiers], identifying the [conformance targets] to which the MPD claims to conform. The following rule establishes the [class] of an [MPD]:

Rule 5-9. MPD Class Determined by Conformance Target Identifier in c:mpdClassURIList

   [Rule 5-9] (WF-MPD)

      An MPD MUST have an [MPD class] of a [conformance target identifier] if and only if that [conformance target identifier] appears in the c:mpdClassURIList attribute within its [MPD catalog document].

   It should be clear that an [MPD] that is an [IEPD] should have a value for its c:mpdClassURIList attribute that contains both [conformance target identifiers] above. In the future, additional conformance target identifiers will be assigned by other appropriate NIEM specifications that specialize MPDs (for example, releases, domain updates, etc.).

   The c:mpdClassURIList attribute is an XML list type that may declare that an MPD conforms to multiple conformance targets. An MPD developer can establish a new MPD [conformance target] identifier in addition to those provided by this and other NIEM specifications. The identifier represents the new conformance target which should be associated with one or more rules or constraints to which an MPD must conform if it is assigned that identifier.

   An [IEPD] authoring organization might use another classification system for its IEPDs. For example, the organization ABC might establish the [conformance target identifier] http://example.org/niem-iepd/1.0/#abc-org to indicate its IEPDs also conform to its own stricter set of [IEPD] conformance rules. Thus, an MPD catalog document for its published IEPDs would contain the c:mpdClassURIList component shown in Figure 5-1, MPD catalog c:mpdClassURIList attribute for organization ABC., below, indicating conformance to three [conformance targets].

   Figure 5-1: MPD catalog c:mpdClassURIList attribute for organization ABC.

      
      	c:mpdClassURIList=
      	     "http://reference.niem.gov/niem/specification/model-package-description/3.0/#MPD 
      	      http://reference.niem.gov/niem/specification/model-package-description/3.0/#IEPD 
      	      http://example.org/niem-iepd/1.0/#abc-org"
      		

5.2.3. MPD Version Numbering Scheme (c:mpdVersionID)

   Published MPDs may be periodically revised and updated; therefore, versioning is required to clearly indicate changes have occurred. In order to maintain some consistency while allowing reasonable flexibility to authors, this specification establishes a simple version numbering scheme that is consistent with most common practices. This is the same version numbering scheme that is used for NIEM releases.

   An MPD version number is the value of the c:mpdVersionID attribute owned by the c:MPD element within its [MPD catalog document]. A consistent version number syntax is enforced by the MPD catalog schema in Appendix A, MPD Catalog XML Schema Document, below. The syntax rule is as follows:

Rule 5-10. MPD Version Number Syntax

   [Rule 5-10] (WF-MPD)

      An MPD MUST be assigned a version number that adheres to the regular expression:

      	version ::= digit+ ('.' digit+)* (status digit+)?
      	Where:	
      		digit   ::= [0-9]
      		status  ::= 'alpha' | 'beta' | 'rc' | 'rev'

      The meaning of the status values are as follows:

         *  alpha indicates early development; changing significantly.

         *  beta indicates late development; but changing or incomplete.

         *  rc indicates release candidate; complete but not approved as operational.

         *  rev indicates very minor revision that does not impact schema validation.

   The regular expression notation used above is from [W3C XML 1.0] #sec-notation.

   Note that the absence of a status string in the version number indicates that the version has been baselined and published.

   The following examples are valid MPD version numbers:

      *  1

      *  1.2

      *  1.3.1.0

      *  1.2alpha13

      *  199.88.15rev6

   There are two implications in Rule 5-10, MPD Version Number Syntax. The first is that in some cases this version scheme implies and confirms a chronology of releases. For example, a given product labeled version 2.3 must have been released before the same product labeled 2.3.1. Therefore, version 2.3.1 is more current than version 2.3.

   However, this is a multi-series version scheme, and chronological relationships exist only within a given series. So, for example, nothing can be said about a chronological relationship between versions 2.2.4 and 2.3. This is because version 2.2.4 is in a different series (i.e., 2.2) and could actually have been released after 2.3. Figure 5-2, Example versioning system, below, illustrates a system of versions that uses the numbering scheme of Rule 5-10, MPD Version Number Syntax.

   Figure 5-2: Example versioning system

      Images are omitted from this edition.

   Figure 5-2, Example versioning system, above, illustrates eight different version series. Within this illustration these are the only sequences that have chronological relationships that can be identified through version numbers.

      *  Series 2 is {2.2, 2.3, 2.4}

      *  Series 3 is {3.0, 3.1, 3.2}

      *  Series 2.2 is {2.2, 2.2.1, 2.2.2, 2.2.3, 2.2.4}

      *  Series 2.3 is {2.3, 2.3.1}

      *  Series 2.4 is {2.4, 2.4.1}

      *  Series 3.0 is {3.0, 3.0.1, 3.0.2}

      *  Series 3.1 is {3.1, 3.1.1}

      *  Series 3.2 is {3.2, 3.2.1, 3.2.2}

   The second implication of Rule 5-10, MPD Version Number Syntax is that pre-releases are easily identified by the strings alpha, beta, and rc. These strings are simple visible indicators of MPD status or stage of development.

   This specification places no further restrictions or meaning (implied or otherwise) on a version number. Authors have the option to use integers between dots to indicate degree of compatibility or other relationships between versions as needed. For example, for a given [MPD], the author may declare that if an instance validates to version 4.2.3, then it will also validate to version 4.2. Such a claim is acceptable. However, this specification does not imply any such relationships. Any meaning assigned to version sequence by an authoritative source should be unambiguously documented within the [MPD].

   MPD version numbers within a version series do NOT imply compatibility between versions. Compatibility between or among MPD versions MUST be explicitly stated in documentation.

   Note that an author who updates an existing [MPD] to a new version may choose the version number based on its previous version number or not, as long as it follows the version number syntax. 

   Version number syntax applies to MPDs only; there is no requirement to apply this syntax to artifact versioning.

5.2.4. URI Schemes

   All MPDs use Uniform Resource Identifiers (URIs) to identify artifacts and other resources. Several kinds of URIs are employed by MPDs to reference other MPDs, MPD artifacts (internally and externally), conformance targets, documents, and other resources. For each type of URI used in an MPD catalog document, this section describes its purpose, options, and syntax based on [RFC 3986 URI].

   The following definitions will be useful to understanding MPD rules defined in later subsections that involve various kinds of URIs.

   [Definition: path name]

      A general form of the name of a file or directory that specifies a unique location in a file system. A path name points to a file system location by following the directory tree hierarchy expressed in a string of characters in which path components, separated by a delimiting character, represent each subdirectory. If a path name terminates in a file name, then it specifies the location of that file.

   [Definition: resolve URI]

      A function (or action) that takes a URI string of the form xs:anyURI and returns the resource it identifies. If the URI is local (i.e., within an [MPD]) and the resource does not exist, then this function fails. If a URI is remote or of unknown location (e.g., a URN), then this function (or action) may require human assistance to determine if a resource associated with the URI exists (pass) or not (fail).

5.2.4.1. MPD URI Scheme (c:mpdURI)

   To facilitate MPD sharing and reuse, the assignment of a URI (Uniform Resource Identifier) to an MPD is essential. This is enforced by the MPD catalog schema document Appendix A, MPD Catalog XML Schema Document, below. It is also important to ensure that an MPD URI is absolute.

Rule 5-11. MPD URI Is Absolute

   [Rule 5-11] (WF-MPD)

      In an MPD catalog document, the value of a c:mpdURI attribute of type xs:anyURI MUST match the production <absolute-URI> as defined by [RFC 3986 URI],  section 4.3, "Absolute URI".

   This rule implies that a URI assigned to an [MPD] must be valid. Furthermore, the entity (person or organization) assigning the MPD URI either (1) is the registrant of the domain name or namespace identifier, or (2) has authority from the registrant to assign this URI.

   Examples of valid MPD URIs:

      *  http://example.gov/niem-iepd/prescription-monitoring-info-exchange/3.0/

      *  http://example.gov/niem-iepd/pmix/3.0/

      *  http://release.niem.gov/niem/niem-core/3.0/

      *  http://niem.gov/niem/domains/cyfs/2.1/1

   This specification does not mandate that basic MPD catalog metadata be designed into an MPD URI. However, including such can obviously provide convenient visual recognition. That said, an author should ensure any metadata embedded in the URI accurately reflect the MPD catalog metadata (in particular, the values of c:mpdURI, c:mpdName, c:mpdVersionID, and c:mpdClassURIList defined in the MPD catalog document).

5.2.4.2. URI Scheme for MPD Artifacts (c:externalURI)

   Artifacts in other MPDs can be referenced from within an [MPD] to identify equivalence (signify reuse, one aspect of lineage). To support this concept, the following MPD URI rules are necessary:

Rule 5-12. MPD URI Supports Fragment

   [Rule 5-12] (WF-MPD)

      A valid MPD URI MUST support the inclusion of a fragment identifier (as a suffix) [RFC 3986 URI].

   This rule ensures that an [MPD] can always uniquely identify and refer to each artifact within another MPD. This MPD specification follows [RFC 3986 URI] which forbids a URI to contain more than a single fragment identifier. To construct an MPD artifact URI, add a fragment (that locally identifies the artifact) to an MPD URI, and therefore, an MPD URI cannot already contain a fragment.

Rule 5-13. MPD URI Has No Fragment

   [Rule 5-13] (WF-MPD)

      A valid MPD URI MUST NOT contain a fragment identifier [RFC 3986 URI].

   Rationale: If a URI for an [MPD] (do NOT confuse this with a URI for an MPD artifact) already contains a fragment identifier, then that URI cannot be employed as an MPD artifact URI, because [RFC 3986 URI] only allows a single fragment identifier.

   By the following rule, each file artifact or artifact set is uniquely identified by its [path name] relative to the [MPD root directory].

Rule 5-14. MPD Artifact URI Syntax

   [Rule 5-14] (WF-MPD)

      Within an [MPD] a URI reference to an artifact in another external MPD (i.e., an MPD artifact URI) is the concatenation of:

         *  The URI of the [MPD] that contains the artifact.

         *  A pound-sign character ("#" -- also known as a hashtag character).

         *  An identifier that is the artifact's locally unique [path name] relative to the [MPD root directory].

   An artifact set has a locally unique [path name]. An artifact has a path name that terminates with its file name which is unique to the directory it resides in.

   The following are examples of valid MPD artifact URIs:

      *  http://example.gov/niem-iepd/pmix/3.0/#subset/niem-core.xsd (a file artifact)

      *  http://example.gov/niem-iepd/pmix/3.0beta2/#extension/ext-1.1.xsd (a file artifact)

      *  http://example.gov/niem-iepd/pmix/3.0/#application-info (a set artifact)

      *  http://example.gov/niem-iepd/pmix/3.0/#iep-sample/query (a set artifact)

   Since MPD URIs require the support of fragment identifiers (by Rule 5-12, MPD URI Supports Fragment), it does not appear that the "urn" URI scheme may be used as an MPD URI. Fragments use the "#" character, and the specification for the "urn" scheme ([RFC 2141 URN Syntax]) indicates that they are not valid in URNs, when it states:

      RFC 1630 reserves the characters "/", "?", and "#" for particular purposes. The URN-WG has not yet debated the applicability and precise semantics of those purposes as applied to URNs. Therefore, these characters are RESERVED for future developments.

   Artifact URIs are used as values for the c:externalURI attribute in the MPD catalog XML document to declare equivalence relationships between artifacts (See Appendix A, MPD Catalog XML Schema Document, below). A simple scenario follows. Consider two different IEPDs with the following URIs:

      1. http://example.gov/niem-iepd/pmix/3.0/

      2. http://www.abc.org/niem-iepd/order/2.1.2rev3/

   The author of [IEPD] (2) has decided to reuse the base-xsd/extension/req1.xsd artifact in [IEPD] (1) as-is. He/she can optionally create an MPD catalog c:ExtensionSchemaDocument entry for this artifact (assuming it is an extension schema document), and add the attribute:

      c:externalURI="http://example.org/niem-iepd/pmix/3.0/#base-xsd/extension/req1.xsd"

   Additional c:externalURI attributes may be added to this entry if the author knows of other uses of this same artifact in other MPDs and wishes to acknowledge them.

   A URI does not have the same meaning as namespace. NIEM namespaces cannot be used as MPD artifact URIs. Recall that the target namespace used in a subset schema document derived from a NIEM release schema document is identical to the target namespace of that release schema document. Furthermore, an [IEPD] may contain multiple subsets. NIEM namespaces are not necessarily unique to an artifact within an [MPD]. Later, Section 5.5, XML Catalogs, below, will describe the use of [XML Catalogs 1.1] to correlate namespaces to local URIs in order to [resolve] them to local resources.

   The value of c:externalURI is an identifier for a remote resource that is not necessarily accessible online. For this reason, even though such URIs should be correct (i.e. a resource with that URI should exist), their verification is not within the scope of this specification.

5.2.4.3. URI Scheme for Local MPD Artifacts (c:pathURI)

   An MPD uses the file directory system of path names and file names to identify local artifacts and artifact sets. All local URIs are relative to the location of the [MPD catalog document], and therefore, they are also relative to the [MPD root directory] since the MPD catalog document resides in the MPD root directory.

   In general, every value of attribute c:pathURI in an MPD catalog document will be a relative [path name] to a directory (i.e., an artifact set), or to a file (i.e., an artifact). The following are typical examples of each:

      Artifact Set: c:pathURI="base-xsd/niem/niem-core/3.0"

      Artifact:      c:pathURI="base-xsd/niem/niem-core/3.0/niem-core.xsd"

   Note that per Table Table 5-1, Summary of "RFC 3986 URI: Generic Syntax", below, and Table Table 5-2, Summary of MPD URI attributes, below, a local URI may contain an optional fragment. Although c:pathURI has no use for a URI with a fragment, MPD documentation artifacts could reference a subpart within a local artifact by using a relative URI with a fragment.

   Despite its simplicity, c:pathURI comes with over a dozen rules that help to define a [model package description]. These rules ensure that every c:pathURI attribute value in a well-formed [MPD] resolves to a correct local resource:

Rule 5-15. c:pathURI Resolves to a Resource

   [Rule 5-15] (WF-MPD)

      Within an [MPD catalog document], the value of a c:pathURI attribute MUST [resolve] to a resource.

Rule 5-16. c:pathURI for c:XMLCatalog

   [Rule 5-16] (WF-MPD)

      Within an [MPD catalog document], the value of a c:pathURI attribute owned by a c:XMLCatalog element MUST [resolve] to an [XML catalog document].

Rule 5-17. c:pathURI for c:MPDChangeLog

   [Rule 5-17] (WF-MPD)

      Within an [MPD catalog document], the value of a c:pathURI attribute owned by a c:MPDChangeLog element MUST [resolve] to a [change log].

Rule 5-18. c:pathURI for c:ReadMe

   [Rule 5-18] (WF-MPD)

      Within an [MPD catalog document], the value of a c:pathURI attribute owned by a c:ReadMe element MUST [resolve] to a [readme artifact].

Rule 5-19. c:pathURI for c:IEPSampleXMLDocument

   [Rule 5-19] (WF-MPD)

      Within an [MPD catalog document], the value of a c:pathURI attribute owned by a c:IEPSampleXMLDocument element MUST [resolve] to an [XML document].

Rule 5-20. c:pathURI for c:BusinessRulesArtifact

   [Rule 5-20] (WF-MPD)

      Within an [MPD catalog document], the value of a c:pathURI attribute owned by a c:BusinessRulesArtifact element MUST [resolve] to a [business rule schema] or [business rules] artifact.

Rule 5-21. c:pathURI for c:XMLSchemaDocument

   [Rule 5-21] (WF-MPD)

      Within an [MPD catalog document], the value of a c:pathURI attribute owned by a c:XMLSchemaDocument element MUST [resolve] to an [XML schema document].

Rule 5-22. c:pathURI for c:ExternalSchemaDocument

   [Rule 5-22] (WF-MPD)

      Within an [MPD catalog document], the value of a c:pathURI attribute owned by a c:ExternalSchemaDocument element MUST [resolve] to an [XML schema document].

Rule 5-23. c:pathURI for c:ReferenceSchemaDocument

   [Rule 5-23] (WF-MPD)

      Within an [MPD catalog document], the value of a c:pathURI attribute owned by a c:ReferenceSchemaDocument element MUST [resolve] to a NIEM [reference schema document].

Rule 5-24. c:pathURI for c:ExtensionSchemaDocument

   [Rule 5-24] (WF-MPD)

      Within an [MPD catalog document], the value of a c:pathURI attribute owned by a c:ExtensionSchemaDocument element MUST [resolve] to a NIEM [extension schema document].

Rule 5-25. c:pathURI for c:SubsetSchemaDocument

   [Rule 5-25] (WF-MPD)

      Within an [MPD catalog document], the value of a c:pathURI attribute owned by a c:SubsetSchemaDocument element MUST [resolve] to a NIEM [subset schema document].

   Note: It is not possible for a Schematron rule to verify that the URI resolves to a NIEM subset schema document, only that it is a schema document.

Rule 5-26. c:pathURI for c:Wantlist

   [Rule 5-26] (WF-MPD)

      Within an [MPD catalog document], the value of a c:pathURI attribute owned by a c:Wantlist element MUST [resolve] to a [NIEM wantlist] XML document.

Rule 5-27. c:pathURI for c:SchematronSchema

   [Rule 5-27] (WF-MPD)

      Within an [MPD catalog document], the value of a c:pathURI attribute owned by a c:SchematronSchema element MUST [resolve] to a [Schematron schema].

Rule 5-28. c:pathURI for c:RelaxNGSchema

   [Rule 5-28] (WF-MPD)

      Within an [MPD catalog document], the value of a c:pathURI attribute owned by a c:RelaxNGSchema element MUST [resolve] to a RelaxNG schema.

Rule 5-29. c:pathURI for c:SchemaDocumentSet

   [Rule 5-29] (WF-MPD)

      Within an [MPD catalog document], the value of a c:pathURI attribute owned by a c:SchemaDocumentSet element MUST [resolve] to an [XML schema document] set.

Rule 5-30. c:pathURI for c:ConstraintSchemaDocumentSet

   [Rule 5-30] (WF-MPD)

      Within an [MPD catalog document], the value of a c:pathURI attribute owned by a c:ConstraintSchemaDocumentSet element MUST [resolve] to a NIEM [XML schema document] set.

Rule 5-31. 

   [Rule 5-31] (WF-MPD)

      Any [XML schema document] set whose c:pathURI attribute resolves to a [constraint schema document set] MUST be interpreted to be a [constraint schema document set].

5.2.4.4. MPD Relationships and Lineage (c:resourceURI)

   An important business requirement is transparency of MPD lineage. Data lineage is also referred to as data provenance, how the data was derived and where it came from. There are two basic views of data provenance: (1) as data annotations; and (2) as a graph of data relationships [Principles of Data Integration], Chapter 14 "Data Provenance".

   The MPD Specification adapts the latter view of data provenance to enable a simple framework for recording MPD lineage within an MPD catalog. The URI scheme for MPDs and their artifacts and sets enables a graph of relationships. An [MPD] may internally identify and record relationships to other MPDs, including families, versions, adaptations, specializations, generalizations, etc.

   The next few paragraphs require understanding of URIs for MPDs and MPD artifacts. See Section 5.2.4.1, MPD URI Scheme (c:mpdURI), above, and Section 5.2.4.2, URI Scheme for MPD Artifacts (c:externalURI), above.

   The MPD catalog provides a c:Relationship element with two attributes (c:resourceURI and c:relationshipCode) and an optional element (nc:DescriptionText) to identify ancestry and other relationships to other MPDs. There are many ways that one [MPD] may relate to another. This makes it difficult to specify a fixed set of values that can objectively define an exact relationship between a pair of MPDs. Therefore, the optional nc:DescriptionText element is provided to further explain the nature of any of the c:relationshipCode values. The set is: {version_of, specializes, generalizes, deprecates, supersedes, adapts, conforms_to, updates}. In some cases, the value of c:relationshipCode may be generic enough to require a more detailed explanation in nc:DescriptionText (for example, if its value is adapts).

   As was described in Section 5.2.4.2, URI Scheme for MPD Artifacts (c:externalURI), above, the MPD catalog also enables an author to record more fine-grained ancestry between MPDs using the c:externalURI attribute. This attribute records an explicit equivalence relationship between artifacts reused across MPDs.

   Note that a c:resourceURI attribute is used to identify a remote resource that is only related to the MPD whose catalog declares it. The resource is not required for validation. Therefore, the [MPD] is not required to contain this resource. As in the case of c:externalURI, the value of a c:resourceURI should be correct (i.e., a resource with that URI should exist). However, in this case, existence verification is considered outside the scope of this specification.

5.2.4.5. Resolving an MPD URI with a Fragment

Rule 5-32. Resolve MPD URI with Fragment

   [Rule 5-32] (WF-MPD)

      Given an absolute MPD URI [RFC 3986 URI],  section 4.3, "Absolute URI" with a fragment, resolve this URI as follows:

         1. Resolve the base URI (per [RFC 3986 URI]) to retrieve the resource MPD. If the resource MPD does not exist, then fail (existence error).

         2. Apply the fragment (without "#") to the MPD resource:

               1. Locate a structures:id attribute value that matches the fragment string. If more than one exist, then fail (ambiguity error). If none exists, then continue.

               2. Locate a [path name] (for a directory or file) that matches the fragment string. If more than one exist, then fail (ambiguity error). If none exists, then fail (existence error).

         3. Return the element, directory, or file found.

   In the presence of NIEM [reference elements], URI resolution may require an additional step to account for indirect references. Be sure to review Section 5.2.4.6, URI Resolution Involving Reference Elements, below, if this case applies.

5.2.4.6. URI Resolution Involving Reference Elements

   A NIEM element can indirectly reference its content rather than carry or encapsulate it. A NIEM element with simple content derived from type xs:anyURI may appear in an instance XML document as a reference element, in which case, rather than locally containing a URI as simple content, it will instead refer to another element that contains a URI. Under some circumstances, this might impact URI resolution described in Rule 5-32, Resolve MPD URI with Fragment.

   [NIEM Naming and Design Rules 3.0],  section 12.3, "Reference Elements" defines a NIEM [reference element] as follows:

   [Definition: reference element]

      A reference element is an element information item that has an attribute structures:ref. A reference element refers to its value by reference, instead of carrying it as content.

   Thus, the structures:ref attribute value refers to another element that carries the content (for both elements) and owns a structures:id attribute with a value equal to that of structures:ref.

   The [MPD catalog document] reuses NIEM Core and so it conforms to NIEM. Therefore, one or more NIEM [reference elements] from various locations may refer to a single content bearing instance of the same element (with a unique structures:id). The definition of [resolve URI] and the URI-related rules in this section assume content bearing elements. If a URI resolution rule applies to an element in [reference element] form, then URI resolution will be applied at the site of the content-bearing element form it refers to (where the URI will be).

5.2.4.7. XML Catalog URI

   An [XML catalog document] conforms to [XML Catalogs 1.1]. For the purpose of MPD validation, the following rules ensure that an XML catalog document contains URIs that correctly resolve.

Rule 5-33. XML Catalog uri Value Resolves to Resource

   [Rule 5-33] (XML-catalog)

      Within an [XML catalog document], the value of a uri attribute owned by a er:uri element MUST [resolve] to a resource.

Rule 5-34. XML Catalog uri Value Resolves to Resource with Correct Target Namespace

   [Rule 5-34] (XML-catalog)

      Within an [XML catalog document], given an [XML schema document] resolved by the value of a uri attribute owned by a er:uri element, the [XML schema document] target namespace MUST equal the value of the name (a namespace string) attribute owned by the er:uri element.

5.2.4.8. Summary of MPD URIs

   This section summarizes the various URIs used in the MPD catalog document. It also presents a summary of [RFC 3986 URI]. See that reference for explanation and details of URI syntax.

   Table 5-1: Summary of "RFC 3986 URI: Generic Syntax"

      Id|URI Syntax|Meaning|Examples

      1|<absolute-URI>|absolute URI only (no fragment)|http://nlets.org/rap/3.1/

      2|<URI>|absolute URI and optional fragment|http://nlets.org/rap/3.1/#rap-sheet2

      3|<relative-reference>|optional relative part and optional fragment|/iep-sample/query.xml or #A3 or /iep-sample/query.xml#A3

      4|<URI-reference>|<URI> or <relative-reference>|any example in 1, 2, or 3 above

      

   As the table above indicates, [RFC 3986 URI] allows a <relative-reference> to contain a fragment or even be a fragment itself. However, a c:pathURI is required to resolve to a local resource. Therefore, rules in this specification preclude a c:pathURI value from taking the fragment-only form of a <relative-reference>.

   Table 5-2: Summary of MPD URI attributes

      MPD Attribute|URI Syntax (refer to table above)

      c:mpdURI|<absolute-URI>

      c:pathURI|<relative-reference>; excluding fragment-only format; relative to [MPD catalog document]

      c:externalURI|<URI>

      c:resourceURI|<URI>

      

5.3. Change Log

   A version identifier is a useful and simple visual indicator that an [MPD] has changed. However, a change log is needed to understand the volume, complexity, and possible impact of changes.

   [Definition: change log]

      An artifact that describes the changes applied to an [MPD] since its previous version.

5.3.1. Change Log for Releases and Domain Updates

   Once published, a NIEM release always exists. This ensures that an [IEPD] built from a given release will always be usable. Developers are not compelled to update their IEPDs when a new release is publshed; they may wait until an update is convenient, or absolutely necessary to take advantage of new or modified [data components]. Though not encouraged, nothing prohibits a developer from building an [IEPD] based on a NIEM release that is older than the most current version. There may be potential disadvantages related to interoperability levels achievable with others developing to the latest release. Nonetheless, an older version might meet the business needs of a particular organization quite well.

   New versions of reference schema document sets such as NIEM releases and domain updates can have significant impacts on future IEPDs. Developers must understand in detail how changes will affect their [IEPD] products and the tools used to build them. To work effectively, tools for domain content development, impact analysis, migration between releases, etc. must be able to digest formal change logs. A formal change log is also essential to efficiently process and integrate new and changed content into NIEM for new releases, and to simultaneously maintain multiple versions of NIEM for users. All of the foregoing reasons dictate that a NIEM reference schema document set requires a normative change log.

   Formal change logs for releases and domain updates will be detailed in future NIEM specifications related to these MPDs.

5.3.2. Change Log for IEPDs

   An [IEPD] change log is not required to conform to any particular XML schema or other format specification. However, a change log is still required for an [IEPD].

Rule 5-35. IEPD Has a Change Log

   [Rule 5-35] (IEPD)

      An [IEPD] MUST contain a [change log] artifact that is identified by a c:MPDChangeLog element in its [MPD catalog document].

   The [change log] for the first version release of an IEPD simply contains its release date.

   The format of an [IEPD] change log is left to the discretion of the author. A flexible [change log] format encourages and facilitates easier and more rapid development. IEPDs are developed by a variety of NIEM domains, organizations, and users; and they are intended to specify implementable exchanges. As a result, an [IEPD] may contain both documentation artifacts and machine readable application artifacts in a large variety of formats. As a result, a consistent standard [change log] would be very difficult to specify.

5.4. ReadMe Artifact

   [Definition: readme artifact]

      An informal documentation artifact contained in a [model package description] that serves as the initial general source of human readable descriptive or instructional information. A readme artifact or file (formerly known as a master document) may index or reference other more specific documentation or other explanatory materials within the [MPD].

   A [readme artifact] is only required for IEPDs since these MPDs are allowed the greatest design flexibility, can be developed and implemented different ways, and are not centrally managed. On the other hand, releases and domain updates have restrictive rules, standard documentation for using them, and central management.

Rule 5-36. Readme Describes Purpose, Scope, Business Value, etc.

   [Rule 5-36] (WF-MPD)

      A [readme artifact] SHOULD (at a minimum) describe the [MPD] purpose, scope, business value, exchange information, typical senders/receivers, interactions, and references to other documentation.

Rule 5-37. IEPD Has a ReadMe Artifact

   [Rule 5-37] (IEPD)

      An IEPD MUST contain a [readme artifact] that is identified by a c:ReadMe element in its [MPD catalog document].

   The [readme artifact] may replicate some of the metadata in the MPD catalog. However, the MPD catalog is intentionally designed to be efficient, easy to parse, and minimal. It is intended for search, discovery, registration, and Web page generation, and not to support various types of detailed technical prose often required for human understanding.

   The primary purposes of the [readme artifact] include:

      *  To help facilitate understanding and reuse of IEPDs.

      *  To ensure that fundamental and detailed business-level information about an [IEPD] are documented for human understanding.

      *  To ensure the [IEPD] author has considered and conveys such fundamental information.

      *  To provide an initial source within an [IEPD] for human consumable documentation and/or references to other business or technical documentation needed for understanding.

   The [readme artifact] is not intended to be the only source of written documentation for an MPD (though it can be). It is expected to be the initial resource that references and coordinates all others whether physically present in the MPD or linked by reference. Many organizations have their own customized formats and operating procedures for documenting their work and products. This specification does not attempt to standardize readme file name, location, format, or layout; only that it be identified in the [MPD catalog document] of an IEPD. The following section will generally describe minimal content that should be in the [readme artifact]. This guidance is non-normative, so adherence is a subjective judgment by the author.

5.4.1. Readme Content

   This section is non-normative.

   This section is neither a cookbook nor a normative specification for a [readme artifact]. It simply suggests typical topics that a readme artifact should or might address, and provides some non-normative guidance.

   The readme file should help another user or developer to understand the content and use of an [IEPD], as well as determine potential for reuse or adaptation. It should describe what implementers need to understand and what the author considers is important to understanding an [IEPD]. There is no limit or constraint on its content.

   At a minimum, the [readme artifact] should contain several fundamental elements of information about the MPD:

      *  Purpose of this MPD.

      *  Scope of its deployment, usage, and information content.

      *  Business value and rationale for developing it.

      *  Type of information it is intended to exchange (in business terms).

      *  Identification of senders and receivers (or the types of senders and receivers).

      *  Typical interactions between senders, receivers, and systems.

      *  References to other documentation within the MPD, and links to external documents that may be needed to understand and implement it.

   Many document formats (e.g., HTML, PDF) can display hyperlinks to local files within the MPD as well as URLs to files on the Internet. Employing such a format is highly recommended but not mandatory.

   MPD documentation types and formats will vary with the methodologies and tools used to develop them. Most of this documentation will likely be typical of that generated for data-oriented software projects. Some documentation may only require sections in the [readme artifact]. Other documentation may be more suitable as separate artifacts that are referenced and explained by a section in the [readme artifact] (such as diagrams, large tables, data dictionaries, test results/reports, etc.). The following are some common examples of sections in or separate artifacts associated with the [readme artifact]:

      *  Executive summary (especially for a lengthy readme artifact>

      *  Use cases

      *  Business processes

      *  Business requirements

      *  Business rules

      *  Metadata security considerations

      *  Domain model design specifications and documentation and/or diagrams

      *  Data dictionary

      *  Testing and conformance

      *  Development tools and methodologies used

      *  Implementation guidance (particularly important for a complex [IEPD] with multiple subsets or IEP root elements)

      *  Security considerations

      *  Privacy considerations (e.g., Personal Identifiable Information)

      *  Types of implementations

      *  If an [IEPD] employs multiple subsets:

            *  When, where, and how these are used

            *  How these are coordinated in the implementation

            *  Caveats regarding duplicate [data components] (which can occur with multiple subsets)

      *  If an [IEPD] employs multiple IEP conformance targets:

            *  Purpose of each and when it should be used

            *  How these are coordinated during the runtime preparation and transmission of IEPs

5.5. XML Catalogs

   [Definition: XML catalog document]

      As defined by [XML Catalogs 1.1], which states:

         An entity catalog.

      An [XML catalog document] MUST conform to all the rules in this specification for the conformance target [XML catalog document].

      Rules specifying this conformance target use the applicability code "XML-catalog".

   An [XML catalog document] is an [instance XML document] that describes a mapping between external entity references and locally-cached equivalents. It associates a URI reference with information about an external reference that appears in an XML document. An [XML catalog document] can be used to locate the replacement text for an external entity, or an alternate URI reference for a resource.

   An MPD can use an [XML catalog document] to [resolve] XML schema document target namespaces to local URIs. This is especially useful when assembling an XML schema from an XML schema document set. Some validators (e.g., Xerces) and other tools utilize [XML catalog documents] for this purpose.

   [IEPD] authors are encouraged to employ [XML catalog documents] within IEPDs to facilitate validation of IEPs.

   Note that schema assembly or [XML catalog document] design from non-conformant [external schema documents] that may contain xs:include statements can be problematic.

   In order to support [XML schema assembly] for the purpose of [XML schema validation], the namespace of each XML schema document used within an [IEPD] should [resolve] to a locally-unique artifact. A correctly constructed [XML catalog document] can guarantee this.

   According to [XML Catalogs 1.1], er:nextCatalog elements may be used within [XML catalog documents] to connect them and control the parsing sequence. Section 5.6, Defining Information Exchange Packages, below, discusses more about using [XML catalog documents] within IEPDs.

   According to [W3C XML Schema Part 1 Structures], the assembly of a schema document set into a schema is implementation-dependent. In practice, different tools use different methods for selecting the next schema document in the assembly process. This specification recommends the use of [XML catalog documents] as the preferred method for describing the desired schema assembly (for validation or other purposes).

   The MPD catalog schema document defines a c:XMLSchemaType that contains both c:XMLSchemaDocument elements and c:XMLCatalog elements, which may appear interleaved, or in any order. Occurrences of the c:XMLSchemaDocument identify schema documents to be used in schema assembly. c:XMLCatalog identifies the [XML catalog documents] to be used to identify schema documents, each corresponding to an XML namespace, which may be used in schema assembly. Relative order of c:XMLCatalog entries is considered significant, with catalogs appearing earlier taking precedence over catalogs appearing later. Note that the schema document assembly process does not specify a document element for an [instance XML document]; this may be specified with other mechanisms provided by the MPD catalog, such as Schematron, XPath expressions, or by explicitly setting a document element.

   This document does not specify the schema assembly process. A deterministic, implementation-independent schema assembly process may be the subject of a later NIEM specification.

5.6. Defining Information Exchange Packages

   An MPD may declare one or more IEP conformance targets within its [MPD catalog document].

   [Definition: IEP conformance target]

      A [conformance target] that is a class or category of IEP which has a set of one or more validity constraints and a [conformance target identifier]. Every IEP is an instance of one or more IEP conformance targets.

   This definition requires that an IEP conformance target be assigned a [conformance target identifier] that distinguishes it from all other [IEP conformance targets]. Construct a [conformance target identifier] using a fragment identifier (similar to an MPD artifact URI) per this rule:

Rule 5-38. Conformance Target Identifier

   [Rule 5-38] (MPD-catalog)

      A [conformance target identifier] for an [IEP conformance target] declared in an MPD is formed by concatenating in sequence:

         1. the IEPD URI, and

         2. the pound sign character (#). and

         3. a locally unique NCName (i.e., a non-colonized name, as defined by [W3C XML Schema Part 2 Datatypes], section 3.3.7, "NCName").

   This rule requires that an [IEP conformance target] has a URI, i.e., its [conformance target identifier].

   The following rule is required for an [MPD catalog document]. It supplements the rule above.

Rule 5-39. IEP Conformance Target Has a structures:id

   [Rule 5-39] (MPD-catalog)

      A c:IEPConformanceTarget element MUST own a structures:id attribute.

   This rule ensures that a [conformance target] can be referenced between MPDs (not just within an MPD). The value of the structures:id attribute is the NCName in Rule 5-38, Conformance Target Identifier.

   An [IEPD] defines IEP conformance targets by explicitly declaring them within its MPD catalog per the rules above.

Rule 5-40. [IEPD] Declares One or More IEP Conformance Targets

   [Rule 5-40] (IEPD)

      The [MPD catalog document] of an [IEPD] MUST contain one or more c:IEPConformanceTarget elements.

   The following subsections detail the concepts, artifacts, and procedures for declaring and identifying [IEP conformance targets] in IEPDs.

5.6.1. Validity Context and Constraints

   Explicit declaration of validity constraints is far more flexible and precise than relying on conventions that can easily be misinterpreted. The c:IEPConformanceTarget element within the [MPD catalog document] can apply several common constraints by explicitly declaring the information required for a given constraint. This information may include the conformance target, context, and type of validation, location of validation artifact(s), and specific tests to perform. It can also identify IEP samples known to satisfy the validity constraints.

   Appendix A, MPD Catalog XML Schema Document, below, provides XML elements for various validity constraints. These constraints are employed by element substitution using two abstract elements, c:ValidityConstraintWithContext and c:ValidityConstraint. Appendix A, MPD Catalog XML Schema Document, below, normatively specifies how this works.

   Note that there may exist multiple ways to declare the same validity constraint with these elements. This rule only requires that each required validity constraint be declared once in a single form. For example, it may be possible to use either c:HasDocumentElement and c:ValidToXPath to declare the same XML document elements. However, it is only required that an [IEPD] author use one or the other.

   [Definition: validity constraint context]

      A set of information items that establishes the applicability of certain validity constraints.

   Validity constraint context can refer to multiple information items (e.g., XML elements, attributes, etc.) within an IEP. Also, note that [validity constraint context] can evaluate to no information items (e.g., in XPath, "()", for which "empty-sequence()" is true). In this cases, the validity constraints (within the in scope validity constraint context) will not fire and the test passes.

   The following subsections explain in more detail the purpose and context for validity constraints that can be declared in c:IEPConformanceTarget.

5.6.2. Declaring Validity Constraints

5.6.2.1. c:ValidityConstraintWithContext

   c:ValidityConstraintWithContext is an abstract element into which various validity constraints will be substituted, depending upon the MPD author's intent. In the absence of an explicit context (declared by an c:xPathText attribute), [validity constraint context] defaults to the IEP's document information item as defined in [W3-XML-InfoSet],  section 2.1, "The Document Information Item". In this default case, a specific validity constraint will substitute for c:ValidityConstraint which in turn, substitutes for c:ValidityConstraintWithContext.

5.6.2.2. c:ValidityConstraint

   This is the abstract element for which a specific validity constraint will substitute if no explicit context is used (and therefore, the default document context applies as described in Section 5.6.2.1, c:ValidityConstraintWithContext, above).

5.6.2.3. c:ValidityContext

   [Validity constraint context] is explicitly declared by an XPath expression that is the value of c:xPathText. c:ValidityContext can contain any of the specific validity constraints that are substitutable for c:ValidityConstraint.

Rule 5-41. 

   [Rule 5-41] (MPD-catalog)

      Given a c:xPathText attribute owned by c:ValidityContext, the [validity constraint context] for the descendant's validity constraint SHALL be the value of c:xPathText evaluated against the IEP's document information item (See [W3-XML-InfoSet],  section 2.1, "The Document Information Item").

5.6.2.4. c:HasDocumentElement

   c:HasDocumentElement is a validity constraint that identifies all intended XML document elements for an IEP conformance target, and it is directly substitutable for c:ValidityConstraintWithContext. This constraint ensures that an IEP artifact is rooted by one XML document element that is a member of the list of elements in its c:qualifiedNameList attribute. This is a common validity constraint employed by simple IEPDs that declare one or more intended XML document elements.

   Note that [validity constraint context] of c:HasDocumentElement is always on the IEP's document information item as defined in [W3-XML-InfoSet],  section 2.1, "The Document Information Item". This is because it can only declare XML document elements. So, if an IEP defines a payload that may be included in some XML envelope, then c:HasDocumentElement should not be used. Instead, use c:ValidityContext with another specific validity constraint and c:xPathText to explicitly declare [validity constraint context].

   When employing c:HasDocumentElement the following rule applies:

Rule 5-42. Identifying the Document Element of an IEP

   [Rule 5-42] (IEP)

      Within an MPD catalog document, if an c:IEPConformanceTarget element for an IEP has a c:HasDocumentElement child element owning a c:qualifiedNameList attribute with a value of $LIST, then the document element of the IEP MUST have a QName that is a member of $LIST.

5.6.2.5. c:ValidToXPath

   c:ValidToXPath is a specific validity constraint whose purpose is to ensure that a condition is satisfied within an IEP. The condition is defined by an XPath expression contained in the c:xPathText attribute. If the XPath expression applied to a target instance [XML document] returns a Boolean value of TRUE, then the condition is satisfied by that XML document.

   This validity constraint is useful for a variety of purposes. For example, an [IEPD] author may require that a given c:IEPConformanceTarget must contain a particular element with a particular attribute whose value is an integer greater than some required minimum. An XPath expression can validate this.

   c:ValidToXPath can also employ a simple XPath expression to validate that an IEP is rooted with an intended XML document element. However, other validity constraints can do this as well; the [IEPD] author may choose the constraint representation.

   Note that if c:ValidToXPath is used (substituted) within c:ValidityContext there will be two XPath expressions -- the expression within c:ValidToXPath is the condition to validate, the other is the context (where the condition will be validated). For example, the context provided by c:ValidityContext might be //my:speedingTicket, while the c:ValidToXPath might require that a test for exists(nc:DriverPerson) be true.

   This specific validity constraint as well as those that follow below can either be substituted for the c:ValidityConstraint or used within the c:ValidityContext element (i.e., substituted for its c:ValidityConstraint child).

   Note that if c:ValidToXPath is substituted for c:ValidityConstraint within the c:ValidityContext element, then the explicit context, the c:xPathText value, can imply that multiple items must be checked and each must return "true" in order for an IEP to pass the c:ValidToXPath constraint.

   When employing c:ValidToXPath the following rule applies:

Rule 5-43. Validating an XPath Expression

   [Rule 5-43] (IEP)

      Within an [MPD catalog document] with a c:xPathText attribute owned by a c:ValidToXPath element, a candidate IEP is a valid IEP, ONLY IF the value of c:ValidToXPath applied to the candidate IEP (an [XML document]) has an effective Boolean value (EBV) equal to true. EBV is defined by [W3C XPath 2.0],  section 2.4.3, "Effective Boolean Value".

5.6.2.6. c:XMLSchemaValid

   NIEM employs the W3C XML Schema Definition (XSD) Language ([W3C XML Schema Part 1 Structures] and [W3C XML Schema Part 2 Datatypes]), one of several XML schema definition languages designed to define an instance XML document and enable its validation. In general, an instance XML document is valid against a particular XML schema if it obeys or conforms to the constraints imposed by that schema ([W3C XML Schema Part 1 Structures],  section 2.5, "Schema-validity and documents").

   So, a NIEM [IEPD] is an MPD that contains a set of XML schema documents, that are assembled into an XML schema (after processing XML catalogs to [resolve URI] values in namespace attributes owned by xs:import elements and similar XML Schema constructs). In turn, the resulting XML schema can be used to validate one or more [instance XML documents] for NIEM conformance.

   NIEM is based on XML Schema, and so the term "schema validation" usually refers to "XML Schema validation". However, an [IEPD] author may also choose to include artifacts to validate with other types of schemas or rules, including but not limited to [ISO Schematron] and [ISO RelaxNG]. [IEPD] authors may also include artifacts for NIEM constraint schema validation, which, of course, is XML Schema validation (See Section 4.5, Constraint Schema Document Sets, above.

   Because NIEM is XML Schema based, then c:XMLSchemaValid (of type c:XMLSchemaType) will likely be employed by most IEPDs. This validity constraint ensures that an IEP artifact is schema valid to an XML schema that can be assembled correctly from the schema documents that comprise it. To do this c:XMLSchemaValid provides two methods to choose from based on its child elements, c:XMLCatalog and c:XMLSchemaDocument, both zero to unbounded cardinality. The MPD author can use (1) c:XMLCatalog to identify one or more XML catalog documents that map the correct schema documents; or (2) c:XMLSchemaDocument to explicitly identify the one or more XML schema documents to be retrieved. In each case, depending on the nature of the XML schema document set from which the schema documents are coming, it may be possible to identify a single XML catalog document or a single XML schema document. That catalog or schema document will be the starting point or root document and will contain enough information to explicitly identify or cascade to the rest. (See also Section 5.5, XML Catalogs, above)

   It is the MPD author's responsibility to ensure that the method used (XML catalogs or XML schema document identification) is configured correctly per the appropriate specification ([XML Catalogs 1.1] or [W3C XML Schema Part 1 Structures]).

5.6.2.7. c:SchematronValid

   c:SchematronValid is similar to c:XMLSchemaValid, but uses a c:SchematronSchema element to identify the Schematron rule file that applies to the IEP.

5.6.2.8. c:RelaxNGValid

   c:RelaxNGValid is similar to the previous two validity constraints, but uses a c:RelaxNGSchema element to identify the RelaxNG schema file to which the IEP must validate.

5.6.2.9. c:ConformsToConformanceTarget

   c:ConformsToConformanceTarget enables an [IEPD] author to effectively subclass and relate conformance target classes. For example, using this constraint, a given conformance target class defined by a c:IEPConformanceTarget structures:id="A2" can be required to also conform to another class structures:id="A1". This creates an IS-A relationship. We say that A2 IS-AN A1, or that A2 IS-A specialization of A1.

   Conformance target classes are related through the c:conformanceTargetURI attribute owned by c:ConformsToConformanceTarget. Recall that per Rule 5-38, Conformance Target Identifier a conformance target URI is formed by concatenating the [IEPD] URI (the value of c:mpdURI), the pound character ("#"), and the value of the conformance class (structures:id) of the [IEP conformance target].

5.6.2.10. c:ConformsToRule

   Sometimes it is not possible to formally declare an executable validity constraint. For example, we can mandate that a [data component] definition must be present, must be in English, and must follow [ISO 11179-4]. Validating that text is present is easy, and validating that it is in English is more difficult, but validating that it obeys [ISO 11179-4] is essentially intractable. Thus, c:ConformsToRule provides an [IEPD] author with English text representation as an alternative when it is not possible or not easy to define more formal validation rules or validity constraints.

5.6.3. IEP Sample Instance XML Documents

   This section discusses sample IEPs in the context of an [IEPD]. However, this is not meant to imply that sample IEPs are not useful in other MPDs.

   A sample IEP [instance XML document] is a representation of an actual or example exchange data instance. Sample instances can be extremely valuable artifacts in an [IEPD]. Sample IEPs:

      *  Help an [IEPD] implementer to understand the original intent of the [IEPD] author.

      *  Can be used by an implementer as a data point for validation of IEP conformance targets.

      *  can indicate or imply [IEPD] quality.

   For these reasons, the following rule applies to an [IEPD]:

Rule 5-44. IEPD Has an IEP Sample for Each c:IEPConformanceTarget

   [Rule 5-44] (IEPD)

      Within the MPD catalog document of an [IEPD], a c:IEPConformanceTarget element MUST contain a c:IEPSampleXMLDocument child element.

   The rule above requires that each declared [IEP conformance target] be covered (exemplified or correctly demonstrated) by at least one IEP sample instance XML document. This does not necessarily mandate a different IEP sample for each [IEP conformance target]. It may be possible, and is therefore acceptable, for a given IEP sample to serve as an example of one or more [IEP conformance targets].

   The purpose of this rule is not to provide a test for all possible IEP permutations given the schema definitions and validity constraint declarations; rather, it is to encourage [IEPD] authors to test their own designs, and to provide implementers with examples for additional understanding, guidance, and testing. To the extent possible, [IEPD] authors should strive to include sample IEPs that (1) capture real world business cases of data exchanges, and (2) exercise as many [data components] and validity constraints as possible. Where it makes sense, an [IEPD] author should strive to provide enough sample IEPs to exercise all the XML document elements (or payload root elements). If a single IEP cannot provide enough example coverage, an author may include multiple IEPs (but is not required to do so).

   Each sample IEP usually illustrates a single view of the data based on a chosen set of conditions. Other views based on different conditions likely exist. An implementer will still need to review the [IEPD] documentation to ensure understanding of all potential conditions. Therefore, as appropriate, the author should not rely exclusively on sample IEPs to convey implementation understanding, since they will probably not account for all possible permutations.

   The following rule relates to validity of an IEP Sample XML Document:

Rule 5-45. Validating an IEP Sample XML Document

   [Rule 5-45] (IEP)

      Within an [MPD catalog document] with a c:pathURI attribute owned by a c:IEPSampleXMLDocument, the artifact resolved by the value of c:pathURI MUST be valid for the validity constraints of the c:IEPConformanceTarget parent of c:IEPSampleXMLDocument.

5.7. Conformance Assertion

   This section discusses a [conformance assertion] in the context of an [IEPD]. However, this artifact may also be useful to other classes of MPDs.

   Independent authors build NIEM IEPDs from NIEM [reference schema document sets]. Presently, a formal NIEM conformance certification process for IEPDs does not exist. Therefore, this specification requires that an [IEPD] contain an artifact that asserts NIEM conformance and provides a small amount of information to support such.

   [Definition: conformance assertion]

      An artifact that provides a declaration that an MPD conforms to relevant NIEM specifications and associated rules, including [NIEM Conformance 3.0], [NIEM Naming and Design Rules 3.0], [NIEM Conformance Targets Attribute Specification 3.0] and [NIEM MPD Specification 3.0] (this NIEM MPD Specification).

Rule 5-46. IEPD Has Conformance Assertion

   [Rule 5-46] (IEPD)

      An [IEPD] MUST contain a [conformance assertion] artifact that is identified by a c:ConformanceAssertion element in its [MPD catalog document].

   A [conformance assertion] provides information to increase the level of confidence that an [IEPD] was checked for NIEM conformance and quality. It does NOT constitute a guarantee or contract. In fact, a conformance assertion can be self-asserted.

   In the absence of a formal NIEM certification process, both weak and strong conformance assertions will exist. An [IEPD] user or implementer (who is not the author) must decide his/her level of confidence in the assertion. A self-signed artifact that simply claims an [IEPD] is NIEM-conformant may be considered weak. On the other hand, a stronger self-assertion could provide information that may include (but is not limited to):

      *  Date of assertion

      *  URI of the MPD claiming NIEM conformance

      *  Assertion of NIEM conformance

      *  Author (name and/or organization, or sponsoring entity; indication of NIEM and XML background or experience)

      *  Certifier (may be the author or another person/organization)

      *  Details of conformance verification:

            *  How, what, and/or who? (e.g., automatic checks, manual checks, other reviews?)

            *  Tool(s) employed? (e.g., tool, version, how used, on what, etc.)

            *  Results? (e.g., issues, pass/fails, warnings, confirmations, etc.)

   Inclusion of a [conformance assertion] made by a reputable, independent, trusted entity (person or organization) would likely increase confidence in conformance. Another strong case can be made by supplementing a conformance assertion with a formal conformance test report or similar artifact. The MPD catalog schema document provides a c:ConformanceReport element to identify a conformance report if one is present.

   In the future, as NIEM procedures and tools advance, a conformance or quality report and a corresponding certificate may become required artifacts. A tool might check conformance and issue the report and certificate together as a digitally signed and hashed artifact that reports conformance, and proves both author and [IEPD] identity (i.e., that the [IEPD] is an unaltered copy of the original). For now, inclusion of an informal [conformance assertion] artifact in an [IEPD] is the only requirement.

6. Optional MPD Artifacts

   Aside from the required artifacts, MPD content is relatively flexible. A variety of other optional documentation files may be incorporated into an MPD. When applicable, these may include (but are not limited to) files that describe or explain:

      *  Implementation details (hardware, software, configuration, etc.)

      *  Use of multiple root elements

      *  Use of multiple subsets or mixed releases

      *  How to use/reuse an MPD for various purposes (such as Web Services)

      *  Rationales and/or business purposes

   In addition to documentation artifacts, a variety of other optional files can be added to an MPD to facilitate tool support and make reuse, adaptation, and/or implementation easier. These are often files that are inputs to or outputs from software tools. Examples include content diagrams, content models in tool-specific formats, and business rules (either formal or informal representations).

   An MPD author may include any files believed to be useful to understand, implement, reuse, and/or adapt an MPD.

   An MPD of relatively simple content and scope may only need to contain the minimum mandatory artifacts required by this specification in order to understand and implement it. (See Appendix C, Common MPD Artifacts, below, for a listing of the mandatory and common optional artifacts for each type of MPD.)

   Files vary widely in format and are often specific to the tools an author uses to parse, consume, or output them. Therefore, if tool-specific files are included in an MPD, it is also a good practice to include copies of those files in formats that display with standard Web browsers or other cost-free, publicly available viewing tools (e.g., ASCII text, PDF, CSV, HTML, JPG, GIF, PNG). This guidance is intended to encourage and facilitate maximal sharing and distribution of MPDs; it does not prohibit and is not intended to discourage the inclusion of other file formats.

   In particular, this specification does not discourage use of Microsoft file formats for documentation and other optional artifacts. Microsoft Office products are in common use, and free viewers are available for many of them (See http://office.microsoft.com/en-us/downloads/office-online-file-converters-and-viewers-HA001044981.aspx).

6.1. NIEM Wantlist

   A NIEM schema document subset is often associated with a NIEM wantlist. A wantlist is an abbreviated XML representation of a NIEM schema document subset, and identifies only the [data components] a user selected (as requirements) to build a schema document subset. To reconstruct the complete schema document subset there are usually a number of additional [data components] that the user selections depend upon. These must be computed from the appropriate NIEM reference model and added to reconstruct the complete schema document subset. For example, a user may select nc:Person for the subset. In this case, the wantlist will only contain that component, but the associated full subset must contain both nc:Person and nc:PersonType. A software tool that understands how to process NIEM wantlists and schema document subsets (such as the NIEM Schema Subset Generator Tool [NIEM SSGT]) can rebuild an accurate schema document subset from a wantlist (and the reverse).

   [Definition: NIEM wantlist]

      An XML document that represents a complete NIEM schema document subset.

   A NIEM wantlist identifies the [data component] requirements declared by the subset author; it does not identify the [data component] dependencies required to reconstitute the complete subset. The complete subset can be computed with the reference schema document set from which the subset was derived.

   A wantlist is always associated with a schema document subset. A wantlist may also be associated with a [constraint schema document set], because constraint schema documents are often built from a [schema document subset]. For a simple [IEPD], it can sometimes be trivial to identify a single schema document subset. However, this MPD Specification does not prohibit building complex IEPDs that contain schema document sets supported by multiple schema document subsets and associated wantlists. As with other complex cases, the [IEPD] author is responsible to clearly document the associations between wantlists and schema document sets. In order to maintain a minimal degree of consistency for placement of a wantlist within an [IEPD] the following rule applies.

Rule 6-1. Wantlist Location

   [Rule 6-1] (WF-MPD)

      If present, a NIEM wantlist MUST reside within the root of the MPD subdirectory that groups and defines its corresponding subset schema document set (e.g., niem).

6.2. Business Rules

   For simplicity and consistency, NIEM employs a profile of the XML Schema language [W3C XML Schema Part 1 Structures], [W3C XML Schema Part 2 Datatypes]. Thus, some constraints on NIEM XML documents cannot be enforced by NIEM. [Constraint schema document sets] provide a convenient technique for enforcing some additional constraints. However, even the full XML Schema language cannot validate and enforce all possible constraints that may be required of an XML document.

   So, NIEM allows (even encourages) the use of formal or informal [business rules] to help define or constrain MPDs (in particular IEPDs).

   [Definition: business rules]

      Formal or informal statements that describe business policy or procedure, and in doing so define or constrain some aspect of a process or procedure in order to impose control.

   [Business rules] may be represented as informal English statements, or as formally coded machine-readable and process-able statements. For example, an [IEPD] may use a [Schematron schema] [ISO Schematron] or any other formal representation for [business rules].

   [Definition: business rule schema]

      An artifact that contains [business rules] in a formal representation language with the intent to automatically process them on an XML document to enforce business constraints.

   [Definition: Schematron schema]

      A [business rule schema] that adheres to [ISO Schematron].

7. Organization, Packaging, and Other Criteria

   An MPD is a logical set of electronic files aggregated and organized to fulfill a specific purpose in NIEM. Directory organization and packaging of an MPD should be designed around major themes in NIEM: reuse, sharing, interoperability, and efficiency.

Rule 7-1. An MPD in ZIP File Format Preserves Logical Directory Structure.

   [Rule 7-1] (WF-MPD)

      An MPD in [ZIP file] format represents a sub-tree of a file system. Such an archive MUST preserve and store the logical directory structure intended by its author for respository format.

   NIEM XSD and XML [artifacts] in an MPD must be valid for both XML Schema and NIEM. This also implies these artifacts must adhere to applicable [NIEM Naming and Design Rules 3.0] conformance target rules.

Rule 7-2. XSD and XML Documents Conform to Applicable NDR Conformance Targets

   [Rule 7-2] (WF-MPD)

      Within an MPD, each XML schema document (XSD) or instance XML document (XML) artifact that uses a conformance targets attribute (as defined by [NIEM Conformance Targets Attribute Specification 3.0]) MUST satisfy the [NIEM Naming and Design Rules 3.0] rules for the conformance targets it declares.

   NIEM releases and domain updates maintain a relatively consistent directory organization [NIEM Domain Update Specification 1.0]. But there are many ways to organize [IEPD] directories that may depend on a number of factors including (not limited to) business purpose and complexity. For this reason, strict rules for [IEPD] directory structure are difficult to establish. Therefore, [IEPD] authors may create their own logical directory structures subject to the rules of this section.

   [Definition: MPD root directory]

      The top level file directory relative to all MPD artifacts and subdirectories.

Rule 7-3. MPD Archive Uncompresses to a Single Root Directory

   [Rule 7-3] (WF-MPD)

      An MPD in [ZIP file] format MUST uncompress (unzip) to one and only one [MPD root directory].

   The foregoing rule ensures that:

      *  Unpacking an MPD in [ZIP file] format will not scatter its contents on a storage device.

      *  One common starting directory always exists to explore or use any MPD.

      *  mpd-catalog and change log artifacts will always be found in the [MPD root directory].

7.1. Artifact Sets

   Grouping artifacts into sets is generally optional. There may be many reasons for identifying artifacts sets in an MPD. While directory structure is most often the most convenient method for grouping a set of artifacts, there may multiple logical groupings, and these may spread across multiple directories.

   This specification defines other ways to group MPD artifacts into [sets]. In general, independent of directory organization, sets can be established through one of two methods. An [XML catalog document] can be used to establish an [XML schema document] set. The [MPD catalog document] can be used to identify all kinds of artifacts sets (including XML schema documents).

   Section 5.5, XML Catalogs, above, describes how NIEM employs an [XML catalog document] to assemble an [XML Schema] from [XML schema documents]. For user convenience, this method is now used in NIEM releases (as well as their associated core supplements) and domain updates. Note also that this method is applicable to all the various classes of NIEM XML schema documents (reference, subset, extension, constraint, and external).

   Another reason for grouping artifacts into sets is a need for humans to review, identify, and navigate the artifacts of an [IEPD] (particularly, if it is complicated). An [XML catalog document] has a relatively focused purpose, to identify (by namespace) and assemble a set of XML schema documents into an [XML Schema]. It is not intended to index artifacts in general (other than XML schema documents to assigned target namespaces). So, it does not classify or describe the artifacts it identifies.

   On the other hand, the [MPD catalog document] is designed to record, index, classify, and describe (as needed) any or all MPD artifacts (not just schema documents). The MPD catalog provides a flexible method for grouping all kinds artifacts.

   The MPD catalog schema Appendix A, MPD Catalog XML Schema Document, below, defines a set of common artifact classifiers and artifact set classifiers. In summary, per Appendix A, MPD Catalog XML Schema Document, below, define sets by substituting the appropriate artifact classifier (of type c:FileType) into the abstract element c:ArtifactOrArtifactSet, within the appropriate artifact set classifier (of type c:FileSetType). Use the most specific classifiers available for your artifacts and artifact sets. Otherwise, as needed, use generic c:File and c:FileSet classifiers with nc:DescriptionText.

   Note that the c:pathURI value for an artifact is its operating system relative directory [path name] with file name. The c:pathURI value for an artifact set is its operating system relative [path name].

   Artifact sets can be assembled in the MPD Catalog by using c:FileSet with or without a c:pathURI attribute.

   If a single directory contains all the artifacts in a set, then the following simple form of c:FileSet can be used:

   Figure 7-1: Simple c:FileSet form for a directory-associated artifact set.

      
      	<c:FileSet c:pathURI="samples/">
      		<nc:DescriptionText>All IEP samples within this IEPD.</nc:DescriptionText>
      	</c:FileSet>
      		

   This simple form of c:FileSet associates an operating system directory with a set of artifacts that also includes all artifacts within subdirectories under the directory named in the value of the c:pathURI attribute. Note that the interpretation of this XML schema component (as implied by nc:DescriptionText) is that all artifacts in the samples/ directory are sample IEPs, and no other IEP samples exist in other locations within the [IEPD]. The author must construct MPD catalog entries that are clear and correct. So, in this case, if other artifacts exist within this directory that are not sample IEPs or if sample IEPs exist in other directories, then use of this simple directory association form is not appropriate.

   However, multiple artifact sets and artifacts can be nested within a c:FileSet element to organize artifacts into a logical group of files in many locations. For example, an author may identify a set of artifacts in several locations using the following more complicated form of c:FileSet with the MPD catalog:

   Figure 7-2: c:FileSet form for a more complex artifact set.

      
      	<c:FileSet>
      		<nc:DescriptionText>All IEP samples in this IEPD</nc:DescriptionText>
      		<c:FileSet c:pathURI="samples/" />
      		<c:FileSet c:pathURI="iep-samples-1/" />
      		<c:FileSet c:pathURI="iep-samples-2/" />
      		<c:FileSet c:pathURI="iep-samples-supplement/" />
      		<c:IEPSampleXMLDocument c:pathURI="iep/test-case1.xml" c:mimeMediaTypeText="text/xml" />
      		<c:IEPSampleXMLDocument c:pathURI="test/test-case2.xml" c:mimeMediaTypeText="text/xml" />
      	</c:FileSet>
      		

   Another way the MPD catalog schema groups artifacts is through the use of the c:RequiredFile element. Use this construct to signify there are strong dependencies among artifacts. For example, documentation may be prepared as a set of hyperlinked HTML files. These HTML files may also incorporate separate GIF or JPG images. Regardless of file location within the MPD, these files depend on one another through hyperlinks. As a result, they tend to operate as a single artifact; removal of a file will cause one or more broken links within the set. This set of artifacts should be grouped using c:RequiredFile. If the set does not have a root HTML document (i.e., the set can be entered from any file in the set), then create an index HTML document and use it as the root of the set (i.e., the index is the value of the c:File element while all others are values for c:RequiredFile child elements).

7.1.1. Constraint on Elements of Type c:SchemaDocumentSetType

   In order to accommodate the [model package description] concept, the design of the MPD catalog schema does not enforce a rule that is required to ensure a c:SchemaDocumentSet within an [MPD catalog document] is used correctly for an [IEPD]. This rule assumes that within the IEPD's MPD catalog any c:SchemaDocumentSet element identifies [XML schema documents] to be assembled into an [XML Schema].

Rule 7-4. Constraint on Elements of Type c:SchemaDocumentSetType

   [Rule 7-4] (MPD-catalog)

      An element information item with a type definition validly derived from c:SchemaDocumentSetType MUST have a child element with an element declaration that is in the substitution group of c:XMLCatalog or c:XMLSchemaDocument.

   This rule ensures that a c:SchemaDocumentSet element always has at least one child element that is an [XML catalog document] (which itself defines an [XML schema document]) set, or an [XML schema document] (which constitutes a set of at least one schema document). This rule cannot be enforced within the MPD catalog schema without introducing a UPA error, but it could be enforced by a Schematron rule.

7.2. IEPD File Name Syntax

   Additional non-normative for directory naming and organization for IEPDs is in Appendix E, Guidance for IEPD Directories (non-normative), below.

   It is important to understand that this section does not apply to the syntax for the c:mpdName attribute in the [MPD catalog document]. Refer to Section 5.2.1, MPD Name Syntax (c:mpdName), above, for details regarding the c:mpdName metadata attribute.

   The MPD Specification is intended to help facilitate tool support for processing MPDs. Tools and search mechanisms that can identify basic MPD information as early as possible is efficient and valuable. So, if an MPD name, version, and class can be identified from its file name, then a tool would not have to open the [ZIP file] and parse the MPD catalog to determine such. Of course, to do anything useful, a tool will eventually have to open the MPD archive. However, a standard file name syntax allows a tool to search through a set of MPDs in [ZIP file] format to find a particular MPD name, version, or class without having to open each. File name consistency can also make it easier to scan and identify MPDs in a long list sorted by file name.

Rule 7-5. IEPD ZIP file Name Syntax

   [Rule 7-5] (IEPD)

      The file name of an [IEPD] [ZIP file] (iepd-filename) SHOULD adhere to the syntax defined by the regular expression:

      
      	iepd-filename ::= name '-' version '.iepd.zip'
      	Where: 
      		name     ::= alphanum ((alphanum | special)* alphanum)?
      		alphanum ::= [a-z0-9]
      		special  ::= '.' | '-' | '_'
      		version  ::= digit+ ('.' digit+)* (status digit+)?
      		digit    ::= [0-9]
      		status   ::= 'alpha' | 'beta' | 'rc' | 'rev'

      The status values are as defined in Rule 5-10, MPD Version Number Syntax.

   Regular expression notation in the rule above is from [W3C XML 1.0] #sec-notation.

   Alphabetic characters are lower case to reduce complications across various file systems.

   An example of an [IEPD] file name that follows this rule is: abc-query-2.0beta1.iepd.zip

   File names can easily be changed by a person or process that executes a download on the Internet. Nonetheless, [IEPD] authors and publishers should ensure that their application of Rule 7-5, IEPD ZIP file Name Syntax is consistent with an IEPD's catalog. The basic metadata in the [MPD catalog document] (e.g., IEPD name, version, class, URI, etc.) should match any such information incorporated into the file name.

7.3. Artifact Links to Other Resources

   It is important to understand that the URI scheme defined in Section 5.2.4.2, URI Scheme for MPD Artifacts (c:externalURI), above, can only be used to identify relationships among and provide source links to external schemas being reused. It is not sufficient to allow references or links to such schemas stand in for a physical copy. Thus, all schema artifacts necessary to define, validate, and use an MPD must be physically present within that MPD. In accordance with the [NIEM Naming and Design Rules 3.0], if MPD schemas are moved to an operational environment for implementation, validation, or other purposes, then absolute references may replace relative [path name] references when needed. The following rule applies when absolute references to Internet resources are required.

Rule 7-6. MPD Reference to Resource Uses Common URI Scheme

   [Rule 7-6] (WF-MPD)

      An absolute reference to an Internet resource MUST use a well-known URI scheme (e.g., http, https, ftp, ftps) and MUST [resolve]. If applicable, documentation SHOULD describe how to [resolve] with security, account, and/or password information.

7.4. IEPD Completeness

   Since an [IEPD] defines an information exchange and is often implemented by persons other than the original author, it is important to ensure that they are relatively complete and provide all artifacts needed to use the [IEPD].

Rule 7-7. IEPD Completeness

   [Rule 7-7] (IEPD)

      An [IEPD] SHOULD contain all artifacts needed to understand it and facilitate its correct implementation.

   The rule above means that an [IEPD] implementer should not be forced to search for or track down specialized schema documents, documentation, or other artifacts required to validate and implement exchanges defined by an [IEPD]. Specialized artifacts refer to those designed and built by an [IEPD] author, not artifacts that are standards and publicly available to all implementers. For example, this rule does not imply that an [IEPD] should contain a schema document that defines the XML schema component vocabulary identified by the namespace name http://www.w3.org/2001/XMLSchema (i.e., XS), or http://www.w3.org/2001/XMLSchema-instance (i.e., XSI). All schema processors have appropriate declarations for these built in. Likewise, an [IEPD] is not required to contain mpd-catalog-3.0.xsd or the standard NIEM subset that supports it.

   On the other hand, an [IEPD] whose author has extended the MPD catalog schema is clearly required to contain the catalog extension schema document, since this is a specialized customization created by the author. If a different NIEM schema subset is also used, then the [IEPD] must also contain its superset (i.e., a complete subset that incorporates both the original subset with additional NIEM components used to extend the catalog schema document; see Rule 5-8, MPD Schema Document Extension Support Schemas Are Supersets of Spec Subsets.)

   The rationale for "SHOULD" in Rule 7-7, IEPD Completeness relates to issues of security. Although NIEM is generally public, some IEPDs (and even other MPDs) may contain XML tags that provide more semantics or structure than a domain is willing to expose. In such cases, it may be necessary to simply refer to schema documents that are required for validation and implementation, instead of circulating them within a public [IEPD]. Implementers would then be expected to know how and where to obtain the required documents.

   The [NIEM Naming and Design Rules 3.0] explains how NIEM employs adapter types to encapsulate and use other standards (e.g., geospatial and emergency management standards) in their native forms that are not NIEM-conformant. Other standards may use xs:import without requiring schemaLocation attributes (instead, relying only on the namespace value). These standards may also use xs:include. This XML Schema construct is disallowed by NIEM. When standards external to NIEM are required within MPDs, the following rule applies:

Rule 7-8. MPD External Schema Documents Are Local Resources

   [Rule 7-8] (WF-MPD)

      Within an MPD, a non-NIEM-conformant external schema document reference to another schema document and/or namespace MUST [resolve] to a local resource. schemaLocation attributes or XML catalogs can be used to ensure resolution.

   For the case of non-NIEM-conformant schemas, this rule ensures that all schemas (or corresponding artifacts and namespaces) from external standards required for definition, validation, and use of the MPD are present within it.

   XML schemas are the heart of MPDs since they formally specify normative structure and semantics for [data components]. However, in general, an MPD is a closed set of artifacts. This means that all hyperlink references within artifacts should [resolve] to the appropriate artifact.

Rule 7-9. Key MPD Resources Are Local Resources

   [Rule 7-9] (WF-MPD)

      Within any artifact of an MPD, any direct reference to another resource (i.e., another artifact such as an image, schema, stylesheet, etc.) that is required to process or display an artifact SHOULD exist within the MPD at the location specified by that reference.

   This means that MPD artifacts, including documentation artifacts, should be complete. For example, if an HTML document within an MPD contains a hyperlink reference (href) to an artifact that is part of or used by the MPD, then the file associated with that hyperlink should be present in the MPD; likewise for a sourced (src) image. Authors should exercise good judgment with this rule. For example, it does not require an MPD to contain copies of all cited documents from a table of references if it contains hyperlinks to those documents. The key operating words in this rule are: "another resource is required to process or display an artifact SHOULD exist within the MPD."

   In some cases, it may not be possible to include all artifacts, even schemas, in an MPD without violating laws, regulations, or policies. For example, an [IEPD] may require use of a schema document that is not publicly accessible; it might be classified or controlled unclassified information (CUI). This is a valid reason for exception to Rule 7-9, Key MPD Resources Are Local Resources. If the [IEPD] is placed in the public domain, the author should omit the non-public schema document, and if appropriate, document the omission, and explain where and/or how the missing schema document can be obtained.

7.5. Duplication of Artifacts

   Within an MPD, the replication of files or entire file sets should be avoided. However, replication is allowed if a reasonable rationale exists. In some cases, file replication may make it easier to use, validate, implement, or automatically process an MPD. For example, multiple subsets and/or constraint sets may overlap in many identical schema documents. Yet, allowing this duplication may be easier or necessary to accommodate a validation tool, rather than removing duplicate schema documents, and forcing the tool to search for them. Whenever possible, use XML catalogs to coordinate schema assembly.

   

Appendix A. MPD Catalog XML Schema Document

   <?xml version="1.0" encoding="US-ASCII"?>
   <xs:schema
       ct:conformanceTargets="http://reference.niem.gov/niem/specification/naming-and-design-rules/3.0/#ExtensionSchemaDocument"
       targetNamespace="http://reference.niem.gov/niem/resource/mpd/catalog/3.0/"
       version="3.0"
       xmlns:appinfo="http://release.niem.gov/niem/appinfo/3.0/"
       xmlns:c="http://reference.niem.gov/niem/resource/mpd/catalog/3.0/"
       xmlns:ct="http://release.niem.gov/niem/conformanceTargets/3.0/"
       xmlns:nc="http://release.niem.gov/niem/niem-core/3.0/"
       xmlns:structures="http://release.niem.gov/niem/structures/3.0/"
       xmlns:term="http://release.niem.gov/niem/localTerminology/3.0/"
       xmlns:niem-xs="http://release.niem.gov/niem/proxy/xsd/3.0/"
       xmlns:xs="http://www.w3.org/2001/XMLSchema">
   
       <xs:import namespace="http://release.niem.gov/niem/structures/3.0/" schemaLocation="niem/structures/3.0/structures.xsd"/>
       <xs:import namespace="http://release.niem.gov/niem/niem-core/3.0/" schemaLocation="niem/niem-core/3.0/niem-core.xsd"/>
       <xs:import namespace="http://release.niem.gov/niem/proxy/xsd/3.0/" schemaLocation="niem/proxy/xsd/3.0/xs.xsd"/>
   
       <xs:annotation>
   
         <xs:documentation>Model Package Description (MPD) Catalog schema document. 
             defines an mpd-catalog.xml artifact for Model Package Descriptions (MPD).
             The purpose of this schema is to facilitate consistent declaration of MPD
   	  content, conformance targets, metadata, and lineage to process, display, 
   	  review, register, search, and discover MPDs efficiently. For IEPDs, this
             mpd-catalog schema provides instructions for validating IEPs to schemas. 
   	  This XML Schema document is supported by a subset of niem-core 3.0.
         </xs:documentation>
   
         <xs:appinfo>
           <term:LocalTerm term="EIEM"  literal="Enterprise Information Exchange Model"/>
           <term:LocalTerm term="EXI"   literal="Efficient XML Interchange"/>
           <term:LocalTerm term="IANA"  literal="Internet Assigned Numbers Authority"/>
           <term:LocalTerm term="ID"    literal="Identifier"/>
           <term:LocalTerm term="IEP"   literal="Information Exchange Package" 
                                        definition="an instance XML document"/>
           <term:LocalTerm term="IEPD"  literal="Information Exchange Package 
                                                   Documentation"/>
           <term:LocalTerm term="MIME"  literal="Multipurpose Internet Mail Extension"/>
           <term:LocalTerm term="MPD"   literal="Model Package Description"/>
           <term:LocalTerm term="OASIS" literal="Organization for the Advancement
                                                   of Structured Information Standards"/>
           <term:LocalTerm term="SSGT"  literal="Schema Subset Generation Tool"/>
           <term:LocalTerm term="URI"   literal="Uniform Resource Identifier"/>
           <term:LocalTerm term="Wantlist" definition="An XML file that represents a 
                   NIEM schema document subset; used by NIEM Schema Subset Generation 
                   Tool to input/output a schema document subset"/>
         </xs:appinfo> 
   
       </xs:annotation>
   
       <xs:element name="Catalog" type="c:CatalogType">
         <xs:annotation>
           <xs:documentation>An MPD catalog that describes MPD artifacts and metadata.
           </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:complexType name="CatalogType">
         <xs:annotation>
           <xs:documentation>A data type for an MPD catalog.</xs:documentation>
         </xs:annotation>
         <xs:complexContent>
           <xs:extension base="structures:ObjectType">
             <xs:sequence>
               <xs:element ref="c:MPD"/>
             </xs:sequence>
           </xs:extension>
         </xs:complexContent>
       </xs:complexType>
   
       <xs:element name="MPD" type="c:MPDType">
         <xs:annotation>
           <xs:documentation>A Model Package Description (MPD).</xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:complexType name="MPDType">
         <xs:annotation>
           <xs:documentation>A data type for an MPD.</xs:documentation>
         </xs:annotation>
         <xs:complexContent>
           <xs:extension base="structures:ObjectType">
             <xs:sequence>
              <xs:element ref="nc:DescriptionText"        minOccurs="0"/>
              <xs:element ref="c:MPDInformation"   minOccurs="0"/>
              <xs:element ref="c:IEPConformanceTarget" minOccurs="0" maxOccurs="unbounded"/>
              <xs:element ref="c:ArtifactOrArtifactSet" minOccurs="0" maxOccurs="unbounded"/>
             </xs:sequence>
             <xs:attribute ref="c:mpdURI"          use="required"/>
             <xs:attribute ref="c:mpdClassURIList" use="required"/>
             <xs:attribute ref="c:mpdName"         use="required"/>
             <xs:attribute ref="c:mpdVersionID"    use="required"/>
           </xs:extension>
         </xs:complexContent>
       </xs:complexType>
   
       <xs:element name="ArtifactOrArtifactSet" abstract="true">
         <xs:annotation>
                 <xs:documentation>
                    A data concept for a file or file set in an MPD.
                 </xs:documentation>
         </xs:annotation>
       </xs:element>
   
   
   <!-- File artifact classifiers for a table of contents =========================== -->
   
       <xs:element name="File" type="c:FileType" substitutionGroup="c:ArtifactOrArtifactSet">
         <xs:annotation>
                 <xs:documentation>
                    A generic electronic file artifact in an MPD; a file stored on a computer system.
                 </xs:documentation>
         </xs:annotation>
         </xs:element>
   
       <xs:complexType name="FileType">
         <xs:annotation>
           <xs:documentation>A data type for an MPD file artifact.</xs:documentation>
         </xs:annotation>
         <xs:complexContent> 
           <xs:extension base="structures:ObjectType">
             <xs:sequence>
               <xs:element ref="c:RequiredFile"     minOccurs="0" maxOccurs="unbounded"/>
               <xs:element ref="nc:DescriptionText" minOccurs="0"/>
             </xs:sequence>
             <xs:attribute ref="c:pathURI"           use="required"/>
             <xs:attribute ref="c:mimeMediaTypeText" use="optional"/>
             <xs:attribute ref="c:externalURI"       use="optional"/>
           </xs:extension>
         </xs:complexContent>
       </xs:complexType>
   
       <xs:element name="XMLCatalog" type="c:FileType" substitutionGroup="c:ArtifactOrArtifactSet">
         <xs:annotation>
                 <xs:documentation>
                    An MPD artifact that is an OASIS XML catalog.
                 </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:element name="MPDChangeLog" type="c:FileType" substitutionGroup="c:ArtifactOrArtifactSet">
         <xs:annotation>
                 <xs:documentation>
                    An MPD artifact that contains a record of the MPD changes.
                 </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:element name="ReadMe" type="c:FileType" substitutionGroup="c:ArtifactOrArtifactSet">
         <xs:annotation>
            <xs:documentation>An MPD read-me artifact.</xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:element name="IEPSampleXMLDocument" type="c:FileType" substitutionGroup="c:ArtifactOrArtifactSet">
         <xs:annotation>
                 <xs:documentation>
                    An example MPD instance XML document or IEP artifact.
                 </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:element name="BusinessRulesArtifact" type="c:FileType" substitutionGroup="c:ArtifactOrArtifactSet">
         <xs:annotation>
                 <xs:documentation>
                    An MPD artifact that contains business rules 
                    and constraints on exchange content.
                 </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:element name="XMLSchemaDocument" type="c:FileType" substitutionGroup="c:ArtifactOrArtifactSet">
         <xs:annotation>
                 <xs:documentation>
                    An MPD artifact that is an XML schema document (i.e., an XSD that
                    is not necessarily a NIEM subset, extension, or reference schema).
                 </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:element name="ExternalSchemaDocument" type="c:FileType" substitutionGroup="c:XMLSchemaDocument">
         <xs:annotation>
                 <xs:documentation>
                    An MPD artifact that is a schema document external to NIEM.
                 </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:element name="ExtensionSchemaDocument" type="c:FileType" substitutionGroup="c:XMLSchemaDocument">
         <xs:annotation>
           <xs:documentation>An MPD artifact that is a NIEM extension schema document.
           </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:element name="SubsetSchemaDocument" type="c:FileType" substitutionGroup="c:XMLSchemaDocument">
         <xs:annotation>
           <xs:documentation>An MPD artifact that is a subset schema document.
           </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:element name="ReferenceSchemaDocument" type="c:FileType" substitutionGroup="c:XMLSchemaDocument">
         <xs:annotation>
           <xs:documentation>An MPD artifact that is a reference schema document (from a release, domain update, or core update).
           </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:element name="EXIXMLSchema" type="c:XMLSchemaType" substitutionGroup="c:ArtifactOrArtifactSet">
         <xs:annotation>
                 <xs:documentation>
                         An XML Schema to be used for EXI serialization of an IEP Class.
                 </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:element name="Wantlist" type="c:FileType" substitutionGroup="c:ArtifactOrArtifactSet">
         <xs:annotation>
           <xs:documentation>An MPD artifact that represents a NIEM schema subset 
           and is used as an import or export for the NIEM SSGT.</xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:element name="ConformanceAssertion" type="c:FileType" substitutionGroup="c:ArtifactOrArtifactSet">
         <xs:annotation>
           <xs:documentation>An MPD artifact that is a signed declaration 
           that a NIEM IEPD or EIEM is NIEM-conformant.</xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:element name="ConformanceReport" type="c:FileType" substitutionGroup="c:ArtifactOrArtifactSet">
         <xs:annotation>
           <xs:documentation>
   	  An MPD artifact either auto-generated by a NIEM-aware software tool or manually prepared 
   	  that checks NIEM conformance and/or quality and renders a detailed report of results.
   	  This report may also be an auto-generated and manually prepared hybrid artifact. 
           </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:element name="SchematronSchema" type="c:FileType" substitutionGroup="c:ArtifactOrArtifactSet">
         <xs:annotation>
           <xs:documentation>A Schematron schema document.</xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:element name="RelaxNGSchema" type="c:FileType" substitutionGroup="c:ArtifactOrArtifactSet">
         <xs:annotation>
           <xs:documentation>A RelaxNG schema.</xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:element name="Documentation" type="c:FileType" substitutionGroup="c:ArtifactOrArtifactSet">
         <xs:annotation>
            <xs:documentation>
                   An MPD artifact that is a form of explanatory documentation.
            </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:element name="ApplicationInfo" type="c:FileType" substitutionGroup="c:ArtifactOrArtifactSet">
         <xs:annotation>
                 <xs:documentation>
                   An MPD artifact that is used by a software tool (e.g., import, export, input, output, etc.).
                 </xs:documentation>
         </xs:annotation>
       </xs:element>
   
   
   <!-- For declaring sets of dependent artifacts =================================== -->
   
       <xs:element name="RequiredFile" type="c:FileType">
         <xs:annotation>
                 <xs:documentation>
                   An MPD file artifact that another artifact depends on and should not be separated from.
                 </xs:documentation>
         </xs:annotation>
       </xs:element>
   
   
   <!-- Artifact Set Classifiers ==================================================== -->
   
       <xs:element name="FileSet" type="c:FileSetType" substitutionGroup="c:ArtifactOrArtifactSet">
         <xs:annotation>
                 <xs:documentation>
                   A generic MPD artifact set; used to group artifacts that are not accounted for by other set classifiers.
                 </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:complexType name="FileSetType">
         <xs:annotation>
           <xs:documentation>A data type for a set of MPD file artifacts.</xs:documentation>
         </xs:annotation>
         <xs:complexContent>
           <xs:extension base="structures:ObjectType">
             <xs:sequence>
               <xs:element ref="nc:DescriptionText" minOccurs="0"/>
               <xs:element ref="c:ArtifactOrArtifactSet" minOccurs="0" maxOccurs="unbounded"/>
             </xs:sequence>
             <xs:attribute ref="c:pathURI"     use="optional"/>
             <xs:attribute ref="c:externalURI" use="optional"/>
           </xs:extension>
         </xs:complexContent>
       </xs:complexType>
   
       <xs:element name="SchemaDocumentSet" type="c:SchemaDocumentSetType" substitutionGroup="c:ArtifactOrArtifactSet">
         <xs:annotation>
                 <xs:documentation>
                         An MPD artifact set that may include subset schema documents, extension and external schema documents, and other supporting artifacts.
                 </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:element name="ConstraintSchemaDocumentSet" type="c:SchemaDocumentSetType" substitutionGroup="c:ArtifactOrArtifactSet">
         <xs:annotation>
                 <xs:documentation>
                         An MPD artifact set of constraint schema documents and other supporting artifacts.
                 </xs:documentation>
         </xs:annotation>
       </xs:element>
   
      <xs:complexType name="SchemaDocumentSetType">
         <xs:annotation>
                 <xs:documentation>
                         A data type for an MPD artifact set that may include subset schema documents, extension schema documents, and external schema documents or constraint schema documents.
                 </xs:documentation>
         </xs:annotation>
         <xs:complexContent>
                 <xs:extension base="c:FileSetType"/>
         </xs:complexContent>
       </xs:complexType>
   
   
   <!-- Primitives ================================================================== -->
   
       <xs:attribute name="mpdURI" type="xs:anyURI">
         <xs:annotation>
                 <xs:documentation>
                         A globally unique identifier (URI) for an MPD.
                 </xs:documentation>
         </xs:annotation>
       </xs:attribute>
   
       <xs:attribute name="mpdName" type="c:MPDNameSimpleType">
         <xs:annotation>
           <xs:documentation>A descriptive label or title for an MPD.</xs:documentation>
         </xs:annotation>
       </xs:attribute>
   
       <xs:simpleType name="MPDNameSimpleType">
         <xs:annotation>
                   <xs:documentation>
                           A data type for an MPD name, label, or title.
                   </xs:documentation>
         </xs:annotation>
         <xs:restriction base="xs:token">
           <xs:pattern value="[A-Za-z]([-_ ]?[A-Za-z0-9]+)*"/>
         </xs:restriction>
       </xs:simpleType>
   
       <xs:attribute name="mpdVersionID" type="c:MPDVersionIDSimpleType">
         <xs:annotation>
                   <xs:documentation>
                           An identifier that distinguishes releases of a given MPD.
                   </xs:documentation>
         </xs:annotation>
       </xs:attribute>
   
       <xs:simpleType name="MPDVersionIDSimpleType">
         <xs:annotation>
                   <xs:documentation>
                           A data type for an identifier that distinguishes releases of a given MPD.
                   </xs:documentation>
         </xs:annotation>
         <xs:restriction base="xs:token">
           <xs:pattern value="[0-9]+(\.[0-9]+)*((alpha|beta|rc|rev)[0-9]+)?"/>
         </xs:restriction>
       </xs:simpleType>
   
   
   <!-- =========================================================================== -->
   
       <xs:attribute name="mpdClassURIList" type="c:MPDClassURIListSimpleType">
         <xs:annotation>
                   <xs:documentation>
                           A list of one or more URIs that each represents an MPD class to which the MPD claims conformance.
                   </xs:documentation>
         </xs:annotation>
       </xs:attribute>
   
       <xs:simpleType name="MPDClassURIListSimpleType">
           <xs:annotation>
                     <xs:documentation>
                           A data type that ensures at least one class is identified as an MPD conformance target.
                     </xs:documentation>
           </xs:annotation>
           <xs:restriction base="c:MPDClassListSimpleType">
               <xs:minLength value="1"/>
           </xs:restriction>
       </xs:simpleType>
   
       <xs:simpleType name="MPDClassListSimpleType">
           <xs:annotation>
                   <xs:documentation>
                           A data type for one or more URIs that are MPD conformance target classes.
                   </xs:documentation>
           </xs:annotation>
           <xs:list itemType="xs:anyURI"/>
       </xs:simpleType>
   
   
   <!-- =========================================================================== -->
   
       <xs:attribute name="pathURI" type="xs:anyURI">
         <xs:annotation>
                 <xs:documentation>
                         A URI for the pathname of a local artifact relative to the MPD root directory.
                 </xs:documentation>
         </xs:annotation>
       </xs:attribute>
   
       <xs:attribute name="externalURI" type="xs:anyURI">
         <xs:annotation>
                 <xs:documentation>
                         A globally unique identifier (URI) for an artifact in another MPD that is reused by this MPD.
                 </xs:documentation>
         </xs:annotation>
       </xs:attribute>
   
       <xs:attribute name="mimeMediaTypeText" type="xs:string">
         <xs:annotation>
                 <xs:documentation>
                         A classification for an MPD file artifact from the IANA MIME media classes: http://www.iana.org/assignments/media-types.
                 </xs:documentation>
         </xs:annotation>
       </xs:attribute>
   
       <xs:complexType name="RelationshipType">
         <xs:annotation>
                 <xs:documentation>
                         A data type for a reference to another MPD related to this MPD.
                 </xs:documentation>
         </xs:annotation>
         <xs:complexContent>
           <xs:extension base="structures:ObjectType">
             <xs:sequence>
               <xs:element ref="nc:DescriptionText" minOccurs="0"/>
             </xs:sequence>
             <xs:attribute ref="c:relationshipCode" use="required"/>
             <xs:attribute ref="c:resourceURI"      use="required"/>
           </xs:extension>
         </xs:complexContent>
       </xs:complexType>
   
       <xs:attribute name="resourceURI" type="xs:anyURI">
         <xs:annotation>
                 <xs:documentation>
                         A globally unique identifier (URI) for another MPD or document to which this MPD relates.
                 </xs:documentation>
         </xs:annotation>
       </xs:attribute>
   
       <xs:attribute name="relationshipCode" type="c:RelationshipCodeSimpleType">
         <xs:annotation>
                 <xs:documentation>
                         A classification or reason for the connectedness between this MPD and the resource referenced in resourceURI.
                 </xs:documentation>
         </xs:annotation>
       </xs:attribute>
   
       <xs:simpleType name="RelationshipCodeSimpleType">
         <xs:annotation>
                 <xs:documentation>
                         A data type for a classification of the relationship between MPDs.
                 </xs:documentation>
         </xs:annotation>
           <xs:restriction base="xs:token">
               <xs:enumeration value="version_of">
                 <xs:annotation>
                         <xs:documentation>
                                 A relationshipCode value for indicating that this MPD is a different version of the MPD referenced in resourceURI.  This code value is only needed in cases where significant name changes might obscure the relationship to the previous version.  For example, NIEM Justice 4.1 is a version of GJXDM 3.0.3.
                         </xs:documentation>
                   </xs:annotation>
               </xs:enumeration>
               <xs:enumeration value="specializes">
                 <xs:annotation>
                         <xs:documentation>
                                 A relationshipCode value for indicating that this MPD is a specialization of the MPD referenced in resourceURI.  This value is the inverse of generalizes.
                         </xs:documentation>
                 </xs:annotation>
               </xs:enumeration>
               <xs:enumeration value="generalizes">
                 <xs:annotation>
                         <xs:documentation>
                                 A relationshipCode value for indicating that this MPD is a generalization of the MPD referenced in resourceURI.  This value is the inverse of specializes.
                         </xs:documentation>
                   </xs:annotation>
               </xs:enumeration>
               <xs:enumeration value="supersedes">
                 <xs:annotation>
                         <xs:documentation>
                                 A relationshipCode value for indicating that this MPD replaces the MPD referenced in resourceURI.
                         </xs:documentation>
                 </xs:annotation>
               </xs:enumeration>
               <xs:enumeration value="deprecates">
                 <xs:annotation>
                         <xs:documentation>
                                 A relationshipCode value for indicating that content in this MPD is preferred over content in the MPD referenced in resourceURI; and at some time in the future will supersede the MPD referenced in resourceURI.
                         </xs:documentation>
                 </xs:annotation>
               </xs:enumeration>
               <xs:enumeration value="adapts">
                 <xs:annotation>
                         <xs:documentation>
                                 A relationshipCode value for indicating that this MPD is an adaptation of the MPD referenced in resourceURI.
                         </xs:documentation>
                 </xs:annotation>
               </xs:enumeration>
               <xs:enumeration value="updates">
                 <xs:annotation>
                         <xs:documentation>
                                 A relationshipCode value for indicating that this MPD is an incremental update to the resource referenced in resourceURI.  Used by a core or domain update to identify the domain schema in a NIEM release being incrementally updated (not replaced).
                         </xs:documentation>
                 </xs:annotation>
               </xs:enumeration>
               <xs:enumeration value="conforms_to">
                 <xs:annotation>
                         <xs:documentation>
                                 A relationshipCode value for indicating that this MPD conforms to the specification or standard referenced in resourceURI.
                         </xs:documentation>
                 </xs:annotation>
               </xs:enumeration>
               <xs:enumeration value="derives_from">
                 <xs:annotation>
                         <xs:documentation>
                                 A relationshipCode value for indicating that this MPD has been derived from another; used to indicate an IEPD is derived from an EIEM (may have other uses as well).
                         </xs:documentation>
                 </xs:annotation>
               </xs:enumeration>
           </xs:restriction>
       </xs:simpleType>
   
   
   <!-- IEP Conformance Targets ==================================================== -->
   
       <xs:element name="IEPConformanceTarget" type="c:IEPConformanceTargetType">
         <xs:annotation>
                 <xs:documentation>
                         A class or category of IEPs which has a set of validity constraints and a unique identifier. Every IEP is an instance of one or more IEP Conformance Targets.
                 </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:complexType name="IEPConformanceTargetType">
         <xs:annotation>
                 <xs:documentation>
                         A data type for a class or category of IEP, which has a set of validity constraints and a unique identifier.
                 </xs:documentation>
         </xs:annotation>
         <xs:complexContent>
           <xs:extension base="structures:ObjectType">
             <xs:sequence>
               <xs:element ref="nc:DescriptionText" minOccurs="0"/>
               <xs:element ref="c:ValidityConstraintWithContext" minOccurs="0" maxOccurs="unbounded"/>
               <xs:element ref="c:ArtifactOrArtifactSet" minOccurs="0" maxOccurs="unbounded"/>
             </xs:sequence>
           </xs:extension>
         </xs:complexContent>
       </xs:complexType>
   
       <xs:element name="ValidityConstraintWithContext" abstract="true">
         <xs:annotation>
                 <xs:documentation>
                         A data concept for a rule or instructions for validating an IEP candidate (XML document) using some context within that XML document.
                 </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:element name="ValidityConstraint" abstract="true" substitutionGroup="c:ValidityConstraintWithContext">
         <xs:annotation>
                 <xs:documentation>
                         A data concept for a rule or instructions for validating an IEP candidate.
                 </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:element name="ValidityContext" type="c:ValidityContextType" substitutionGroup="c:ValidityConstraintWithContext">
         <xs:annotation>
                 <xs:documentation>
                         A rule or instructions for validating an IEP candidate within context defined by an XPath expression.
                 </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:complexType name="ValidityContextType">
         <xs:annotation>
                 <xs:documentation>
                         A data type for a rule or instructions for validating an IEP candidate within context defined by an XPath expression.
                 </xs:documentation>
         </xs:annotation>
         <xs:complexContent>
           <xs:extension base="structures:ObjectType">
             <xs:sequence>
               <xs:element ref="nc:DescriptionText" minOccurs="0"/>
               <xs:element ref="c:ValidityConstraint" maxOccurs="unbounded"/>
             </xs:sequence>
             <xs:attribute ref="c:xPathText" use="required"/>
           </xs:extension>
         </xs:complexContent>
       </xs:complexType>
    
   
   <!-- Validity Constraints ======================================================== -->
   
       <xs:element name="ValidToXPath" type="c:XPathType" substitutionGroup="c:ValidityConstraint">
         <xs:annotation>
                 <xs:documentation>
                         A validity constraint that has a an XPath expression that MUST have an effective Boolean value of "TRUE" when applied to a valid IEP. 
                 </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:complexType name="XPathType">
         <xs:annotation>
           <xs:documentation>A data type for an XPath expression.</xs:documentation>
         </xs:annotation>
         <xs:complexContent>
           <xs:extension base="structures:ObjectType">
             <xs:sequence>
               <xs:element ref="nc:DescriptionText" minOccurs="0"/>
             </xs:sequence>
             <xs:attribute ref="c:xPathText" use="required"/>
           </xs:extension>
         </xs:complexContent>
       </xs:complexType>
   
       <xs:attribute name="xPathText" type="xs:string">
         <xs:annotation>
           <xs:documentation>An XPath expression.</xs:documentation>
         </xs:annotation>
       </xs:attribute>
   
       <xs:element name="XMLSchemaValid" type="c:XMLSchemaType" substitutionGroup="c:ValidityConstraint">
         <xs:annotation>
                 <xs:documentation>
                         A validity constraint that indicates that an artifact must be locally XML Schema valid against an XML schema described/asssembled using one or more XML catalog documents or (more explicitly) one or more XML schema documents.
                 </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:complexType name="XMLSchemaType">
         <xs:annotation>
   	      <xs:documentation>A data type for a validity constraint that  indicating an XML Schema against which an artifact may be validated, or which can be used for other purposes.  c:XMLSchemaDocument identifies the root or starting XML schema document.
                 </xs:documentation>
         </xs:annotation>
         <xs:complexContent>
           <xs:extension base="structures:ObjectType">
             <xs:sequence>
               <xs:element ref="nc:DescriptionText"  minOccurs="0"/>
               <xs:element ref="c:XMLCatalog"          minOccurs="0" maxOccurs="unbounded"/>
               <xs:element ref="c:XMLSchemaDocument" minOccurs="0" maxOccurs="unbounded"/>
             </xs:sequence>
           </xs:extension>
         </xs:complexContent>
       </xs:complexType>
   
       <xs:element name="SchematronValid" type="c:SchematronValidationType" substitutionGroup="c:ValidityConstraint">
         <xs:annotation>
   	      <xs:documentation>A validity constraint that indicates that an artifact must be valid against the rules carried by a Schematron file, starting with the identified validation roots.
                 </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:complexType name="SchematronValidationType">
         <xs:annotation>
                 <xs:documentation>
                         A data type for a Schematron validation constraint, indicating a Schematron schema document against which an artifact may be validated as well as a description of the validation roots for assessment of validity.
                 </xs:documentation>
         </xs:annotation>
         <xs:complexContent>
           <xs:extension base="structures:ObjectType">
             <xs:sequence>
               <xs:element ref="nc:DescriptionText" minOccurs="0"/>
               <xs:element ref="c:SchematronSchema"/>
             </xs:sequence>
           </xs:extension>
         </xs:complexContent>
       </xs:complexType>
   
       <xs:element name="RelaxNGValid" type="c:RelaxNGValidationType" substitutionGroup="c:ValidityConstraint">
         <xs:annotation>
                 <xs:documentation>
                         A validity constraint that indicates that an artifact must be valid against the rules carried by a RelaxNG schema.
                 </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:complexType name="RelaxNGValidationType">
         <xs:annotation>
                 <xs:documentation>
                         A data type for a RelaxNG validation constraint, indicating a RelaxNG schema document against which an artifact may be validated, as well as a description of the validation roots for assessment of validity.
                 </xs:documentation>
         </xs:annotation>
         <xs:complexContent>
           <xs:extension base="structures:ObjectType">
             <xs:sequence>
               <xs:element ref="nc:DescriptionText" minOccurs="0"/>
               <xs:element ref="c:RelaxNGSchema"/>
             </xs:sequence>
           </xs:extension>
         </xs:complexContent>
       </xs:complexType>
   
       <xs:element name="HasDocumentElement" type="c:QualifiedNamesType" substitutionGroup="c:ValidityConstraintWithContext">
         <xs:annotation>
                 <xs:documentation>
                        A validity constraint that indicates that an artifact has a document element with a name that is one of the given qualified names.
                 </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:complexType name="QualifiedNamesType">
         <xs:annotation>
           <xs:documentation>A data type for a set of qualified names.</xs:documentation>
         </xs:annotation>
         <xs:complexContent>
           <xs:extension base="structures:ObjectType">
             <xs:sequence>
               <xs:element ref="nc:DescriptionText" minOccurs="0"/>
             </xs:sequence>
             <xs:attribute ref="c:qualifiedNameList" use="required"/>
           </xs:extension>
         </xs:complexContent>
       </xs:complexType>
   
       <xs:attribute name="qualifiedNameList" type="c:QualifiedNameListSimpleType">
         <xs:annotation>
           <xs:documentation>A list of qualified names.</xs:documentation>
         </xs:annotation>
       </xs:attribute>
   
       <xs:simpleType name="QualifiedNameListSimpleType">
         <xs:annotation>
                 <xs:documentation>A data type for a list of qualified names.</xs:documentation>
         </xs:annotation>
         <xs:list itemType="xs:QName"/>
       </xs:simpleType>
   
       <xs:element name="ConformsToConformanceTarget" type="c:ConformanceTargetType" substitutionGroup="c:ValidityConstraint">
         <xs:annotation>
   	      <xs:documentation>
                         A validity constraint that indicates that an artifact must conform to the given conformance target.
                 </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:complexType name="ConformanceTargetType">
         <xs:annotation>
                 <xs:documentation>
                         A data type for identifying and describing a conformance target.
                 </xs:documentation>
         </xs:annotation>
         <xs:complexContent>
           <xs:extension base="structures:ObjectType">
             <xs:sequence>
               <xs:element ref="nc:DescriptionText" minOccurs="0"/>
             </xs:sequence>
             <xs:attribute ref="c:conformanceTargetURI" use="required"/>
           </xs:extension>
         </xs:complexContent>
       </xs:complexType>
   
       <xs:attribute name="conformanceTargetURI" type="xs:anyURI">
         <xs:annotation>
           <xs:documentation>A URI for a conformance target.</xs:documentation>
         </xs:annotation>
       </xs:attribute>
   
       <xs:element name="ConformsToRule" type="c:TextRuleType" substitutionGroup="c:ValidityConstraint">
         <xs:annotation>
                 <xs:documentation>
                         A validity constraint that indicates that an artifact must conform to the given text rule, drafted in a human language.
                 </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:complexType name="TextRuleType">
         <xs:annotation>
                 <xs:documentation>
                         A data type for a rule drafted in a human language.
                 </xs:documentation>
         </xs:annotation>
         <xs:complexContent>
           <xs:extension base="structures:ObjectType">
             <xs:sequence>
               <xs:element ref="nc:DescriptionText" minOccurs="0"/>
               <xs:element ref="c:RuleText"/>
             </xs:sequence>
           </xs:extension>
         </xs:complexContent>
       </xs:complexType>
   
       <xs:element name="RuleText" type="nc:TextType"> 
         <xs:annotation>
           <xs:documentation>A rule written in a human language.</xs:documentation>
         </xs:annotation>
       </xs:element>
   
   
   <!-- Metadata ==================================================================== -->
   
       <xs:element name="MPDInformation" type="c:MPDInformationType">
         <xs:annotation>
           <xs:documentation>A set of descriptive data about an MPD.</xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:complexType name="MPDInformationType">
         <xs:annotation>
                 <xs:documentation>
                         A data type for a set of descriptive data about an MPD.
                 </xs:documentation>
         </xs:annotation>
         <xs:complexContent>
           <xs:extension base="structures:ObjectType">
             <xs:sequence>
               <xs:element ref="c:AuthoritativeSource" minOccurs="0"/>
               <xs:element ref="c:CreationDate" minOccurs="0"/>
               <xs:element ref="c:LastRevisionDate" minOccurs="0"/>
               <xs:element ref="c:StatusText" minOccurs="0"/>
               <xs:element ref="c:Relationship" minOccurs="0" maxOccurs="unbounded"/>
               <xs:element ref="c:KeywordText" minOccurs="0" maxOccurs="unbounded"/>
               <xs:element ref="c:DomainText" minOccurs="0" maxOccurs="unbounded"/>
               <xs:element ref="c:PurposeText" minOccurs="0" maxOccurs="unbounded"/>
               <xs:element ref="c:ExchangePatternText" minOccurs="0" maxOccurs="unbounded"/>
               <xs:element ref="c:ExchangePartnerName" minOccurs="0" maxOccurs="unbounded"/>
               <xs:element ref="c:ExtendedInformation" minOccurs="0" maxOccurs="unbounded"/>
             </xs:sequence>
           </xs:extension>
         </xs:complexContent>
       </xs:complexType>
   
       <xs:element name="ExtendedInformation" abstract="true">
         <xs:annotation>
                 <xs:documentation>
                         A data concept for a user-defined descriptive data about an MPD.
                 </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:element name="AuthoritativeSource" type="nc:EntityType">
         <xs:annotation>
                 <xs:documentation>
                         An official sponsoring or authoring organization responsible for an MPD.
                 </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:element name="CreationDate" type="niem-xs:date">
         <xs:annotation>
           <xs:documentation>A date this MPD was published.</xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:element name="LastRevisionDate" type="niem-xs:date">
         <xs:annotation>
                 <xs:documentation>
                         A date the latest changes to an MPD were published (i.e., CreationDate of previous version).
                 </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:element name="StatusText"   type="niem-xs:string">
         <xs:annotation>
                 <xs:documentation>
                         A description of the current state of this MPD in development; may also project future plans for the MPD.
                 </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:element name="Relationship" type="c:RelationshipType">
         <xs:annotation>
           <xs:documentation>A reference to another MPD related to this MPD.</xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:element name="KeywordText"  type="niem-xs:string">
         <xs:annotation>
                 <xs:documentation>
                         A common alias, term, or phrase that would help to facilitate search and discovery of this MPD.
                 </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:element name="DomainText"   type="niem-xs:string">
         <xs:annotation>
                 <xs:documentation>
                         A description of the environment or NIEM Domain in which this MPD is applicable or used.
                 </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:element name="PurposeText"  type="niem-xs:string">
         <xs:annotation>
                 <xs:documentation>
                         A description of the intended usage and reason for which an MPD exists.
                 </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:element name="ExchangePatternText" type="niem-xs:string">
         <xs:annotation>
                 <xs:documentation>
                         A description of a transactional or design pattern used for this IEPD (generally, only applicable to IEPDs).
                 </xs:documentation>
         </xs:annotation>
       </xs:element>
   
       <xs:element name="ExchangePartnerName" type="niem-xs:string">
         <xs:annotation>
                 <xs:documentation>
                         A name of an entity or organization that uses this MPD (generally, only applicable to IEPDs).
                 </xs:documentation>
         </xs:annotation>
       </xs:element>
   
   </xs:schema>
   
   

      

Appendix B. Example MPD Catalog Document for Cursor on Target

   Below is a simple example of an MPD catalog document for a Cursor on Target [IEPD]. The entire [IEPD] is contained in the [NIEM MPD Toolkit]

   <?xml version="1.0" encoding="US-ASCII"?>
   <c:Catalog 
       xmlns:cot="http://example.com/cot-niem/0.9/"
       xmlns:c="http://reference.niem.gov/niem/resource/mpd/catalog/3.0/"
       xmlns:structures="http://release.niem.gov/niem/structures/3.0/"
       xmlns:nc="http://release.niem.gov/niem/niem-core/3.0/">
       <c:MPD 
           c:mpdURI="http://example.com/cot-iepd/0.9rc2/" 
           c:mpdClassURIList=
             "http://reference.niem.gov/niem/specification/model-package-description/3.0/#MPD
             http://reference.niem.gov/niem/specification/model-package-description/3.0/#IEPD"
           c:mpdName="cot-iepd" 
           c:mpdVersionID="0.9rc1">
           <c:MPDInformation>
               <c:AuthoritativeSource> 
                   <nc:EntityOrganization>
                       <nc:OrganizationName>CoT Program Office</nc:OrganizationName>
                       <nc:OrganizationPrimaryContactInformation>
   			    <nc:ContactWebsiteURI>
   				    https://partners.mitre.org/sites/CoTUserGroup/
   			    </nc:ContactWebsiteURI>
                       </nc:OrganizationPrimaryContactInformation>
                   </nc:EntityOrganization>
               </c:AuthoritativeSource>
               <c:CreationDate>2014-08-04</c:CreationDate>
               <c:StatusText>Release Candidate</c:StatusText>
           </c:MPDInformation>
           <c:IEPConformanceTarget structures:id="CoT-NIEM-IEP">
               <nc:DescriptionText>
                   An IEP class equivalent to Cursor-on-Target 2.0 messages
               </nc:DescriptionText>
               <c:HasDocumentElement c:qualifiedNameList="cot:Event"/>
               <c:XMLSchemaValid>
                   <c:XMLCatalog c:pathURI="base-xsd/xml-catalog.xml"/>
               </c:XMLSchemaValid>
               <c:SchematronValid>
                   <c:SchematronSchema c:pathURI="schematron/business-rules.sch"/>
               </c:SchematronValid>
               <c:EXIXMLSchema>
                   <c:XMLCatalog c:pathURI="exi-xsd/exi-xml-catalog.xml"/>
                   <c:XMLSchemaDocument c:pathURI="extension/cot-niem.xsd"/>
               </c:EXIXMLSchema>
               <c:IEPSampleXMLDocument c:pathURI="iep-samples/iep1.xml"/>
           </c:IEPConformanceTarget>
           <c:ReadMe c:pathURI="00-README.txt"/>
           <c:MPDChangeLog c:pathURI="01-changelog.txt"></c:MPDChangeLog>
           <c:ConformanceAssertion c:pathURI="02-conformance.txt"/>
           <c:Wantlist c:pathURI="base-xsd/niem/wantlist.xml"/>
           <c:ExtensionSchemaDocument c:pathURI="base-xsd/extension/cot-niem.xsd"/>
           <c:ExtensionSchemaDocument c:pathURI="base-xsd/extension/cot-niem-codes.xsd"/>
           <c:ReferenceSchemaDocument c:pathURI="base-xsd/extension/milops-future-ref.xsd"/>
       </c:MPD>
   </c:Catalog>
   

      

Appendix C. Common MPD Artifacts

   Notes:

      *  (MPD) in artifact name indicates a required artifact for all [MPDs].

      *  (IEPD) in artifact name indicates a required artifact for an [IEPD].

      *  (ref) indicates name is hyperlinked to a defined term in the specification.

      *  * in filename syntax indicates wildcard.

      Artifact name|Filename syntax|Definition

      (MPD) [MPD catalog document]|mpd-catalog.xml|(ref)

      (MPD) [change log]|*.*|(ref)

      (IEPD) [readme artifact]|*.*|(ref)

      (IEPD) [conformance assertion]|*.*|(ref)

      [XML catalog document]|*.xml|(ref)

      conformance report|*.*|a formal detailed report on conformance generated by a NIEM-aware tool or manually prepared (or both)

      MPD catalog extension [XML catalog document]|mpd-catalog-extension-xml-catalog.xml|an XML catalog that identifies an MPD catalog extension schema document (ref)

      MPD catalog [extension schema document]|*.xsd|a XML schema document that extends an MPD catalog schema (ref)

      [subset schema document]|*.xsd|(ref)

      [NIEM wantlist]|*.xml|(ref)

      [extension schema document]|*.xsd|(ref)

      [external schema document]|*.xsd|(ref)

      [reference schema document]|*.xsd|(ref)

      IEP sample [XML document]|*.xml|an XML document instance that exemplifies an [IEP conformance target] defined by a c:IEPConformanceTarget (ref)

      Schematron schema document|*.sch|a business rule schema in [ISO Schematron] format

      RelaxNG schema document|*.rng|a business rule schema in [ISO RelaxNG] format

      documentation|*.*|a textual or graphic artifact containing notes, instructions, guidance, etc.

      application information|*.*|a tool-specific artifact used, generated, exported, imported, etc. by a specific tool; includes models, databases, configuration files, graphics, etc.

      

Appendix D. Conformance Assertion Example

   A NIEM conformance assertion is a required artifact for an [IEPD]. The following is a simple example of a conformance assertion (in this case, a self assertion by the author, but with assistance from colleagues. The concept is to provide implementers with some information that indicates how well an [IEPD] has been checked for quality and conformance with respect to XML Schema and NIEM. The assertion can be as simple as the assertion clause. However, clearly the more detail that is provided, the stronger the case for conformance and quality will be.

   Images are omitted from this edition.

Appendix E. Guidance for IEPD Directories (non-normative)

   NIEM releases (and their associated core supplements) and domain updates generally follow a consistent directory organization. When employing a release, its supplements, and updates within IEPDs whether as-is or as subsets, developers are encouraged to maintain their original directory structures. However, aside from applicable rules previously stated in the preceding sections, there are no normative rules for organizing directories within IEPDs.

   Guidance for directory structuring may be useful to authors, especially in the case of a relatively simple [IEPD] with a single schema document subset, and a few extension and external schema documents. The following are common non-normative practices for [IEPD] directories:

      1.  Create a root directory for the [IEPD] from the name and version identifier of the [IEPD]. For example my_iepd-3.2rev4. (Rule 7-3, MPD Archive Uncompresses to a Single Root Directory)

      2.  For every MPD, an mpd-catalog.xml artifact (Rule 5-1, MPD Has an mpd-catalog.xml in its Root Directory) is required to be in the [MPD root directory]

      3.  If extending the [MPD catalog document], then per Rule 5-3, MPD Catalog Extension XML Catalog Document in Root Directory mpd-catalog-extension-xml-catalog.xml must reside in the same relative directory as the mpd-catalog.xml it supports (normally, the [MPD root directory]). mpd-catalog-extension.xsd can be located anywhere in the MPD because mpd-catalog-extension-xml-catalog.xml correlates its namespace to its URI. However, this specification recommends both artifacts be co-located in the [MPD root directory] for visibility:

             *  mpd-catalog-extension-xml-catalog.xml (Rule 5-3, MPD Catalog Extension XML Catalog Document in Root Directory)

             *  mpd-catalog-extension.xsd

      4.  Include the following artifacts and ensure each is identified (tagged) appropriately within the [MPD catalog document]:

             *  readme artifact

             *  change log artifact

             *  conformance-assertion artifact

             *  conformance-report artifact (if present)

          Recommend these artifacts be located in the [MPD root directory].

      5.  Create the following directories within the [MPD root directory]:

             *  base-xsd -- will contain the NIEM subset and its associated extension, external, and custom NIEM schema documents. These are the NIEM XML schema documents used to validate conformance of an instance XML document. Subdirectories under base-xsd may include:

                   *  niem -- a NIEM schema subset organized as the Schema Subset Generation Tool (SSGT) generates it (including wantlist.xml and xml-catalog.xml artifacts).

                   *  extension -- for NIEM extension schema documents.

                   *  external -- for non-NIEM standards used by the [IEPD].

                   *  niem-custom -- for NIEM schema documents that may be customized (extended or restricted) such as structures.xsd.

             *  constraint-xsd -- will contain constraint schema documents organized as necessary. Usually this schema document set will be organized similarly to schema documents in base-xsd because it is customary to start with the base schema set and constrain it as necessary.

      6.  If using Schematron, create a schematron subdirectory for any Schematron schemas (or create the appropriate subdirectory name for any other kinds of business rule artifacts).

      7.  If using specialized [XML schema documents] for optimized EXI serialization, create an exi-xsd subdirectory for them.

      8.  Create an iep-sample subdirectory for sample IEPs (Rule 5-44, IEPD Has an IEP Sample for Each c:IEPConformanceTarget).

      9.  If more documentation artifacts (e.g., text, graphics, media) are necessary, create a documentation subdirectory for miscellaneous explanatory documentation. As needed, create additional subdirectories within this one to organize documentation artifacts. The readme artifact in the [MPD root directory] should refer to or index documentation in this subdirectory.

      10. If necessary, create an application-info subdirectory for tool-specific artifacts (inputs, outputs, imports, exports, models, etc.). Again, as needed, use additional subdirectories to organize artifacts of this nature. The readme artifact can and should also refer to or index artifacts in this subdirectory.

      11. Maintain a [NIEM wantlist] within the same subdirectory as the subset it generates (Rule 6-1, Wantlist Location).

      12. Maintain an xml-catalog.xml closest to the XML schema document set it relates to. Use er:nextCatalog elements as needed to help maintain this proximity).

      13. Finally, if it becomes necessary to maintain multiple constraint-xsd or extension subdirectories (or any other subdirectories) together in the same directory, then simply suffix each directory name with a distinct character string (for example, extension1, extension2, etc.; or extension-abc, extension-zyx, etc.)

   Obviously, there are many other ways to organize for more complex business requirements in which a single [IEPD] employs multiple releases, core supplements, subsets, constraint sets, and domain updates. Regardless of directory organization and file naming, an [IEPD] author must always configure all IEP conformance targets using the MPD catalog c:IEPConformanceTarget element and the appropriate validation artifacts (such as XML catalogs, Schematron schemas, RelaxNG schemas, etc.).

   The guidance above results in the [IEPD] directory structure and naming that appears below. Notes are in parentheses. Filenames within the extension, external, schematron, and iep-sample subdirectories are non-normative examples. Authors are free to assign names for such files according to their own requirements (if they do not violate rules in this specification).

   
   	/my_iepd-3.2rev4			(root directory of IEPD)
   
   		mpd-catalog.xml				(normative artifact name)
   		mpd-catalog-extension.xsd
   		mpd-catalog-extension-xml-catalog.xml	(normative artifact name)
   		changelog.*
   		conformance-assertion.*
   		readme.*
   
   		/base-xsd
   
   			/niem			(subset)
   				/adapters
   				/appinfo
   				/codes
   				/conformanceTargets
   				/domains
   				/external
   				/localTerminology
   				/niem-core
   				/proxy
   				/structures
   				wantlist.xml
   				xml-catalog.xml
   
   			/niem-custom		(extension/restriction of structures)
   				structures.xsd
   
   			/extension
   				query.xsd
   				response.xsd
   				extension1.xsd
   				extension2.xsd
   				...
   				xml-catalog.xml
   
   			/external
   				/stix
   				/ic-ism
   				...
   				xml-catalog.xml
   
   		/constraint-xsd			(constraint schema document sets)
   
   			/niem			(constraints on subset)
   				/adapters
   				/appinfo
   				/codes
   				/conformanceTargets
   				...
   				wantlist.xml
   				xml-catalog.xml
   
   			/extension		(constraints on extensions)
   				query.xsd
   				extension1.xsd
   				xml-catalog.xml
   
   		/exi-xsd
   			gml.xsd
   			xs.xsd
   			...
   
   		/schematron
   			business-rules1.sch
   			business-rules2.sch
   			...
   			
   		/iep-sample
   			query.xml
   			request.xml
   			...
   
   		/application-info
   			... (tool inputs, outputs, etc.)
   
   		/documentation
   			... (human readable documentation)
   

      

Appendix F. Acronyms and Abbreviations

      Acronym / Abbreviation|Literal or Definition

      ASCII|American Standard Code for Information Interchange

      CSV |Comma Separated Value (file format)

      CUI |Controlled Unclassified Information

      EBV |Effective Boolean Value

      EIEM |Enterprise Information Exchange Model

      GIF |Graphic Interchange Format

      GML |Geospatial Markup Language

      HTML |Hyper Text Markup Language

      IEP |information exchange package

      IEPD |information exchange package documentation

      IRI |Internationalized Resource Identifier

      JPG |Joint Photographic (Experts) Group

      LEXS |Logical Entity Exchange Specifications

      MPD |Model Package Description

      NCName|Non-colonized Name (in XML Schema: unprefixed and no colon character)

      NDR |Naming and Design Rules

      NIEM |National Information Exchange Model

      NTAC |NIEM Technical Architecture Committee

      OGC |Open Geospatial Consortium

      PDF |Portable Document Format

      PMO |Program Management Office

      PNG |Portable Network Graphic

      QName|Qualified Name (in XML Schema: a name qualified by a namespace)

      RFC |Request for Comment

      SSGT |Schema Subset Generation Tool

      TDF |Trusted Data Format

      UML |Unified Modeling Language

      UPA |Unique Particle Attribution

      URI |Uniform Resource Identifier

      URL |Uniform Resource Locator 

      URN |Uniform Resource Name

      W3C |World Wide Web Consortium

      XMI |XML Metadata Interchange

      XML |Extensible Markup Language

      XS |XML Schema (namespace prefix)

      XSD |XML Schema Definition

      XSI |XML Schema Instance (namespace prefix)

      XSLT |Extensible Stylesheet Language Transformation

      

Appendix G. References

   [FEA Data Reference Model 1.0]: The Federal Enterprise Architecture Data Reference Model, Version 1.0, September 2004. Available from http://xml.gov/documents/completed/DRMv1.pdf. A more recent DRM Version 2.0, 17 November 2005 is available from http://www.whitehouse.gov/omb/assets/egov_docs/DRM_2_0_Final.pdf

   [GJXDM IEPD Guidelines 1.1]: GJXDM Information Exchange Package Documentation Guidelines, Version 1.1, Global XML Structure Task Force (GXSTF), 2 March 2005. Available from http://it.ojp.gov/documents/global_jxdm_IEPD_guidelines_v1_1.pdf

   [ISO 11179-4]: ISO/IEC 11179-4 Information Technology -- Metadata Registries (MDR) -- Part 4: Formulation of Data Definitions Second Edition, 15 July 2004. Available from http://standards.iso.org/ittf/PubliclyAvailableStandards/c035346_ISO_IEC_11179-4_2004(E).zip.

   [ISO 11179-5]: ISO/IEC 11179-5:2005, Information technology -- Metadata registries (MDR) -- Part 5: Naming and identification principles. Available from http://standards.iso.org/ittf/PubliclyAvailableStandards/c035347_ISO_IEC_11179-5_2005(E).zip.

   [ISO RelaxNG]: Document Schema Definition Language (DSDL) -- Part 2: Regular-grammar-based validation -- RELAX NG, ISO/IEC 19757-2:2008, Second Edition, 15 December 2008. Available from http://standards.iso.org/ittf/PubliclyAvailableStandards/c052348_ISO_IEC_19757-2_2008(E).zip. See also http://relaxng.org.

   [ISO Schematron]: Schema Definition Languages (DSDL) -- Part 3: Rule-based validation -- Schematron, ISO/IEC 19757-3:2006(E), First Edition, 1 June 2006. Available from http://standards.iso.org/ittf/PubliclyAvailableStandards/c040833_ISO_IEC_19757-3_2006(E).zip.

   [Logical Entity Exchange Specification]: Logical Entity Exchange Specification, Version 4.0, 27 July 2011. Available from http://130.207.211.107/content/downloads.

   [NIEM Business Information Exchange Components 1.0]: NIEM Business Information Exchange Components, Version 1.0, NIEM Technical Architecture Committee (NTAC), 8 March 2011. Available from http://reference.niem.gov/niem/specification/business-information-exchange-components/1.0/.

   [NIEM Conformance 3.0]: NIEM Conformance, Version 3.0, NIEM Technical Architecture Committee (NTAC), 14 August 2014. Available from http://reference.niem.gov/niem/specification/conformance/3.0/.

   [NIEM Conformance Targets Attribute Specification 3.0]: NIEM Conformance Targets Attribute Specification, Version 3.0, NIEM Technical Architecture Committee (NTAC), 31 July 2014. Available from http://reference.niem.gov/niem/specification/conformance-targets-attribute/3.0/.

   [NIEM Domain Update Specification 1.0]: NIEM Domain Update Specification, Version 1.0, NIEM Technical Architecture Committee (NTAC), 5 November 2010. Available from http://reference.niem.gov/niem/specification/domain-update/1.0/.

   [NIEM High-Level Tool Architecture 1.1]: NIEM High-Level Tool Architecture, Version 1.1, NIEM Technical Architecture Committee, 1 December 2008. Available from http://reference.niem.gov/niem/specification/high-level-tool-architecture/1.1/.

   [NIEM High-Level Version Architecture 3.0]: NIEM High Level Version Architecture (HLVA), Version 3.0, NIEM Technical Architecture Committee, 27 April 2015. Available from http://reference.niem.gov/niem/specification/high-level-version-architecture/3.0/.

   [Requirements for a NIEM IEPD 2.1]: Requirements for a National Information Exchange Model (NIEM) Information Exchange Package Documentation (IEPD) Specification, Version 2.1, June 2006. Available from http://reference.niem.gov/niem/guidance/iepd-requirements/2.1/.

   [NIEM Implementation Guide]: "NIEM Implementation Guide", NIEM Program Management Office. Available from https://www.niem.gov/aboutniem/grant-funding/Pages/implementation-guide.aspx.

   [NIEM Introduction]: Introduction to the National Information Exchange Model (NIEM), Version 0.3, NIEM Program Management Office, 12 February 2007. Available from http://reference.niem.gov/niem/guidance/introduction/.

   [NIEM MPD Specification 1.0]: NIEM Model Package Description (MPD) Specification, Version 1.0, NIEM Technical Architecture Committee (NTAC), 8 August 2011. Available from http://reference.niem.gov/niem/specification/model-package-description/1.0/.

   [NIEM MPD Specification 1.1]: NIEM Model Package Description (MPD) Specification, Version 1.1, NIEM Technical Architecture Committee (NTAC), 1 October 2012. Available from http://reference.niem.gov/niem/specification/model-package-description/1.1/.

   [NIEM MPD Specification 3.0]: NIEM Model Package Description (MPD) Specification, Version 3.0, NIEM Technical Architecture Committee (NTAC), 15 August 2014. Available from http://reference.niem.gov/niem/specification/model-package-description/3.0/.

   [NIEM MPD Toolkit]: "NIEM Model Package Description Toolkit", Version 3.0, NIEM Technical Architecture Committee (NTAC), 15 August 2014. Available from http://reference.niem.gov/niem/specification/model-package-description/3.0/mpd-toolkit-3.0.zip.

      This toolkit contains: example IEPDs, XML schemas to validate an mpd-catalog.xml artifact, associated NIEM core subset, and a conformance assertion example. Other artifacts may be added in the future as appropriate.

   [NIEM Naming and Design Rules 3.0]: NIEM Naming and Design Rules (NDR), Version 3.0, NIEM Technical Architecture Committee (NTAC), [31 July 2014. Available from http://reference.niem.gov/niem/specification/naming-and-design-rules/3.0/.

   [NIEM SSGT]: "NIEM Schema Subset Generation Tool" (SSGT). Available from http://tools.niem.gov/niemtools/ssgt/index.iepd.

   [XML Catalogs 1.1]: XML Catalogs, Organization for the Advancement of Structured Information Standards (OASIS) Standard v1.1, 7 October 2005. Available from https://www.oasis-open.org/committees/download.php/14809/std-entity-xml-catalogs-1.1.html.

   [PKZIP]: APPNOTE.TXT - .ZIP File Format Specification, Version: 6.3.2, Revised: 28 September 2007, Copyright (c) 1989 - 2007 PKWare Inc. Available from http://www.pkware.com/documents/casestudies/APPNOTE.TXT.

   [Principles of Data Integration]: Doan, A., Halevy, A., and Ives, X. (2012), Principles of Data Integration, New York, NY: Morgan Kaufmann.

   [RFC 2119 Key Words]: Bradner, S., Key words for use in RFCs to Indicate Requirement Levels, IETF RFC 2119, March 1997. Available from http://www.ietf.org/rfc/rfc2119.txt.

   [RFC 2141 URN Syntax]: Moats, R., URN Syntax, IETF Request For Comment 2141, May 1997. Available from http://tools.ietf.org/html/rfc2141.

   [RFC 3986 URI]: Berners-Lee, T., et al., Uniform Resource Identifier (URI): Generic Syntax, Request for Comment 3986, Network Working Group, January 2005. Available from http://tools.ietf.org/html/rfc3986.

   [RFC 3987 IRI]: Duerst, M., and Suignard, M., Internationalized Resource Identifiers (IRIs), Request For Comment 3987, January 2005. Avalailable from http://tools.ietf.org/html/rfc3987.

   [EXI Format 1.0]: Efficient XML Interchange (EXI) Format, Version 1.0, W3C Recommendation, 10 March 2011. Available from http://www.w3.org/TR/2011/REC-exi-20110310/.

   [W3C XML 1.0]: Extensible Markup Language (XML), Version 1.0, Fifth Edition, W3C Recommendation 26 November 2008. Available from http://www.w3.org/TR/2008/REC-xml-20081126/.

   [W3-XML-InfoSet]: XML Information Set, Second Edition, W3C Recommendation 4 February 2004. Available from http://www.w3.org/TR/2004/REC-xml-infoset-20040204/.

   [W3-XML-Namespaces]: Namespaces in XML, Second Edition, World Wide Web Consortium 16 August 2006. Available from http://www.w3.org/TR/2006/REC-xml-names-20060816/.

   [W3C XML Schema Part 2 Datatypes]: XML Schema Part 2: Datatypes, Second Edition, W3C Recommendation 28 October 2004. Available from http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/.

   [W3C XML Schema Part 1 Structures]: XML Schema Part 1: Structures, Second Edition, W3C Recommendation 28 October 2004. Available from http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/.

   [W3C XPath 2.0]: XML Path Language (XPath) 2.0, Second Edition, W3C Recommendation 14 December 2010. Available from http://www.w3.org/TR/2010/REC-xpath20-20101214/.

   [XSLT 1.0]: XSL Transformations (XSLT), Version 1.0, W3C Recommendation 16 November 1999. Available from http://www.w3.org/TR/1999/REC-xslt-19991116.

   [XSLT 2.0]: XSL Transformations (XSLT), Version 2.0, W3C Recommendation 23 January 2007. Available from http://www.w3.org/TR/2007/REC-xslt20-20070123/.

Appendix H. Index of Definitions

   The index of definitions is omitted from this edition.

Appendix I. Index of Rules

   Rule 3-1, MPD Conformance Target Identifier: Section 3.2.1, The Model Package Description Conformance Target
   Rule 3-2, MPD with MPD class of IEPD is an IEPD: Section 3.2.2, IEPD Conformance Target
   Rule 3-3, IEPD Conformance Target Identifier: Section 3.2.2, IEPD Conformance Target
   Rule 4-1, Fundamental NIEM Subset Rule: Section 4.2.1, Basic Subset Concepts
   Rule 5-1, MPD Has an mpd-catalog.xml in its Root Directory: Section 5.1, NIEM MPD Catalog
   Rule 5-2, MPD Catalog Document Valid to mpd-catalog-3.0.xsd: Section 5.1, NIEM MPD Catalog
   Rule 5-3, MPD Catalog Extension XML Catalog Document in Root Directory: Section 5.1.2, Extending an MPD Catalog
   Rule 5-4, MPD Catalog Extension XML Catalog Document Name Is mpd-catalog-extension-xml-catalog.xml: Section 5.1.2, Extending an MPD Catalog
   Rule 5-5, MPD Catalog Extension XML Catalog Document Resolves Namespaces to URIs: Section 5.1.2, Extending an MPD Catalog
   Rule 5-6, MPD Catalog Extension Schema Document Conforms to NDR Extension Rules: Section 5.1.2, Extending an MPD Catalog
   Rule 5-7, MPD Catalog Schema and Its Extensions Conform to NDR Schema Set Rules: Section 5.1.2, Extending an MPD Catalog
   Rule 5-8, MPD Schema Document Extension Support Schemas Are Supersets of Spec Subsets: Section 5.1.2, Extending an MPD Catalog
   Rule 5-9, MPD Class Determined by Conformance Target Identifier in c:mpdClassURIList: Section 5.2.2, MPD Class (c:mpdClassURIList)
   Rule 5-10, MPD Version Number Syntax: Section 5.2.3, MPD Version Numbering Scheme (c:mpdVersionID)
   Rule 5-11, MPD URI Is Absolute: Section 5.2.4.1, MPD URI Scheme (c:mpdURI)
   Rule 5-12, MPD URI Supports Fragment: Section 5.2.4.2, URI Scheme for MPD Artifacts (c:externalURI)
   Rule 5-13, MPD URI Has No Fragment: Section 5.2.4.2, URI Scheme for MPD Artifacts (c:externalURI)
   Rule 5-14, MPD Artifact URI Syntax: Section 5.2.4.2, URI Scheme for MPD Artifacts (c:externalURI)
   Rule 5-15, c:pathURI Resolves to a Resource: Section 5.2.4.3, URI Scheme for Local MPD Artifacts (c:pathURI)
   Rule 5-16, c:pathURI for c:XMLCatalog: Section 5.2.4.3, URI Scheme for Local MPD Artifacts (c:pathURI)
   Rule 5-17, c:pathURI for c:MPDChangeLog: Section 5.2.4.3, URI Scheme for Local MPD Artifacts (c:pathURI)
   Rule 5-18, c:pathURI for c:ReadMe: Section 5.2.4.3, URI Scheme for Local MPD Artifacts (c:pathURI)
   Rule 5-19, c:pathURI for c:IEPSampleXMLDocument: Section 5.2.4.3, URI Scheme for Local MPD Artifacts (c:pathURI)
   Rule 5-20, c:pathURI for c:BusinessRulesArtifact: Section 5.2.4.3, URI Scheme for Local MPD Artifacts (c:pathURI)
   Rule 5-21, c:pathURI for c:XMLSchemaDocument: Section 5.2.4.3, URI Scheme for Local MPD Artifacts (c:pathURI)
   Rule 5-22, c:pathURI for c:ExternalSchemaDocument: Section 5.2.4.3, URI Scheme for Local MPD Artifacts (c:pathURI)
   Rule 5-23, c:pathURI for c:ReferenceSchemaDocument: Section 5.2.4.3, URI Scheme for Local MPD Artifacts (c:pathURI)
   Rule 5-24, c:pathURI for c:ExtensionSchemaDocument: Section 5.2.4.3, URI Scheme for Local MPD Artifacts (c:pathURI)
   Rule 5-25, c:pathURI for c:SubsetSchemaDocument: Section 5.2.4.3, URI Scheme for Local MPD Artifacts (c:pathURI)
   Rule 5-26, c:pathURI for c:Wantlist: Section 5.2.4.3, URI Scheme for Local MPD Artifacts (c:pathURI)
   Rule 5-27, c:pathURI for c:SchematronSchema: Section 5.2.4.3, URI Scheme for Local MPD Artifacts (c:pathURI)
   Rule 5-28, c:pathURI for c:RelaxNGSchema: Section 5.2.4.3, URI Scheme for Local MPD Artifacts (c:pathURI)
   Rule 5-29, c:pathURI for c:SchemaDocumentSet: Section 5.2.4.3, URI Scheme for Local MPD Artifacts (c:pathURI)
   Rule 5-30, c:pathURI for c:ConstraintSchemaDocumentSet: Section 5.2.4.3, URI Scheme for Local MPD Artifacts (c:pathURI)
   Rule 5-31, : Section 5.2.4.3, URI Scheme for Local MPD Artifacts (c:pathURI)
   Rule 5-32, Resolve MPD URI with Fragment: Section 5.2.4.5, Resolving an MPD URI with a Fragment
   Rule 5-33, XML Catalog uri Value Resolves to Resource: Section 5.2.4.7, XML Catalog URI
   Rule 5-34, XML Catalog uri Value Resolves to Resource with Correct Target Namespace: Section 5.2.4.7, XML Catalog URI
   Rule 5-35, IEPD Has a Change Log: Section 5.3.2, Change Log for IEPDs
   Rule 5-36, Readme Describes Purpose, Scope, Business Value, etc.: Section 5.4, ReadMe Artifact
   Rule 5-37, IEPD Has a ReadMe Artifact: Section 5.4, ReadMe Artifact
   Rule 5-38, Conformance Target Identifier: Section 5.6, Defining Information Exchange Packages
   Rule 5-39, IEP Conformance Target Has a structures:id: Section 5.6, Defining Information Exchange Packages
   Rule 5-40, [IEPD] Declares One or More IEP Conformance Targets: Section 5.6, Defining Information Exchange Packages
   Rule 5-41, : Section 5.6.2.3, c:ValidityContext
   Rule 5-42, Identifying the Document Element of an IEP: Section 5.6.2.4, c:HasDocumentElement
   Rule 5-43, Validating an XPath Expression: Section 5.6.2.5, c:ValidToXPath
   Rule 5-44, IEPD Has an IEP Sample for Each c:IEPConformanceTarget: Section 5.6.3, IEP Sample Instance XML Documents
   Rule 5-45, Validating an IEP Sample XML Document: Section 5.6.3, IEP Sample Instance XML Documents
   Rule 5-46, IEPD Has Conformance Assertion: Section 5.7, Conformance Assertion
   Rule 6-1, Wantlist Location: Section 6.1, NIEM Wantlist
   Rule 7-1, An MPD in ZIP File Format Preserves Logical Directory Structure.: Section 7, Organization, Packaging, and Other Criteria
   Rule 7-2, XSD and XML Documents Conform to Applicable NDR Conformance Targets: Section 7, Organization, Packaging, and Other Criteria
   Rule 7-3, MPD Archive Uncompresses to a Single Root Directory: Section 7, Organization, Packaging, and Other Criteria
   Rule 7-4, Constraint on Elements of Type c:SchemaDocumentSetType: Section 7.1.1, Constraint on Elements of Type c:SchemaDocumentSetType
   Rule 7-5, IEPD ZIP file Name Syntax: Section 7.2, IEPD File Name Syntax
   Rule 7-6, MPD Reference to Resource Uses Common URI Scheme: Section 7.3, Artifact Links to Other Resources
   Rule 7-7, IEPD Completeness: Section 7.4, IEPD Completeness
   Rule 7-8, MPD External Schema Documents Are Local Resources: Section 7.4, IEPD Completeness
   Rule 7-9, Key MPD Resources Are Local Resources: Section 7.4, IEPD Completeness

Appendix J. Revision History

   Significant changes in version 3.0.1 (27 August 2015):

      1. Changed term "core update" to "core supplement".

      2. Removed references to outdated NIEM User Guide Volume 1.

      3. Relaxed and clarified MPD ZIP file format requirement. Allows an MPD to live as a file collection in a repository, such as a Git repository, and still use ZIP file format for transit, upload, download, bulk storage, or whenever convenient to maintain a small electronic footprint.

      4. Changed a core supplement from a type of MPD to a special release. The MPD specification now defines only four MPD classes: release, domain update, [IEPD], and Enterprise Information Exchange Model (EIEM) (described in [NIEM Business Information Exchange Components 1.0]).

      5. Modified Section 1.3, Scope, above, to explain that this specification is applicable to all MPDs in general, but is specifically focused on [IEPD].