1. Home
  2. Training
  3. IEPD Developer
  4. Assemble and Document

Assemble and Document

The assemble and document phase is the next step you take in IEPD development.

You have all your schemas and supporting documentation ready. Now you need to gather all of it in one electronic package.

Mandatory IEPD Artifacts

The following table lists the documents (artifacts) you must have in an IEPD. All of them must be NIEM-conformant.

Artifact Description
MPD Catalog The MPD Catalog is an XML file that identifies, locates, and classifies key artifacts in an IEPD. It also includes metadata such as points of contact.

This file has the name “mpd-catalog.xml” and resides in the IEPD root directory.
XML Catalog The XML Catalog is an XML file that is used to assemble the schema from the XSD files, and it identifies which XSD file defines which namespaces.

This file typically has the name “xml-catalog.xml.” The IEPD can have multiple files with that name in different folders. An XML Catalog may point to other catalogs to describe a complete XML schema.
Change Log The Change Log is a text file that records cumulative changes from previous IEPD versions. The initial change log records its creation date.
Readme Readme is a text file that provides introductory information about the IEPD. This is the file a user normally wants to read first.
Subset Schema A Subset Schema can be generated by a number of tools from a variety of inputs (e.g., wantlists, XML files). It should always validate against the entire reference schema.
Conformance Assertion A Conformance Assertion is a document that declares the IEPD conforms to relevant NIEM specifications and associated rules. Although it increases the level of confidence that an IEPD was checked for NIEM conformance and quality, it does NOT constitute a guarantee or contract because it can be self-asserted.

Inclusion of a conformance assertion made by a reputable, independent, trusted entity (person or organization) can increase confidence in conformance, especially if it includes information such as a formal conformance test report or similar artifact.
Sample Instance A Sample Instance is an XML instance with real (or realistic) data that must be supplied for each conformance target. However, a sample can serve as an example for more than one target. If as many data components and validity constraints as possible are exercised, the sample helps an IEPD implementer to understand the original intent of the IEPD author.

Readme

As a starting point, logically organize the Readme document in chronological order of the development artifacts. Existing IEPD master documents can be used as a general guide. The Readme document can be a simple-text file and should not include XML code.

The following is a general table of contents.

  1. Executive Summary
  2. [Name] Information Exchange
    • Overview of the [Name] Exchange
    • Exchange Partner Interaction
  3. Business Models
  4. Business Rules and Requirement
  5. Exchange Content Model
  6. Development Information
    • IEPD Definition
    • Tools and Methodologies
    • Testing and Conformance
  7. Appendices
    • List of IEPD Artifacts
    • IEPD Catalog

Change Log

The Change Log can be a simple-text file.

Version Date Description Author
1.0 2/2/03 Original Version Bob
1.1 4/16/03 Added new elements to subset schema. Bill
2.0 5/9/18 Updated requirements and constraint schema. Sara

The following table lists artifacts that we recommend you include in an IEPD. All of them must be NIEM-conformant.

Artifact Description
Extension Schema An Extension Schema is a schema document that defines new components in a new namespace. The components are not found within NIEM, but they may be derived from it. The extension schema may also include reusable data components for a given exchange with the consideration that if the data objects in the extension schema will be reused, it is better to have a separate schema and local namespace defined for that schema. You can have more than one extension schema in an IEPD.

An extension schema defines the root (highest level) element of the exchange, as well as any other content specific to an IEPD that will not be reused by other IEPDs.
Constraint Schema A Constraint Schema is a schema document, usually derived from a schema subset, that imposes restrictions more complex than cardinality on an IEP. A NIEM-conformant IEP needs an additional check against the constraint schema. Constraint schemas do not provide clear visibility or explanation of the constraints they enforce; nor do they provide clear validation failure messages. Thus the use of constraint schemas is discouraged.

A generally better way to impose additional rules on an IEP is to use Schematron. It provides facilities for better understanding of the business rules, their intent, and error handling of failures.
Wantlist A Wantlist is an XML file that contains the elements and types from NIEM that will be included within the subset schema for the exchange. In other words, it describes what an exchange “wants” from the NIEM data model. You can create one manually or use a tool such as the SSGT, which can create a wantlist, or generate a subset schema based on an existing wantlist. Thus the wantlist can be an output that serves as an IEPD artifact, or it can be the input to generate an expanded wantlist. Although it is not required, you should include a wantlist in the package.
Code List A Code List is an XML schema of allowable values for a data element within an exchange. It is typically a table with rows as distinct entries, columns as code list columns, and individual cells as code values. The list can be manually created from previously developed XML schemas with XML code inserted through the use of enumeration facets.
Business Rules Business Rules are a separate document with informal text or formally coded machine-readable statements that describe business policy or procedure. The document defines or constrains some aspect of a process or procedure, and should be validated with Schematron. Informally written rules may be very difficult or impossible to validate but allow the author to present them in the IEPD.

Assemble the IEPD

Once all IEPD artifacts have been compiled, the next step is to properly name, file, and archive the final package.

A standardized file structure promotes consistency and creates logical navigation through a large number of IEPD artifacts. Moreover, this consistency enables a greater degree of discovery and IEPD reuse because you can easily access information in a structured and uniform manner. Note that the catalog enables IEPD developers to locate artifacts in a directory and label them as specific IEPD artifacts no matter where they exist in the package.

  1. Name each artifact for your exchange with a consistent naming convention.
  2. File each artifact in a logical, consistent folder structure.
  3. Archive (e.g., zip) the file structure, including artifacts, into the final package.

The following example shows a recommended IEPD folder structure and file location. Note that the documentation produced by the SSGT creates some of the structure for you.

The root directory name should be meaningful and include the NIEM version and a revision number.

my-iepd-4.0-rev-04

  • documentation (miscellaneous, binaries)
  • iep-samples
  • xsd
    • wantlist.xml
    • xml-catalog.xml
  • extension
  • niem
    • appinfo/4.0
    • conformanceTargets/4.0
    • localTerminology/4.0
    • niem-core/4.0
    • proxy/xsd/4.0
    • structures/4.0
  • schematron (if Schematron is used)
  • changelog.txt (.md, .htm, .pdf; should be in root directory)
  • conformance-assertion.txt (.md, .htm, .pdf; should be in root directory)
  • mpd-catalog.xml (must be in root directory)
  • readme.txt (.md, .htm, .pdf; should be in root directory)

Review the IEPD

You should perform a peer review of your IEPD. This has several benefits:

  • Maintains consistent quality of artifact content and presentation.
  • Decreases the occurrence of published IEPDs that are difficult to reuse.
  • Peer participation in a review also increases individual knowledge of information exchanges and promotes accountability in verifying that the exchange meets established requirements.

A good way to review an IEPD is to compare it to a checklist. The checklist should include the following:

  • The readme document contains documentation necessary to effectively describe the information exchange.
  • The exchange content model file is included and accurately represents the XML code in the schemas.
  • The XML catalog validates with the NIEM Model Package Description (MPD) catalog schema (XSD) and resides in the root directory of the MPD bearing the file name “mpd-catalog.xml.”
  • The change log is in the root directory of the IEPD, begins with the substring “changelog,” and records changes to previous IEPD schemas that are represented.