National Information Exchange Model -- Information Exchange Package Documentation Specification Version 5.0 March 22, 2021 NIEM Technical Architecture Committee (NTAC) Abstract This document specifies normative rules and non-normative guidance for building a National Information Exchange Model (NIEM) information exchange package documentation (IEPD). Status This document deprecates the Model Package Description (MPD) construct as of NIEM 5.0. This specification represents the work of the NIEM Technical Architecture Committee (NTAC), the NIEM Business Architecture Committee (NBAC), and their predecessors. It is a product of the NIEM Management Office (NMO). Email comments on this specification to information@niem.gov or submit them via the GitHub issue tracker. Contents The table of contents is omitted from this edition. 1. Introduction This specification defines rules and practices for constructing and packaging a National Information Exchange Model (NIEM)[information exchange package documentation] (IEPD). To the NIEM program, the [IEPD] is considered the point of interoperability. This specification assumes familiarity with NIEM, its basic concepts, architecture, processes, design rules, and general conformance rules. NIEM training and reference materials are located on the [NIEM TechHub]. In addition to those materials, readers of this specification may wish to be familiar with the current versions of the following: * [NIEM Conformance Specification] * [NIEM Conformance Targets Attribute Specification] * [NIEM Naming and Design Rules] * [NIEM Code List Specification] * [NIEM High-Level Version Architecture] This specification uses and is a peer to the [NIEM Naming and Design Rules]. 1.1. Background An [IEPD] is a normative specification for XML [data components] in the format of the World Wide Web Consortium (W3C) XML Schema Definition Language [W3C XML Schema Part 2 Datatypes], [W3C XML Schema Part 1 Structures]. [IEPD] schema documents define implementable NIEM exchange instance XML documents in W3C Extensible Markup Language (XML) [W3C XML 1.0]. An [IEPD] is ready to publish and use when it conforms to NIEM specifications, and has been properly packaged with the schemas, documentation, and supplemental files needed to implement or reuse it. [IEPD] content design, development, and assembly may be difficult and time-consuming, especially if done manually. Developers will often prefer to build and modify an IEPD with the help of software tools, which can significantly reduce the complexity of designing, constructing, changing, and managing IEPDs. In order to reduce ambiguity and to facilitate interoperable and effective tool support, this baseline specification imposes some degree of consistency on the terminology, syntax, semantics, and composition of IEPDs. 1.2. Purpose This document is a normative specification for NIEM [information exchange package documentation] (IEPD). The rules and guidance herein are designed to encourage and facilitate NIEM use and tools by balancing consistency, simplicity, and flexibility. Consistency and simplicity make IEPDs easy to design correctly, build rapidly, and find easily (for reuse or adaptation). Consistency also facilitates tool support. Flexibility enables more latitude to design and tailor IEPDs for complex data exchange requirements. As such, this document does not necessarily prescribe mandates or rules for all possible situations or organizational needs. If an organization desires to impose additional requirements or constraints on its IEPDs beyond those specified in this document (for example, mandate that an [IEPD] contain a normative set of business requirements or a domain model), then it is free to do so, as long as no conflicts exist with this specification or the [NIEM Naming and Design Rules]. This document defines terminology; identifies required and optional (but common) artifacts; defines metadata; specifies normative constraints, schemes, syntax, and processes as rules; provides non-normative guidance; and as needed, refers to other related NIEM specifications for more detail. 1.3. Scope This specification applies to all NIEM [information exchange package documentation] (IEPD), and in particular it focuses on the normative rules for IEPDs. NIEM is a data layer for an information architecture. Files in an [IEPD] generally define XML Schema types and declare XML elements and attributes to use in payloads for information exchanges. While an [IEPD] may also contain files from layers beyond the data layer, this specification is not intended to define details of other architectural layers. Such files are generally present only to provide additional context, understanding, or assistance for implementing the exchange of payloads. This specification defines several incremental stages of conformance to support iterative [IEPD] development, with conformance testing possible at each step instead of delayed to the end. Tool vendors should be able to build, adapt, and integrate software tools to assist in [IEPD] development and assembly, from raw parts to finished product. This specification provides a standard version numbering scheme Section 5.2.3, IEPD Version Numbering Scheme (c:iepdVersionID), below. However, it does not provide guidance for managing or processing [IEPD] versions or their associated [information exchange packages] ([IEPs]). Creation and management of [IEPDs] is the responsibility of stakeholders and developers. As such, [IEPDs] have their own versioning processes, and are managed independently of the NIEM core and domains. The NIEM Management Office defines [IEPD] conformance, but [IEPD] development and management fall outside its scope. Nonetheless, the NIEM Management Office has developed guidance (through the NTAC) for managing [IEPDs], versioning [IEPDs], and processing their associated [IEPs]. This reference material can be found at https://niem.github.io/reference/artifacts/messages/iepd/. An [IEPD] defines one or more data exchanges, each occurring in the form of an [IEP]. This specification supports a variety of data exchange use cases, in which the [IEP] may be: * An XML document with a NIEM-defined XML document element. * An XML document with a NIEM-defined payload element wrapped inside a non-NIEM envelope element (for example, SOAP, [Logical Entity Exchange Specifications] (LEXS), Trusted Data Format (TDF), or an OGC Web Service document element). * Multiple NIEM-defined payloads packaged together in a single document. IEPD developers are not required to revise IEPDs that existed before this specification becomes effective. However, they are always encouraged to consider revising an IEPD to meet this specification, especially when making other significant changes. 1.4. Audience The following groups should review and be familiar with this specification: * NIEM [IEPD] developers, reviewers, individuals or groups responsible for approving IEPDs, and implementers. * NIEM-aware tool developers. 2. Basic Concepts and Terminology The section defines and discusses baseline terms and concepts that will be used throughout this document. Presentation in this section is sequenced for understanding. Each subsection builds upon previous ones. 2.1. IETF Best Current Practice 14 terminology The key words MUST, MUST NOT, SHALL, SHALL NOT, SHOULD, SHOULD NOT, MAY, RECOMMENDED, REQUIRED, and OPTIONAL in this document are to be interpreted as described in [BCP 14][RFC 2119][RFC 8174]. 2.2. Character Case Sensitivity This specification imposes many constraints on the syntax for identifiers, names, labels, strings, etc. In all cases, unless otherwise explicitly noted, syntax is case sensitive. In particular, XML files in appendices that define particular artifacts, transformations, and examples are case sensitive. Also, note that as a general principle, lower case characters are used whenever such will not conflict with the [NIEM Naming and Design Rules]. 2.3. Artifacts IEPDs are generally composed of files and file sets grouped for a particular purpose. Each file is referred to as an [artifact], and each logical set of such files is called an [artifact set]. [Definition: artifact] A single file with a defined purpose. [Definition: artifact set] A collection of artifacts logically grouped for a defined purpose. An [IEPD] is itself an [artifact set], the purpose for which is to define and document the intended use of the [IEPD]. While the key [IEPD] artifacts are its [XML schema document] artifacts, there are also other kinds of [IEPD] artifacts. These may include (but are not limited to) HTML, XSLT, text, or graphic files used for human-readable documentation. An [IEPD] may also have artifacts intended to help assist in or accelerate the use and implementation of the [IEPD]. For example, these may be XML, UML, or binary files that are inputs to or outputs from software tools used to build, generate, or edit the [IEPD] or its schema document artifacts. Appendix C, Common IEPD Artifacts, below, contains a listing of mandatory and common optional artifacts for IEPDs. Common types of artifacts are described in more detail in subsequent sections. Section 7.1, Artifact Sets, below, discusses the different methods for grouping [IEPD] artifacts into sets. 2.4. Schema Document and Namespace Correspondence in NIEM To simplify automatic schema processing and reduce the potential for confusion and error, [NIEM Naming and Design Rules] principles state that each NIEM-conformant namespace SHOULD be defined by exactly one reference or extension schema document. To support this concept, the [NIEM Naming and Design Rules] disallows the use of xs:include, and mandates the use of the xs:schema/@targetNamespace attribute in NIEM-conformant schema documents. So, (1) each NIEM namespace is defined by a single NIEM-conformant schema document, and (2) each NIEM-conformant schema document declares a target namespace. NIEM does not permit schema documents without target namespaces, unless they are from sources outside of NIEM (e.g., an [external schema document]). 2.5. Namespaces Used in this Specification The following namespaces are referenced and used in this specification: Figure 2-1: Namespaces Used c http://reference.niem.gov/niem/resource/iepd/catalog/5.0/ er urn:oasis:names:tc:entity:xmlns:xml:catalog nc http://release.niem.gov/niem/niem-core/5.0/ structures http://release.niem.gov/niem/structures/5.0/ xs http://www.w3.org/2001/XMLSchema 2.6. 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 conceptual entity. That entity is most commonly substantiated as 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.7. Reference Schema Documents [Definition: reference schema document] As defined by [NIEM Naming and Design Rules]: An [XML schema document] that is intended to provide the authoritative definitions of broadly reusable [schema components]. A NIEM [reference schema document] is an [XML schema document] that is intended to be the authoritative definition schema for a namespace. Examples include NIEM Core and NIEM domains. 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 [IEPD 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] 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. [Definition: data component] An XML Schema type or attribute group definition; or an XML Schema element or attribute declaration. 2.8. 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
-] () 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] defines two terms used normatively and often within this specification. [Definition: conformance target] As defined by [NIEM Conformance Targets Attribute Specification]: 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]: An internationalized resource identifier [RFC 3987 IRI] that uniquely identifies a conformance target. It will also be useful to define [IEPD conformance target identifier]. [Definition: IEPD conformance target identifier] A [conformance target identifier] to which a given [IEPD] claims to conform. 3.2. IEPD Conformance Targets This specification establishes three primary [IEPD] [conformance targets]: [information exchange package documentation], [information exchange package] and [artifact]. 3.2.1. Information Exchange Package Documentation [Definition: information exchange package documentation] An [information exchange package documentation] 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 IEPD [conformance target identifier] http://reference.niem.gov/niem/specification/iepd/5.0/#IEPD, and * conforms to all the rules in this specification for the conformance target [information exchange package documentation] (i.e., applicability code "IEPD"), and * is well-formed (conforms to all the rules with applicability code "WF-IEPD"). This term may be abbreviated "IEPD". Rules specifying this conformance target use the applicability code "IEPD". An [IEPD] has one or more c:IEPConformanceTarget elements within its [IEPD 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] 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 the current [NIEM Naming and Design Rules] 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 applies to all IEPDs: Rule 3-1. IEPD conformance target identifier [Rule 3-1] (IEPD) An [IEPD] MUST have an [IEPD conformance target identifier] of http://reference.niem.gov/niem/specification/iepd/5.0/#IEPD as a value of its c:iepdConformanceTargetIdentifierURIList 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 [IEPDs]: * 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 each XML schema document set. 3.2.1.1. Well-Formed IEPD An [IEPD] may be constructed manually, but it is far more efficient to generate an IEPD entirely or in part using NIEM-aware software tools. The existence of an [information exchange package documentation] [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 [IEPD] incrementally in many different sequences. * Avoids a need to build a complete [IEPD] 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 an [information exchange package documentation]. Because an IEPD is always a directory tree, for the purpose of transporting, up/downloading, and archiving for long term storage, an IEPD 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. All IEPDs share several commonalities; each IEPD: * Is a set of [artifacts], whose principal content is [XML schema documents] (XSD), the purpose for which is to define the exchanges themselves. * Requires a self-documenting iepd-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, IEPD URI Scheme (c:iepdURI), below) * Name (See Section 5.2.1, IEPD Name Syntax (c:iepdName), below) * Version number (See Section 5.2.3, IEPD Version Numbering Scheme (c:iepdVersionID), below) * The [conformance target identifier] http://reference.niem.gov/niem/specification/iepd/5.0/#IEPD (See Section 5.2.2, IEPD Conformance Target Identifier (c:iepdConformanceTargetIdentifierURIList), 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: well-formed IEPD] A [well-formed IEPD] is an [IEPD] that: * has an [IEPD conformance target identifier] of http://reference.niem.gov/niem/specification/iepd/5.0/#WF-IEPD, and * adheres to all the rules within this specification for the [well-formed IEPD] [conformance target] (i.e., applicability code "WF-IEPD"). This term may be abbreviated "WF-IEPD". Rules specifying this conformance target use the applicability code "WF-IEPD". A [well-formed IEPD] satisfies the need for a set of [artifacts] (or a [ZIP file]) with an [IEPD catalog document] that validates to the IEPD catalog schema, and contains no broken links to local artifacts it references. This definition enables a developer to build an [IEPD] by iteratively adding artifacts and expanding the IEPD catalog to reference them. Most rules in this [IEPD] specification are applicable to a [well-formed IEPD] [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-IEPD), 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. Rule 3-2. IEPD is well-formed [Rule 3-2] (WF-IEPD) An [IEPD] MUST have an [IEPD conformance target identifier] of http://reference.niem.gov/niem/specification/iepd/5.0/#WF-IEPD. The schemas and other files within an [information exchange package documentation] are built on other specifications, including: * [NIEM Naming and Design Rules] * [NIEM Conformance Targets Attribute Specification] * [NIEM Conformance Specification] 3.2.2. 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 [instance XML document] that conforms to the conformance target defined by a c:IEPConformanceTarget element in the [IEPD catalog document] of an [information exchange package documentation]. 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 an [information exchange package documentation], 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.3. Artifact Conformance Targets Conformance targets that correspond to artifacts internal to an [IEPD] include: * [schema document subset] (rule applicability code: Schema-subset) * [IEPD catalog document] (rule applicability code: IEPD-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 [information exchange package documentation] | IEPD [well-formed IEPD] | WF-IEPD [information exchange package] | IEP [full NIEM IEP] |FN-IEP [schema document subset] | Schema-subset [IEPD catalog document] | IEPD-catalog [XML catalog document] | XML-catalog 4. IEPD XML Schema Document Artifacts [XML schema document] artifacts are the essential content of IEPDs because they normatively define and declare [data components]. The purpose of an [IEPD] 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] 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 current [NIEM Naming and Design Rules] 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. 4.1. Reference Schema Documents Though not common, it is 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.7, Reference Schema Documents, above. 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 for which 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 IEPD 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]: 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]. 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]: * 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], 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]: 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. An [IEPD] 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]: 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 current [NIEM Naming and Design Rules] 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]. 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. IEPD Documentation Artifacts XML schema documents (and the schemas that result from them) are the essence of a NIEM [IEPD]. However, a variety of documentation files may be incorporated into a NIEM [IEPD]. One particular documentation file is required in every IEPD: iepd-catalog.xml, the IEPD 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 [IEPD]. The following subsections address these documentation artifacts and the concepts, metadata, and content each supports. 5.1. NIEM IEPD Catalog [Definition: IEPD catalog document] An [instance XML document] that: * conforms to all the rules in this specification for the conformance target [IEPD catalog document] (i.e., applicability code "IEPD-catalog"), and * contains metadata describing: * IEPD unique identification * [Conformance targets] * Basic characteristics and properties * Key artifacts and directory structure * Relationships to other IEPDs and their artifacts This term may be abbreviated "IEPD-catalog". Rules specifying this conformance target use the applicability code "IEPD-catalog". Each [IEPD] may have somewhat different catalog requirements. The catalog metadata are formally defined by the XML Schema document in Appendix A, IEPD Catalog XML Schema Document, below. IEPD 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 [IEPD] 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 IEPDs (through metadata and relationships) * Reuse of IEPDs and their artifacts * Tracing and analysis of IEPD lineage * General conformance and validation of the [IEPD] itself * Definition, identification, and validation of IEP conformance targets Rule 5-1. IEPD Has an iepd-catalog.xml in its Root Directory [Rule 5-1] (WF-IEPD) Within its [root directory], an [IEPD] MUST contain an [IEPD catalog document] artifact with name iepd-catalog.xml. Rule 5-2. IEPD Catalog Document Valid to iepd-catalog.xsd [Rule 5-2] (IEPD-catalog) An [IEPD catalog document] MUST be valid to iepd-catalog.xsd as provided by Appendix A, IEPD Catalog XML Schema Document. This rule requires validation with iepd-catalog.xsd, which also imports a NIEM schema subset. So, validation of the [IEPD catalog document] must be done in the context of the catalog schema document, its associated NIEM subset, and iepd-catalog.xml. This does not require the [IEPD] to contain copies of the catalog schema document or the schema subset (since these are standard for all IEPDs). However, a validation tool must have access to all three XML documents. The XML schema documents required to validate an [IEPD catalog document] are available on the [NIEM Template IEPD repository]. 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. A sample [IEPD catalog document], Appendix B, Example IEPD Catalog Document for Cursor on Target, below, is included in this specification. 5.1.1. IEPD Catalog as a Table of Contents One function of the IEPD catalog is to serve as a table of contents that identifies, locates, and classifies key artifacts and artifact sets. For that purpose, Appendix A, IEPD Catalog XML Schema Document, below, provides a number of classifier elements for most common artifacts and artifact sets in IEPDs. 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, iepd-catalog.xml can be transformed into an index.html artifact that displays a hyperlinked IEPD table of contents and metadata summary in a browser. A best practice is to use the readme artifact (i.e., the [readme artifact] required in the [IEPD root directory]) to reference c:Documentation and c:ApplicationInfo artifacts whether or not they have been classified in the IEPD catalog. An IEPD catalog is not required to record all IEPD artifacts. The [IEPD] author decides which artifacts (both files and sets) are important enough to explicitly include in the IEPD catalog. The author may choose to classify all, some, or none in the catalog. The IEPD catalog provides a supplement or an alternative to organizing [IEPD] 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 IEPD Catalog An IEPD catalog may be extended to accommodate new or additional metadata, artifact classifiers, or validity constraints that are not already defined in Appendix A, IEPD Catalog XML Schema Document, below. To extend the IEPD catalog, an [IEPD] author must provide both an XML catalog extension document (XML) and one or more IEPD extension schema documents (XSD). The XML catalog extension identifies that one or more IEPD catalog extensions are present, and resolves their namespaces to local URIs. The IEPD catalog extension is a schema that defines and declares the new [data components] for metadata, classifiers, and/or constraints. Both general [NIEM Conformance Specification] and specific [NIEM Naming and Design Rules] conformance rules apply to these components. The XML catalog extension document must reside in the [IEPD root directory]. The IEPD extension schema documents may bear any file name and reside anywhere in the [IEPD]. This is because the XML catalog is expected to [resolve] all local URIs. IEPD processing tools are expected to look for and recognize the XML catalog (that identifies IEPD catalog extensions exist) by its file name. The following rules specify the requirements for an IEPD catalog extension XML catalog document: Rule 5-3. IEPD Catalog Extension XML Catalog Document in Root Directory [Rule 5-3] (IEPD-catalog) An IEPD catalog extension XML catalog document MUST reside in the same relative directory as the iepd-catalog.xml artifact (normally in the [IEPD root directory]) Rule 5-4. IEPD Catalog Extension XML Catalog Document Name Is iepd-catalog-extension-xml-catalog.xml [Rule 5-4] (IEPD-catalog) An IEPD catalog extension XML catalog document MUST bear the file name (and type) iepd-catalog-extension-xml-catalog.xml. Rule 5-5. IEPD Catalog Extension XML Catalog Document Resolves Namespaces to URIs [Rule 5-5] (IEPD-catalog) An IEPD catalog extension XML catalog document MUST [resolve] all IEPD catalog schema extension document namespaces to the correct corresponding local URIs in the IEPD. So, when a processor identifies a file named iepd-catalog-extension-xml-catalog.xml in the [IEPD root directory], it can assume that it contains references to one or more IEPD catalog extension schema documents that adhere to the following rules: Rule 5-6. IEPD Catalog Extension Schema Document Conforms to NDR Extension Schema Document Rules [Rule 5-6] (IEPD-catalog) An IEPD catalog extension schema document MUST conform to the [NIEM Naming and Design Rules] extension schema document conformance target rules. Rule 5-7. IEPD Catalog Schema and Its Extensions Conform to NDR Schema Set Rules [Rule 5-7] (IEPD-catalog) Within an IEPD, the schema set formed by iepd-catalog.xsd and all IEPD catalog extension schema documents MUST conform to the [NIEM Naming and Design Rules] schema set conformance target rules. Whether extending an IEPD catalog with new metadata elements, artifact classifier elements, or validity constraint elements, Appendix A, IEPD 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, IEPD Catalog XML Schema Document, below. If an IEPD catalog schema document extension uses NIEM [data components] that are not already contained in the NIEM Core subset provided on the [NIEM Template IEPD repository], then the additional components must be additive. In other words: Rule 5-8. IEPD Schema Document Extension Support Schemas Are Supersets of Spec Subsets [Rule 5-8] (IEPD-catalog) Subset schema documents provided to support an IEPD schema document extension MUST be a superset of the subset schema documents provided with this specification to support the IEPD catalog schema document. 5.2. Metadata Concepts The IEPD catalog also contains both required and optional metadata for the [IEPD] and its artifacts and artifact sets. The following subsections specify the syntax, formats, and semantics for that metadata. 5.2.1. IEPD Name Syntax (c:iepdName) An IEPD's official name is the value of the c:iepdName attribute owned by the c:IEPD element in the IEPD's catalog document. This value is constrained by the regular expression pattern on c:iepdName within the IEPD catalog schema Appendix A, IEPD Catalog XML Schema Document, below: [A-Za-z]([-_ ]?[A-Za-z0-9]+)* The regular expression above indicates that an IEPD 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 [IEPD] name in metadata within the file name. Note that c:iepdName 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:iepdName is not the same thing as the name of the file containing the IEPD, described in Section 7.2, IEPD File Name Syntax, below. 5.2.2. IEPD Conformance Target Identifier (c:iepdConformanceTargetIdentifierURIList) An [IEPD conformance target identifier] is a [conformance target identifier] to which the given [IEPD] claims to conform. The IEPD catalog c:iepdConformanceTargetIdentifierURIList attribute declares a list of [conformance target identifiers], identifying the [conformance targets] to which the IEPD claims to conform. The c:iepdConformanceTargetIdentifierURIList attribute is an XML list type that may declare that an IEPD conforms to multiple conformance targets. An IEPD developer can establish a new IEPD [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 IEPD 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 IEPD catalog document for its published IEPDs would contain the c:iepdConformanceTargetIdentifierURIList component shown in Figure 5-1, IEPD catalog c:iepdConformanceTargetIdentifierURIList attribute for organization ABC., below, indicating conformance to three [conformance targets]. Figure 5-1: IEPD catalog c:iepdConformanceTargetIdentifierURIList attribute for organization ABC. c:iepdConformanceTargetIdentifierURIList= "http://reference.niem.gov/niem/specification/iepd/5.0/#IEPD http://example.org/niem-iepd/1.0/#abc-org" 5.2.3. IEPD Version Numbering Scheme (c:iepdVersionID) Published IEPDs 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 IEPD version number is the value of the c:iepdVersionID attribute owned by the c:IEPD element within its [IEPD catalog document]. A consistent version number syntax is enforced by the IEPD catalog schema in Appendix A, IEPD Catalog XML Schema Document, below. The syntax rule is as follows: Rule 5-9. IEPD Version Number Syntax [Rule 5-9] (WF-IEPD) An IEPD 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] 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 IEPD version numbers: * 1 * 1.2 * 1.3.1.0 * 1.2alpha13 * 199.88.15rev6 There are two implications in Rule 5-9, IEPD 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-9, IEPD 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-9, IEPD Version Number Syntax is that pre-releases are easily identified by the strings alpha, beta, and rc. These strings are simple visible indicators of IEPD 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 [IEPD], 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 [IEPD]. IEPD version numbers within a version series do NOT imply compatibility between versions. Compatibility between or among IEPD versions MUST be explicitly stated in documentation. Note that an author who updates an existing [IEPD] 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 IEPDs only; there is no requirement to apply this syntax to artifact versioning. 5.2.4. URI Schemes All IEPDs use Uniform Resource Identifiers (URIs) to identify artifacts and other resources. Several kinds of URIs are employed by IEPDs to reference other IEPDs, IEPD artifacts (internally and externally), conformance targets, documents, and other resources. For each type of URI used in an IEPD catalog document, this section describes its purpose, options, and syntax based on [RFC 3986 URI]. The following definitions will be useful to understanding IEPD 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 [IEPD]) 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. IEPD URI Scheme (c:iepdURI) To facilitate IEPD sharing and reuse, the assignment of a URI (Uniform Resource Identifier) to an IEPD is essential. This is enforced by the IEPD catalog schema document Appendix A, IEPD Catalog XML Schema Document, below. It is also important to ensure that an IEPD URI is absolute. Rule 5-10. IEPD URI Is Absolute [Rule 5-10] (WF-IEPD) In an IEPD catalog document, the value of a c:iepdURI attribute of type xs:anyURI MUST match the production as defined by [RFC 3986 URI], section 4.3, "Absolute URI". This rule implies that a URI assigned to an [IEPD] must be valid. Furthermore, the entity (person or organization) assigning the IEPD 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 IEPD URIs: * http://gbi.georgia.gov/gcic/niem/sort-entry/1.1/ * http://www.acq.osd.mil/ncbdp/nm/pseag/seiwg-niem/1.0/ * http://ncsc.org/niem/icwa/1.0 * http://cb.acf.hhs.gov/neice/1.0/exchange/ This specification does not mandate that basic IEPD catalog metadata be designed into an IEPD 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 IEPD catalog metadata (in particular, the values of c:iepdURI, c:iepdName, c:iepdVersionID, and c:iepdConformanceTargetIdentifierURIList defined in the IEPD catalog document). 5.2.4.2. URI Scheme for IEPD Artifacts (c:externalURI) Artifacts in other IEPDs can be referenced from within an [IEPD] to identify equivalence (signify reuse, one aspect of lineage). To support this concept, the following IEPD URI rules are necessary: Rule 5-11. IEPD URI Supports Fragment [Rule 5-11] (WF-IEPD) A valid IEPD URI MUST support the inclusion of a fragment identifier (as a suffix) [RFC 3986 URI]. This rule ensures that an [IEPD] can always uniquely identify and refer to each artifact within another IEPD. This IEPD specification follows [RFC 3986 URI] which forbids a URI to contain more than a single fragment identifier. To construct an IEPD artifact URI, add a fragment (that locally identifies the artifact) to an IEPD URI, and therefore, an IEPD URI cannot already contain a fragment. Rule 5-12. IEPD URI Has No Fragment [Rule 5-12] (WF-IEPD) A valid IEPD URI MUST NOT contain a fragment identifier [RFC 3986 URI]. Rationale: If a URI for an [IEPD] (do NOT confuse this with a URI for an IEPD artifact) already contains a fragment identifier, then that URI cannot be employed as an IEPD 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 [IEPD root directory]. Rule 5-13. IEPD Artifact URI Syntax [Rule 5-13] (WF-IEPD) Within an [IEPD] a URI reference to an artifact in another external IEPD (i.e., an IEPD artifact URI) is the concatenation of: * The URI of the [IEPD] 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 [IEPD 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 IEPD 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) Artifact URIs are used as values for the c:externalURI attribute in the IEPD catalog XML document to declare equivalence relationships between artifacts (See Appendix A, IEPD 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. They can optionally create an IEPD 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 IEPDs and wishes to acknowledge them. A URI does not have the same meaning as namespace. NIEM namespaces cannot be used as IEPD 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 [IEPD]. 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 IEPD Artifacts (c:pathURI) An IEPD 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 [IEPD catalog document], and therefore, they are also relative to the [IEPD root directory] since the IEPD catalog document resides in the IEPD root directory. In general, every value of attribute c:pathURI in an IEPD 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 IEPD URI attributes, below, a local URI may contain an optional fragment. Although c:pathURI has no use for a URI with a fragment, IEPD 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 an [information exchange package documentation]. These rules ensure that every c:pathURI attribute value in a well-formed [IEPD] resolves to a correct local resource: Rule 5-14. c:pathURI Resolves to a Resource [Rule 5-14] (WF-IEPD) Within an [IEPD catalog document], the value of a c:pathURI attribute MUST [resolve] to a resource. Rule 5-15. c:pathURI for c:XMLCatalog [Rule 5-15] (WF-IEPD) Within an [IEPD catalog document], the value of a c:pathURI attribute owned by a c:XMLCatalog element MUST [resolve] to an [XML catalog document]. Rule 5-16. c:pathURI for c:IEPDChangeLog [Rule 5-16] (WF-IEPD) Within an [IEPD catalog document], the value of a c:pathURI attribute owned by a c:IEPDChangeLog element MUST [resolve] to a [change log]. Rule 5-17. c:pathURI for c:ReadMe [Rule 5-17] (WF-IEPD) Within an [IEPD catalog document], the value of a c:pathURI attribute owned by a c:ReadMe element MUST [resolve] to a [readme artifact]. Rule 5-18. c:pathURI for c:IEPSampleXMLDocument [Rule 5-18] (WF-IEPD) Within an [IEPD catalog document], the value of a c:pathURI attribute owned by a c:IEPSampleXMLDocument element MUST [resolve] to an [XML document]. Rule 5-19. c:pathURI for c:BusinessRulesArtifact [Rule 5-19] (WF-IEPD) Within an [IEPD 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-20. c:pathURI for c:XMLSchemaDocument [Rule 5-20] (WF-IEPD) Within an [IEPD catalog document], the value of a c:pathURI attribute owned by a c:XMLSchemaDocument element MUST [resolve] to an [XML schema document]. Rule 5-21. c:pathURI for c:ExternalSchemaDocument [Rule 5-21] (WF-IEPD) Within an [IEPD catalog document], the value of a c:pathURI attribute owned by a c:ExternalSchemaDocument element MUST [resolve] to an [XML schema document]. Rule 5-22. c:pathURI for c:ReferenceSchemaDocument [Rule 5-22] (WF-IEPD) Within an [IEPD 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-23. c:pathURI for c:ExtensionSchemaDocument [Rule 5-23] (WF-IEPD) Within an [IEPD 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-24. c:pathURI for c:SubsetSchemaDocument [Rule 5-24] (WF-IEPD) Within an [IEPD 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-25. c:pathURI for c:Wantlist [Rule 5-25] (WF-IEPD) Within an [IEPD 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-26. c:pathURI for c:SchematronSchema [Rule 5-26] (WF-IEPD) Within an [IEPD catalog document], the value of a c:pathURI attribute owned by a c:SchematronSchema element MUST [resolve] to a [Schematron schema]. Rule 5-27. c:pathURI for c:RelaxNGSchema [Rule 5-27] (WF-IEPD) Within an [IEPD catalog document], the value of a c:pathURI attribute owned by a c:RelaxNGSchema element MUST [resolve] to a RelaxNG schema. Rule 5-28. c:pathURI for c:SchemaDocumentSet [Rule 5-28] (WF-IEPD) Within an [IEPD 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-29. c:pathURI for c:ConstraintSchemaDocumentSet [Rule 5-29] (WF-IEPD) Within an [IEPD 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-30. Schema document set interpreted as constraint schema document set [Rule 5-30] (WF-IEPD) 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. IEPD Relationships and Lineage (c:resourceURI) An important business requirement is transparency of IEPD 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 IEPD Specification adapts the latter view of data provenance to enable a simple framework for recording IEPD lineage within an IEPD catalog. The URI scheme for IEPDs and their artifacts and sets enables a graph of relationships. An [IEPD] may internally identify and record relationships to other IEPDs, including families, versions, adaptations, specializations, generalizations, etc. The next few paragraphs require understanding of URIs for IEPDs and IEPD artifacts. See Section 5.2.4.1, IEPD URI Scheme (c:iepdURI), above, and Section 5.2.4.2, URI Scheme for IEPD Artifacts (c:externalURI), above. The IEPD 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 IEPDs. There are many ways that one [IEPD] 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 IEPDs. 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 IEPD Artifacts (c:externalURI), above, the IEPD catalog also enables an author to record more fine-grained ancestry between IEPDs using the c:externalURI attribute. This attribute records an explicit equivalence relationship between artifacts reused across IEPDs. Note that a c:resourceURI attribute is used to identify a remote resource that is only related to the IEPD whose catalog declares it. The resource is not required for validation. Therefore, the [IEPD] 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 IEPD URI with a Fragment Rule 5-31. Resolve IEPD URI with Fragment [Rule 5-31] (WF-IEPD) Given an absolute IEPD 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 IEPD. If the resource IEPD does not exist, then fail (existence error). 2. Apply the fragment (without "#") to the IEPD 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 an element information item that has an attribute xs:anyURI, 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-31, Resolve IEPD URI with Fragment. 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 [IEPD 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 IEPD validation, the following rules ensure that an XML catalog document contains URIs that correctly resolve. Rule 5-32. XML Catalog uri Value Resolves to Resource [Rule 5-32] (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-33. XML Catalog uri Value Resolves to Resource with Correct Target Namespace [Rule 5-33] (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 IEPD URIs This section summarizes the various URIs used in the IEPD 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 only (no fragment)| http://nlets.org/rap/3.1/ 2||absolute URI and optional fragment| http://nlets.org/rap/3.1/#rap-sheet2 3||optional relative part and optional fragment|/iep-sample/query.xml or #A3 or /iep-sample/query.xml#A3 4|| or |any example in 1, 2, or 3 above As the table above indicates, [RFC 3986 URI] allows a 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 . Table 5-2: Summary of IEPD URI attributes IEPD Attribute|URI Syntax (refer to table above) c:iepdURI | c:pathURI |; excluding fragment-only format; relative to [IEPD catalog document] c:externalURI | c:resourceURI | 5.3. Change Log A version identifier is a useful and simple visual indicator that an [IEPD] 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 [IEPD] since its previous version. 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-34. IEPD Has a Change Log [Rule 5-34] (IEPD) An [IEPD] MUST contain a [change log] artifact that is identified by a c:IEPDChangeLog element in its [IEPD 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 an [information exchange package documentation] 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 [IEPD]. Rule 5-35. Readme Describes Purpose, Scope, Business Value, etc. [Rule 5-35] (WF-IEPD) A [readme artifact] SHOULD (at a minimum) describe the [IEPD] purpose, scope, business value, exchange information, typical senders/receivers, interactions, and references to other documentation. Rule 5-36. IEPD Has a ReadMe Artifact [Rule 5-36] (IEPD) An IEPD MUST contain a [readme artifact] that is identified by a c:ReadMe element in its [IEPD catalog document]. The [readme artifact] may replicate some of the metadata in the IEPD catalog. However, the IEPD 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 IEPD (though it can be). It is expected to be the initial resource that references and coordinates all others whether physically present in the IEPD 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 [IEPD 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 IEPD: * Purpose of this IEPD. * 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 IEPD, 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 IEPD as well as URLs to files on the Internet. Employing such a format is highly recommended but not mandatory. IEPD 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 IEPD 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 IEPD 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 IEPD 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 IEPD may declare one or more IEP conformance targets within its [IEPD 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 IEPD artifact URI) per this rule: Rule 5-37. Conformance Target Identifier [Rule 5-37] (IEPD-catalog) A [conformance target identifier] for an [IEP conformance target] declared in an IEPD 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 [IEPD catalog document]. It supplements the rule above. Rule 5-38. IEP Conformance Target Has a structures:id [Rule 5-38] (IEPD-catalog) A c:IEPConformanceTarget element MUST own a structures:id attribute. This rule ensures that a [conformance target] can be referenced between IEPDs (not just within an IEPD). The value of the structures:id attribute is the NCName in Rule 5-37, Conformance Target Identifier. An [IEPD] defines IEP conformance targets by explicitly declaring them within its IEPD catalog per the rules above. Rule 5-39. [IEPD] Declares One or More IEP Conformance Targets [Rule 5-39] (IEPD) The [IEPD 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 [IEPD 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, IEPD 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, IEPD 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 IEPD 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 [W3C 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-40. Validity contraint context is value of c:xPathText [Rule 5-40] (IEPD-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 [W3C 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 [W3C 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-41. IEP has Document Element [Rule 5-41] (IEP) Within an IEPD 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-42. Validating an XPath Expression [Rule 5-42] (IEP) Within an [IEPD 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 3.1], 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 IEPD 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 IEPD 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 IEPD 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-37, Conformance Target Identifier a conformance target URI is formed by concatenating the [IEPD] URI (the value of c:iepdURI), 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 IEPDs. 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-43. IEPD Has an IEP Sample for Each c:IEPConformanceTarget [Rule 5-43] (IEPD) Within the IEPD 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-44. Validating an IEP Sample XML Document [Rule 5-44] (IEP) Within an [IEPD 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 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 IEPD conforms to relevant NIEM specifications and associated rules, including [NIEM Conformance Specification], [NIEM Naming and Design Rules], [NIEM Conformance Targets Attribute Specification] and this NIEM IEPD Specification. Rule 5-45. IEPD Has Conformance Assertion [Rule 5-45] (IEPD) An [IEPD] MUST contain a [conformance assertion] artifact that is identified by a c:ConformanceAssertion element in its [IEPD 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. [IEPD] users or implementers (who are not the author) must decide their 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 IEPD 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 IEPD catalog schema document provides a c:ConformanceReport element to identify a conformance report if one is present. A sample [conformance assertion], Appendix D, Conformance Assertion Example, below, is included in this specification. 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 IEPD Artifacts Aside from the required artifacts, IEPD content is relatively flexible. A variety of other optional documentation files may be incorporated into an IEPD. 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 IEPD 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 IEPD 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 IEPD author may include any files believed to be useful to understand, implement, reuse, and/or adapt an IEPD. An IEPD 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 IEPD Artifacts, below, for a listing of the mandatory and common optional artifacts for each type of IEPD.) 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 IEPD, 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 IEPDs; 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 https://www.microsoft.com/en-us/microsoft-365/microsoft-office). 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 IEPD 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-IEPD) If present, a NIEM wantlist MUST reside within the root of the IEPD 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 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 IEPD is a logical set of electronic files aggregated and organized to fulfill a specific purpose in NIEM. Directory organization and packaging of an IEPD should be designed around major themes in NIEM: reuse, sharing, interoperability, and efficiency. Rule 7-1. An IEPD in ZIP File Format Preserves Logical Directory Structure. [Rule 7-1] (WF-IEPD) An IEPD 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 IEPD must be valid for both XML Schema and NIEM. This also implies these artifacts must adhere to applicable [NIEM Naming and Design Rules] conformance target rules. Rule 7-2. XSD and XML Documents Conform to Applicable NDR Conformance Targets [Rule 7-2] (WF-IEPD) Within an IEPD, 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]) MUST satisfy the [NIEM Naming and Design Rules] rules for the conformance targets it declares. 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: IEPD root directory] The top level file directory relative to all IEPD artifacts and subdirectories. Rule 7-3. IEPD Archive Uncompresses to a Single Root Directory [Rule 7-3] (WF-IEPD) An IEPD in [ZIP file] format MUST uncompress (unzip) to one and only one [IEPD root directory]. The foregoing rule ensures that: * Unpacking an IEPD in [ZIP file] format will not scatter its contents on a storage device. * One common starting directory always exists to explore or use any IEPD. * iepd-catalog and change log artifacts will always be found in the [IEPD root directory]. 7.1. Artifact Sets Grouping artifacts into sets is generally optional. There may be many reasons for identifying artifacts sets in an IEPD. 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 IEPD 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 [IEPD 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]. 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 [IEPD catalog document] is designed to record, index, classify, and describe (as needed) any or all IEPD artifacts (not just schema documents). The IEPD catalog provides a flexible method for grouping all kinds artifacts. The IEPD catalog schema Appendix A, IEPD Catalog XML Schema Document, below, defines a set of common artifact classifiers and artifact set classifiers. In summary, per Appendix A, IEPD 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 IEPD 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. All IEP samples within this IEPD. 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 IEPD 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 IEPD catalog: Figure 7-2: c:FileSet form for a more complex artifact set. All IEP samples in this IEPD Another way the IEPD 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 IEPD, 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 [information exchange package documentation] concept, the design of the IEPD catalog schema does not enforce a rule that is required to ensure a c:SchemaDocumentSet within an [IEPD catalog document] is used correctly for an [IEPD]. This rule assumes that within the IEPD's IEPD 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] (IEPD-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 IEPD 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:iepdName attribute in the [IEPD catalog document]. Refer to Section 5.2.1, IEPD Name Syntax (c:iepdName), above, for details regarding the c:iepdName metadata attribute. The IEPD Specification is intended to help facilitate tool support for processing IEPDs. Tools and search mechanisms that can identify basic IEPD information as early as possible is efficient and valuable. So, if an IEPD 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 IEPD catalog to determine such. Of course, to do anything useful, a tool will eventually have to open the IEPD archive. However, a standard file name syntax allows a tool to search through a set of IEPDs in [ZIP file] format to find a particular IEPD name, version, or class without having to open each. File name consistency can also make it easier to scan and identify IEPDs 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-9, IEPD 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 [IEPD 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 IEPD 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 IEPD must be physically present within that IEPD. In accordance with the [NIEM Naming and Design Rules], if IEPD 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. IEPD Reference to Resource Uses Common URI Scheme [Rule 7-6] (WF-IEPD) 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 iepd-catalog.xsd or the standard NIEM subset that supports it. On the other hand, an [IEPD] whose author has extended the IEPD 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, IEPD 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 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] 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 IEPDs, the following rule applies: Rule 7-8. IEPD External Schema Documents Are Local Resources [Rule 7-8] (WF-IEPD) Within an IEPD, 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 IEPD are present within it. XML schemas are the heart of IEPDs since they formally specify normative structure and semantics for [data components]. However, in general, an IEPD is a closed set of artifacts. This means that all hyperlink references within artifacts should [resolve] to the appropriate artifact. Rule 7-9. Key IEPD Resources Are Local Resources [Rule 7-9] (WF-IEPD) Within any artifact of an IEPD, 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 IEPD at the location specified by that reference. This means that IEPD artifacts, including documentation artifacts, should be complete. For example, if an HTML document within an IEPD contains a hyperlink reference (href) to an artifact that is part of or used by the IEPD, then the file associated with that hyperlink should be present in the IEPD; likewise for a sourced (src) image. Authors should exercise good judgment with this rule. For example, it does not require an IEPD 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 IEPD." In some cases, it may not be possible to include all artifacts, even schemas, in an IEPD 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 IEPD 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 IEPD, 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 IEPD. 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. IEPD Catalog XML Schema Document Information Exchange Package Documentation (IEPD) Catalog schema document. Defines an iepd-catalog.xml artifact for IEPDs. The purpose of this schema is to facilitate consistent declaration of IEPD content, conformance targets, metadata, and lineage to process, display, review, register, search, and discover IEPDs efficiently, as well as instructions for validating IEPs to IEPDs. This XML Schema document is supported by a subset of NIEM 5.0. An IEPD catalog that describes IEPD artifacts and metadata. A data type for an IEPD catalog. A data concept for a file or file set in an IEPD. A generic electronic file artifact in an IEPD; a file stored on a computer system. A data type for an IEPD file artifact. An IEPD artifact that is an OASIS XML catalog. An IEPD artifact that contains a record of the IEPD changes. An IEPD read-me artifact. An example IEPD instance XML document or IEP artifact. An IEPD artifact that contains business rules and constraints on exchange content. An IEPD artifact that is an XML schema document (i.e., an XSD that is not necessarily a NIEM subset, extension, or reference schema). An IEPD artifact that is a schema document external to NIEM. An IEPD artifact that is a NIEM extension schema document. An IEPD artifact that is a subset schema document. An IEPD artifact that is a reference schema document (from a release, domain update, or core update). An XML Schema to be used for EXI serialization of an IEP Class. An IEPD artifact that represents a NIEM schema subset and is used as an import or export for the NIEM SSGT. An IEPD artifact that is a signed declaration that a NIEM IEPD is NIEM-conformant. An IEPD 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. A Schematron schema document. A RelaxNG schema. An IEPD artifact that is a form of explanatory documentation. An IEPD artifact that is used by a software tool (e.g., import, export, input, output, etc.). An IEPD file artifact that another artifact depends on and should not be separated from. A generic IEPD artifact set; used to group artifacts that are not accounted for by other set classifiers. A data type for a set of IEPD file artifacts. An IEPD artifact set that may include subset schema documents, extension and external schema documents, and other supporting artifacts. An IEPD artifact set of constraint schema documents and other supporting artifacts. A data type for an IEPD artifact set that may include subset schema documents, extension schema documents, and external schema documents or constraint schema documents. A globally unique identifier (URI) for an IEPD. A descriptive label or title for an IEPD. A data type for an IEPD name, label, or title. An identifier that distinguishes releases of a given IEPD. A data type for an identifier that distinguishes releases of a given IEPD. A list of one or more URIs that each represents an IEPD class to which the IEPD claims conformance. A data type that ensures at least one conformance target is identified as an IEPD conformance target. A data type for one or more URIs that are IEPD conformance target classes. A URI for the pathname of a local artifact relative to the IEPD root directory. A globally unique identifier (URI) for an artifact in another IEPD that is reused by this IEPD. A classification for an IEPD file artifact from the IANA MIME media classes: http://www.iana.org/assignments/media-types. A data type for a reference to another IEPD related to this IEPD. A globally unique identifier (URI) for another IEPD or document to which this IEPD relates. A classification or reason for the connectedness between this IEPD and the resource referenced in resourceURI. A data type for a classification of the relationship between IEPDs. A relationshipCode value for indicating that this IEPD is a different version of the IEPD 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. A relationshipCode value for indicating that this IEPD is a specialization of the IEPD referenced in resourceURI. This value is the inverse of generalizes. A relationshipCode value for indicating that this IEPD is a generalization of the IEPD referenced in resourceURI. This value is the inverse of specializes. A relationshipCode value for indicating that this IEPD replaces the IEPD referenced in resourceURI. A relationshipCode value for indicating that content in this IEPD is preferred over content in the IEPD referenced in resourceURI; and at some time in the future will supersede the IEPD referenced in resourceURI. A relationshipCode value for indicating that this IEPD is an adaptation of the IEPD referenced in resourceURI. A relationshipCode value for indicating that this IEPD is an incremental update to the resource referenced in resourceURI. A relationshipCode value for indicating that this IEPD conforms to the specification or standard referenced in resourceURI. A relationshipCode value for indicating that this IEPD has been derived from another (may have other uses as well). 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. A data type for a class or category of IEP, which has a set of validity constraints and a unique identifier. A data concept for a rule or instructions for validating an IEP candidate (XML document) using some context within that XML document. A data concept for a rule or instructions for validating an IEP candidate. A rule or instructions for validating an IEP candidate within context defined by an XPath expression. A data type for a rule or instructions for validating an IEP candidate within context defined by an XPath expression. A validity constraint that has a an XPath expression that MUST have an effective Boolean value of "TRUE" when applied to a valid IEP. A data type for an XPath expression. An XPath expression. 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. 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. 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. 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. A validity constraint that indicates that an artifact must be valid against the rules carried by a RelaxNG schema. 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. A validity constraint that indicates that an artifact has a document element with a name that is one of the given qualified names. A data type for a set of qualified names. A list of qualified names. A data type for a list of qualified names. A validity constraint that indicates that an artifact must conform to the given conformance target. A data type for identifying and describing a conformance target. A URI for a conformance target. A validity constraint that indicates that an artifact must conform to the given text rule, drafted in a human language. A data type for a rule drafted in a human language. A rule written in a human language. A set of descriptive data about an IEPD. A data type for a set of descriptive data about an IEPD. A data concept for a user-defined descriptive data about an IEPD. An official sponsoring or authoring organization responsible for an IEPD. A date this IEPD was published. A date the latest changes to an IEPD were published (i.e., CreationDate of previous version). A description of the current state of this IEPD in development; may also project future plans for the IEPD. A reference to another IEPD related to this IEPD. A common alias, term, or phrase that would help to facilitate search and discovery of this IEPD. A description of the environment or NIEM Domain in which this IEPD is applicable or used. A description of the intended usage and reason for which an IEPD exists. A description of a transactional or design pattern used for this IEPD. A name of an entity or organization that uses this IEPD. Appendix B. Example IEPD Catalog Document for Cursor on Target Below is a simple example of an IEPD catalog document for a Cursor on Target [IEPD]. The entire [IEPD] and other example IEPDs and supporting artifacts are available on the [NIEM Template IEPD repository]. CoT Program Office https://partners.mitre.org/sites/CoTUserGroup/ 2014-08-04 Release Candidate An IEP class equivalent to Cursor-on-Target 2.0 messages Appendix C. Common IEPD Artifacts Notes: * (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 (IEPD) [IEPD catalog document]|iepd-catalog.xml|(ref) (IEPD) [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) IEPD catalog extension [XML catalog document]|iepd-catalog-extension-xml-catalog.xml|an XML catalog that identifies an IEPD catalog extension schema document (ref) IEPD catalog [extension schema document]|*.xsd|a XML schema document that extends an IEPD 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, IEPD Archive Uncompresses to a Single Root Directory) 2. For every IEPD, an iepd-catalog.xml artifact (Rule 5-1, IEPD Has an iepd-catalog.xml in its Root Directory) is required to be in the [IEPD root directory] 3. If extending the [IEPD catalog document], then per Rule 5-3, IEPD Catalog Extension XML Catalog Document in Root Directory iepd-catalog-extension-xml-catalog.xml must reside in the same relative directory as the iepd-catalog.xml it supports (normally, the [IEPD root directory]). iepd-catalog-extension.xsd can be located anywhere in the IEPD because iepd-catalog-extension-xml-catalog.xml correlates its namespace to its URI. However, this specification recommends both artifacts be co-located in the [IEPD root directory] for visibility: * iepd-catalog-extension-xml-catalog.xml (Rule 5-3, IEPD Catalog Extension XML Catalog Document in Root Directory) * iepd-catalog-extension.xsd 4. Include the following artifacts and ensure each is identified (tagged) appropriately within the [IEPD catalog document]: * readme artifact * change log artifact * conformance-assertion artifact * conformance-report artifact (if present) Recommend these artifacts be located in the [IEPD root directory]. 5. Create the following directories within the [IEPD 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-43, 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 [IEPD 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 IEPD 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) iepd-catalog.xml (normative artifact name) iepd-catalog-extension.xsd iepd-catalog-extension-xml-catalog.xml (normative artifact name) changelog.* conformance-assertion.* readme.* /base-xsd /niem (subset) /xsd /adapters /auxiliary /codes /genc /domains /external /have /ogc /utility appinfo.xsd code-lists-instance.xsd code-lists-schema-appinfo.xsd conformanceTargets.xsd structures.xsd niem-core.xsd 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 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 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 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 [BCP 14]: "Internet Engineering Task Force Best Current Practice 14." Available from https://www.ietf.org/rfc/bcp/bcp14.txt. BCP 14 is composed of: [RFC 2119]: Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels," BCP 14, RFC 2119, March 1997. Available from http://www.ietf.org/rfc/rfc2119.txt. [RFC 8174]: Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words," BCP 14, RFC 8174, May 2017. Available from https://www.ietf.org/rfc/rfc8174.txt. [FEA Data Reference Model 1.0]: "The Federal Enterprise Architecture Data Reference Model," Version 1.0, September 2004. The version 1.0 document is longer publicly available. A more recent DRM Version 2.0, 17 November 2005 is available from https://obamawhitehouse.archives.gov/sites/default/files/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 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]: "Document Schema Definition Languages (DSDL) -- Part 3: Rule-based validation using Schematron," ISO/IEC 19757-3:2020, Third Edition, 2020-06. Available from https://www.iso.org/standard/74515.html. [Logical Entity Exchange Specifications]: "Logical Entity Exchange Specifications," Version 5.0, 12 October 2016. Available from https://it.ojp.gov/NISS/iepd/457. [NIEM Code List Specification]: Webb Roberts, ed. "National Information Exchange Model Code Lists Specification," Version 4.0, NIEM Technical Architecture Committee (NTAC). Available from https://reference.niem.gov/niem/specification/code-lists/4.0/. [NIEM Conformance Specification]: "National Information Exchange Model Conformance Specification," Version 5.0, NIEM Technical Architecture Committee (NTAC). Available from https://reference.niem.gov/niem/specification/conformance/5.0/. [NIEM Conformance Targets Attribute Specification]: "NIEM Conformance Targets Attribute Specification," Version 3.0, NIEM Technical Architecture Committee (NTAC). Available from https://reference.niem.gov/niem/specification/conformance-targets-attribute/3.0/. [NIEM High-Level Version Architecture]: "NIEM High Level Version Architecture (HLVA)," Version 3.0, NIEM Technical Architecture Committee. Available from https://reference.niem.gov/niem/specification/high-level-version-architecture/3.0/. [NIEM Naming and Design Rules]: Webb Roberts. "National Information Exchange Model Naming and Design Rules," Version 5.0, NIEM Technical Architecture Committee (NTAC). https://reference.niem.gov/niem/specification/naming-and-design-rules/5.0/. [NIEM SSGT]: "NIEM Schema Subset Generation Tool (SSGT)." Available from http://tools.niem.gov/niemtools/ssgt/index.iepd. [NIEM TechHub]: NIEM's TechHub provides the developer community with resources and training that will help them use NIEM. Available from https://niem.github.io/. [NIEM Template IEPD repository]: The NIEM Template IEPD can be used as a starting point or a reference for developing a new IEPD. Available from https://github.com/NIEM/Template-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 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 (Second Edition), W3C Recommendation, 11 February 2014. Available from http://www.w3.org/TR/2014/REC-exi-20140211/. [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/. [W3C XML InfoSet]: "XML Information Set," Second Edition, W3C Recommendation 4 February 2004. Available from http://www.w3.org/TR/2004/REC-xml-infoset-20040204/. [W3C XML Namespaces]: "Namespaces in XML 1.0," Third Edition, World Wide Web Consortium 8 December 2009. Available from https://www.w3.org/TR/2009/REC-xml-names-20091208/. [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 3.1]: "XML Path Language (XPath) 3.1," W3C Recommendation 21 March 2017. Available from https://www.w3.org/TR/2017/REC-xpath-31-20170321/. [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, Second Edition, W3C Recommendation 21 April 2009. Available from https://www.w3.org/TR/2009/PER-xslt20-20090421/. [XSLT 3.0]: "XSL Transformations (XSLT)," Version 3.0, W3C Recommendation 8 June 2017. Available from https://www.w3.org/TR/2017/REC-xslt-30-20170608/. Appendix H. Index of Definitions The index of definitions is omitted from this edition. Appendix I. Index of Rules Rule 3-1, IEPD conformance target identifier: Section 3.2.1, Information Exchange Package Documentation Rule 3-2, IEPD is well-formed: Section 3.2.1.1, Well-Formed IEPD Rule 4-1, Fundamental NIEM Subset Rule: Section 4.2.1, Basic Subset Concepts Rule 5-1, IEPD Has an iepd-catalog.xml in its Root Directory: Section 5.1, NIEM IEPD Catalog Rule 5-2, IEPD Catalog Document Valid to iepd-catalog.xsd: Section 5.1, NIEM IEPD Catalog Rule 5-3, IEPD Catalog Extension XML Catalog Document in Root Directory: Section 5.1.2, Extending an IEPD Catalog Rule 5-4, IEPD Catalog Extension XML Catalog Document Name Is iepd-catalog-extension-xml-catalog.xml: Section 5.1.2, Extending an IEPD Catalog Rule 5-5, IEPD Catalog Extension XML Catalog Document Resolves Namespaces to URIs: Section 5.1.2, Extending an IEPD Catalog Rule 5-6, IEPD Catalog Extension Schema Document Conforms to NDR Extension Schema Document Rules: Section 5.1.2, Extending an IEPD Catalog Rule 5-7, IEPD Catalog Schema and Its Extensions Conform to NDR Schema Set Rules: Section 5.1.2, Extending an IEPD Catalog Rule 5-8, IEPD Schema Document Extension Support Schemas Are Supersets of Spec Subsets: Section 5.1.2, Extending an IEPD Catalog Rule 5-9, IEPD Version Number Syntax: Section 5.2.3, IEPD Version Numbering Scheme (c:iepdVersionID) Rule 5-10, IEPD URI Is Absolute: Section 5.2.4.1, IEPD URI Scheme (c:iepdURI) Rule 5-11, IEPD URI Supports Fragment: Section 5.2.4.2, URI Scheme for IEPD Artifacts (c:externalURI) Rule 5-12, IEPD URI Has No Fragment: Section 5.2.4.2, URI Scheme for IEPD Artifacts (c:externalURI) Rule 5-13, IEPD Artifact URI Syntax: Section 5.2.4.2, URI Scheme for IEPD Artifacts (c:externalURI) Rule 5-14, c:pathURI Resolves to a Resource: Section 5.2.4.3, URI Scheme for Local IEPD Artifacts (c:pathURI) Rule 5-15, c:pathURI for c:XMLCatalog: Section 5.2.4.3, URI Scheme for Local IEPD Artifacts (c:pathURI) Rule 5-16, c:pathURI for c:IEPDChangeLog: Section 5.2.4.3, URI Scheme for Local IEPD Artifacts (c:pathURI) Rule 5-17, c:pathURI for c:ReadMe: Section 5.2.4.3, URI Scheme for Local IEPD Artifacts (c:pathURI) Rule 5-18, c:pathURI for c:IEPSampleXMLDocument: Section 5.2.4.3, URI Scheme for Local IEPD Artifacts (c:pathURI) Rule 5-19, c:pathURI for c:BusinessRulesArtifact: Section 5.2.4.3, URI Scheme for Local IEPD Artifacts (c:pathURI) Rule 5-20, c:pathURI for c:XMLSchemaDocument: Section 5.2.4.3, URI Scheme for Local IEPD Artifacts (c:pathURI) Rule 5-21, c:pathURI for c:ExternalSchemaDocument: Section 5.2.4.3, URI Scheme for Local IEPD Artifacts (c:pathURI) Rule 5-22, c:pathURI for c:ReferenceSchemaDocument: Section 5.2.4.3, URI Scheme for Local IEPD Artifacts (c:pathURI) Rule 5-23, c:pathURI for c:ExtensionSchemaDocument: Section 5.2.4.3, URI Scheme for Local IEPD Artifacts (c:pathURI) Rule 5-24, c:pathURI for c:SubsetSchemaDocument: Section 5.2.4.3, URI Scheme for Local IEPD Artifacts (c:pathURI) Rule 5-25, c:pathURI for c:Wantlist: Section 5.2.4.3, URI Scheme for Local IEPD Artifacts (c:pathURI) Rule 5-26, c:pathURI for c:SchematronSchema: Section 5.2.4.3, URI Scheme for Local IEPD Artifacts (c:pathURI) Rule 5-27, c:pathURI for c:RelaxNGSchema: Section 5.2.4.3, URI Scheme for Local IEPD Artifacts (c:pathURI) Rule 5-28, c:pathURI for c:SchemaDocumentSet: Section 5.2.4.3, URI Scheme for Local IEPD Artifacts (c:pathURI) Rule 5-29, c:pathURI for c:ConstraintSchemaDocumentSet: Section 5.2.4.3, URI Scheme for Local IEPD Artifacts (c:pathURI) Rule 5-30, Schema document set interpreted as constraint schema document set: Section 5.2.4.3, URI Scheme for Local IEPD Artifacts (c:pathURI) Rule 5-31, Resolve IEPD URI with Fragment: Section 5.2.4.5, Resolving an IEPD URI with a Fragment Rule 5-32, XML Catalog uri Value Resolves to Resource: Section 5.2.4.7, XML Catalog URI Rule 5-33, XML Catalog uri Value Resolves to Resource with Correct Target Namespace: Section 5.2.4.7, XML Catalog URI Rule 5-34, IEPD Has a Change Log: Section 5.3, Change Log Rule 5-35, Readme Describes Purpose, Scope, Business Value, etc.: Section 5.4, ReadMe Artifact Rule 5-36, IEPD Has a ReadMe Artifact: Section 5.4, ReadMe Artifact Rule 5-37, Conformance Target Identifier: Section 5.6, Defining Information Exchange Packages Rule 5-38, IEP Conformance Target Has a structures:id: Section 5.6, Defining Information Exchange Packages Rule 5-39, [IEPD] Declares One or More IEP Conformance Targets: Section 5.6, Defining Information Exchange Packages Rule 5-40, Validity contraint context is value of c:xPathText: Section 5.6.2.3, c:ValidityContext Rule 5-41, IEP has Document Element: Section 5.6.2.4, c:HasDocumentElement Rule 5-42, Validating an XPath Expression: Section 5.6.2.5, c:ValidToXPath Rule 5-43, IEPD Has an IEP Sample for Each c:IEPConformanceTarget: Section 5.6.3, IEP Sample Instance XML Documents Rule 5-44, Validating an IEP Sample XML Document: Section 5.6.3, IEP Sample Instance XML Documents Rule 5-45, IEPD Has Conformance Assertion: Section 5.7, Conformance Assertion Rule 6-1, Wantlist Location: Section 6.1, NIEM Wantlist Rule 7-1, An IEPD 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, IEPD 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, IEPD 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, IEPD External Schema Documents Are Local Resources: Section 7.4, IEPD Completeness Rule 7-9, Key IEPD Resources Are Local Resources: Section 7.4, IEPD Completeness