Each IEPD is a package that contains schemas and other supporting files.
See the Information Exchange Package Documentation (IEPD) Specification for more information about these artifacts.
An IEPD must include either a local copy of the schemas from a NIEM release or a custom subset of that NIEM release. Because NIEM is a large data model, a subset is usually much easier to deal with in an IEPD. A subset should include only the properties and types from the release that are actually needed by the IEPD, plus any dependencies.
The SSGT can be used to generate a NIEM XML schema subset.
See the Subset schemas page in this section for more details.
An IEPD will include one or more extension schemas. These are schemas created by the IEPD developer in order to define properties and types needed by the IEPD that do not already exist in NIEM.
The NIEM Naming and Design Rules (NDR) specification provides rules and guidance on how components for both release schemas and IEPD extension schemas should be modeled. in Reference / Concepts section on this site explains some of Artifacts section for more.that information.
Many of the rules from the NDR are defined in Schematron so that conformance testing can be automated against NIEM XML schemas. ConTesA and Oxygen are both capable of evaluating these NDR Schematron rules.
- ConTesA is free to use and will generate a conformance report that can be included in the IEPD.
- Oxygen requires a paid license but may be easier to use frequently during schema development because Schematron errors are checked and displayed similarly to standard XML validation errors.
See the Extension schema page in this section for more details.
A change log can be a summary or a detailed description of the changes in this IEPD since the previous versions. NIEM release provide change logs in the form of a spreadsheet but free text descriptions in a document or text file are fine.
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.
A conformance assertion can also contain information about any known issues in the IEPD and the reasons for which they may have been necessary.
As part of a conformance assertion, additional artifacts may also be included in the IEPD:
An IEPD Catalog is an XML document that contains basic information about the package (name, description, purpose, point of contact, etc.) and a listing of the package’s key artifacts. This file has the name iepd-catalog.xml and resides in the IEPD root directory.
See the IEPD Catalog page in this section for more details.
A readme artifact is mandatory for all IEPDs. Additional documentation can be included in an IEPD as desired, but a readme will serve as the common starting point and is the required minimum for human-readable documentation.
A readme should include information that describes the following:
The readme does not have a required file format. Word documents, text, and markdown are common formats.
A sample message (also known as sample instances or sample IEPs) is an example of an actual message that will be exchanged based on the IEPD. The data should be realistic and the sample message should clearly illustrate to IEPD implementers what the real-world messages should look like.
More than one kind of message can be defined within a single IEPD. At least one sample message should be provided for each.
Sample messages in an IEPD also provide the IEPD developer with the opportunity to better test the IEPD schemas that are being developed. Confirming that sample messages can carry all of the expected data from the data requirements helps to ensure that the schemas are wired up correctly and that little things haven’t been forgotten, like missing substitutions, incomplete subsets, or properties that haven’t been added to the right types.
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:
Business rules are defined in artifacts with informal text or formally coded machine-readable statements that describe business policy or procedure or special data constraints that may be difficult or impossible to specify in schema. Schematron is the recommended format for specifying additional data constraints on XML messages. Informally written rules may be very difficult or impossible to validate but allow the author to present them in the IEPD.
NIEM supports enhanced code lists in addition to typical schema enumerations. These code lists may be static (defined in the IEPD) or dynamic (defined at a URL and potentially updated after the IEPD is locked and published) and can be defined as CSVs or Genericode.
See Code Lists in the Reference / Artifacts section for more.
A constraint schema is a schema that usually starts from a subset schema and is modified by hand in order to add custom-tailored constraints and restrictions on instance messages that go beyond setting cardinality limits.
Some things in a constraint schema must remain the same in order to maintain fidelity with the original schemas. For example, property names and the order in which they appear cannot be changed because this would affect the tags in the instances. However, because type information usually does not appear in an instance, properties can be rewritten with customized local types.
nc:TextType or niem-xs:string can be rewritten to have custom string types with individual maximum character lengths or patterns.nc:PersonType in the NIEM release or subset schemas and nc:PersonType would include the superset of all of the person-related requirements. In a constraint schema, however, the child property could be rewritten so that it only includes the exact properties that are allowed to be shared (perhaps like first name and age only) while the other kinds of persons in the message could be defined with additional fields.The use of constraint schemas requires instance validation to be performed in two passes:
XML catalogs can be used to assign different file locations to schema namespaces for the separate validation passes.
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. Constraint schemas do remain an option, however, that may be useful for situations where the XML schemas themselves are required to be tightened down as much as possible.
External standards may be included in IEPDs for information that is already commonly shared within the exchange’s target community according to a standard defined outside of NIEM. GML is one such external standard already included with NIEM releases, but IEPDs may require others. In these cases, it may not make sense to provide an alternate NIEM-representation of data that already has a well-defined and commonly understood format.
To use an external standard:
external folder under the base-xsd folder, next to other folders for the NIEM subset and IEPD extension schemas.A mapping spreadsheet can be used to explicitly document mappings from data requirements to properties and types in NIEM. It can also be used to model extensions for requirements that do not exist in NIEM.
See the Mapping Spreadsheet page in this section for more details, plus the spreadsheet template and examples.
A wantlist is a custom XML file generated by the SSGT that saves the list of properties and types that were added to the subset. In other words, it describes what an exchange “wants” from the NIEM data model.
If the IEPD includes a NIEM subset and that subset was generated by the SSGT, the wantlist should be included in the IEPD as well. This ensures that the subset can be reloaded in the SSGT for future updates without having to start the subset over.
XML catalog files can be used to specify or override the file locations associated with schema namespaces.
See XML Catalog in the Reference / Artifacts section for more.Artifacts section for more.
The IEPD Specification does not contain normative rules on how to structure the folders and place the files in an IEPD, but guidance is provided. A recommended layout is provided below:
See Appendix E. Guidance for IEPD Directories (non-normative) from the IEPD Specification for more information and helpful tips on how to organize an IEPD.
myIEPD-2.0/
iepd-catalog.xml # IEPD catalog
changelog.* # Change log
conformance-assertion.* # Conformance assertion
readme.* # Readme
base-xsd/ # Schema folder
niem/ # NIEM subset schemas
xsd/
adapters/
codes/
domains/
external/
utility/
niem-core.xsd
wantlist.xml # SSGT wantlist
xml-catalog.xml
extension/ # IEPD extension schemas
extension1.xsd
extension2.xsd
...
xml-catalog.xml
external/ # Schemas from external standards
ic-ism/
...
xml-catalog.xml
iep-sample/ # Sample messages
message1.xml
message2.xml
documentation/ # Human-readable documentation
...
For more details on some of the artifacts described above, please see the following pages in this section: