NIEM Code Lists Specification
Version 4.0
November 7, 2017
NIEM Technical Architecture Committee (NTAC)
Abstract

This document establishes methods for using code list artifacts with NIEM information exchange specifications. It provides for the use of Genericode documents, as well as for CSV code lists. It supports the use of code lists at schema definition time, via annotations for XML Schema documents that bind schema components to code lists. It supports the use of code lists at run time, via XML Schema components for use in XML documents that bind XML data to code lists. It also includes identifiers for well-known columns that have semantics needed across the NIEM community.

Authors

Webb Roberts, Georgia Tech Research Institute (<webb.roberts@gtri.gatech.edu>), Lead Author

Document Status

This document is a specification product of the NIEM Technical Architecture Committee (NTAC). This version of this document is normative for the conformance targets it defines.

Updates, revisions, and errata for this specification are posted to https://github.com/NIEM/NIEM-Code-Lists-Spec. Please submit comments on this specification as issues at https://github.com/NIEM/NIEM-Code-Lists-Spec/issues.

Table of Contents
Table of Figures
Table of Tables
1. Introduction

This document establishes methods for using code list artifacts with NIEM information exchange specifications. It provides for the use of Genericode documents, as well as for CSV code lists. It supports the use of code lists at schema definition time, via annotations for XML Schema documents that bind schema components to code lists. It supports the use of code lists at run time, via XML Schema components for use in XML documents that bind XML data to code lists. It also includes identifiers for well-known columns that have semantics needed across the NIEM community.

This specification supplements the use of XML Schema enumerations and simple types as a representation of code lists for information exchanges, which is sufficient for many use cases. The use of separate artifacts for code lists, along with annotations for XML Schema documents, has several goals and benefits, including include:

This specification expands support for code lists, by enabling code lists to be managed independently of XML Schema documents, while still allowing them to support development of XML schemas and to be used for run-time validation. With the support of this specification, a single revision of a code list document may be used with multiple information exchange specifications. As well, a single information exchange specification may be used with multiple versions of a code list.

Features of this specification may be used in combination with other methods of representing code lists in exchanges, such as the use of enumerated values in simple types defined by XML Schema documents.

This specification describes an abstract model for code lists, and describes implementation of that model via Genericode and CSV files. Use of additional representations may be incorporated into future versions of this specification, as needed. In addition, the metadata and methods described by this document may support web service interactions for code list access, although such a mechanism is not described herein.

1.1. Code list example

This section provides an example of a code list and how that code list can be integrated with XML Schemas to provide additional validation and meaning to messages. Take as an example a code list for vehicle makes and models:

Table 1-1: Example code list: vehicle makes and models
Make codeMake descriptionModel codeModel descriptionClass
FORDFordFUSFusionAuto
HONDHondaCIVCivicAuto
HONDHondaCRVCRVSUV
DODGDodgeR15Ram 1500Pickup
NISSNissanALTAltimaAuto
FORDFordF15F-150Pickup
TOYTToyotaCOACorollaAuto
FORDFord500Five HundredAuto
HONDHondaACCAccordAuto
TOYTToyotaCAMCamryAuto
CHEVChevroletSLVSilveradoPickup
MERZMercedes-Benz500500 SeriesAuto

To take the summary from Section 2.9, Code Lists, below:

To summarize, a code list is a set of distinct entries with a corresponding set of columns. Each distinct entry contains a set of code values. Each code value corresponds to a distinct column in the code list. Each column identifies and describes the code values within the distinct entries of the code list. A code list identifier is a name for the code list as a whole, and a column name is a name of a single column within a code list.

In this example:

What we see above is a code list, but there are things missing; in order to make code lists and their uses machine-readable and verifiable, this specification provides:

  1. Machine-readable formats for code lists. This specification provides for the use of Genericode (an XML representation) and CSV files to represent code lists. It also provides a foundation for other representations of code lists, to be identified and implemented later.
  2. Identifiers for code lists. This specification defines that an absolute URI is an identifier for a code list (as well, [Genericode] distinguishes between an identifier for a class of code lists and an identifier for a particular version of a code list). This specification also defines an absolute URI as an identifier for a column, and a character string value as a name of a column within a code list.
  3. Mechanism for resolving code lists. This specification leverages XML Catalogs to resolve code list identifier URIs into code list documents.
  4. Mechanism for identifying the use of a code list in an XML message, such that it can be identified or specified by the exchanged message itself. This specification provides several XML attributes (in the code lists instance namespace) that label XML element content as corresponding to code values in a code list.
  5. Mechanism for identifying use of a code list in an XML Schema, such that it can be determined at IEPD development time or system load time. This specification provides a small XML vocabulary (in the code lists schema appinfo namespace) that annotates XML Schema component definitions, to describe correspondences between XML content and code values in a code list.
  6. Matching values in an XML instance document to code list distinct entries: This specification defines matches between a code list binding and a code list. Each code list binding may result in zero or more matches to distinct entries in a code list.
1.2. Machine-readable format for a code list

This specification provides for representing code lists using CSV files and Genericode files. The code list in Table 1-1, Example code list: vehicle makes and models, above, may be represented as a CSV or Genericode document, as shown in Appendix D.2, Make–Model code list CSV file, below, and Appendix D.3, Make–Model code list Genericode file, below.

This specification also provides a framework for code lists that may be implemented using other formats. The syntax of code list bindings and code list use in instance documents may leverage formats other than CSV and Genericode. Future specifications may identify how other formats satisfy the code list framework defined by this document.

1.3. Identifiers for code lists

Consistent with [Genericode], this specification defines absolute URIs as identifiers for code lists. Each code list may have any number of identifiers, each a URI. Genericode identifies several kinds of URIs that identify a code list.

This specification also provides for the identification of columns within a code list. It defines column names as strings, whereas Genericode defines column IDs of type xs:ID. The use of strings to carry identifiers allows CSV and other non-Genericode representations for code lists.

The use of identifiers for code lists and columns is shown in the examples:

1.4. Mechanism for resolving code lists

This specification uses the mechanism defined by [XML Catalogs] to describe the resolution of code list identifier URIs into code list documents. Examples of this in use are shown in the catalog entry files in Appendix D.6, XML catalog for schema-time code list binding, below, and Appendix D.9, XML catalog for run-time code list binding, below. Each of these catalog files resolves the code list identifier http://example.org/code-list/vehicle-make-model to a locally available resource make-model.gc, a Genericode code list document.

1.5. Identifying a code list at run time

An XML document can connect its contents to code lists using attributes that appear in the instance. This is called a run-time binding, and connects the simple content of an element to a code value in a code list. The attributes that define this connection are in the code lists instance namespace. They are:

Figure 1-1, An XML instance with run-time code list binding, below, shows an example of run-time binding It uses the attribute cli:codeListURI to connect the value of element ext:VehicleMakeCode (DODG) to the make–model code list, and the attribute cli:codeListColumnName to connect the value to the make column of that code list. It also connects the value of ext:VehicleModelCode (R15) to the model column of the code list.

Figure 1-1: An XML instance with run-time code list binding
<nc:Vehicle
    xmlns:cli="http://reference.niem.gov/niem/specification/code-lists/4.0/code-lists-instance/"
    xmlns:ext="http://example.org/namespace/extension-run-time"
    xmlns:nc="http://release.niem.gov/niem/niem-core/4.0/">
  <ext:VehicleMakeCode
      cli:codeListURI="http://example.org/code-list/vehicle-make-model"
      cli:codeListColumnName="make"
    >DODG</ext:VehicleMakeCode>
  <ext:VehicleModelCode
      cli:codeListURI="http://example.org/code-list/vehicle-make-model"
      cli:codeListColumnName="model"
    >R15</ext:VehicleModelCode>
</nc:Vehicle>

Advantages of this strategy include:

1.6. Identifying a code list at schema time

This specification defines an annotation vocabulary, the code lists schema appinfo namespace, which allows connections between code lists and elements, attributes, and types that are defined in an XML Schema. This is managed with two annotation elements:

Figure 1-2, XML instance using schema-time code list binding, below, shows an instance that uses schema-time binding. The instance does not carry any information about code lists; it does not have a code list identifier, nor does it have a column name. The instance is simple.

Figure 1-2: XML instance using schema-time code list binding
<ext:Vehicle
  <ext:VehicleMakeCode>DODG</ext:VehicleMakeCode>
  <ext:VehicleModelCode>R15</ext:VehicleModelCode>
</ext:Vehicle>

The simple code list binding in Figure 1-3, XML schema defining a simple code list binding, below, connects the content of VehicleMakeCode to the code list's make column.

Figure 1-3: XML schema defining a simple code list binding
<xs:element name="VehicleMakeCode" type="niem-xs:token"
            substitutionGroup="nc:VehicleMakeAbstract">
  <xs:annotation>
    <xs:documentation>A code for a manufacturer of a vehicle.</xs:documentation>
    <xs:appinfo>
      <clsa:SimpleCodeListBinding
          codeListURI="http://example.org/code-list/vehicle-make-model"
          columnName="make"/>
    </xs:appinfo>
  </xs:annotation>
</xs:element>

The complex code list binding in Figure 1-4, XML schema defining a complex code list binding, below, connects nc:VehicleMake and nc:VehicleModel child elements of element Vehicle to the code list:

Figure 1-4: XML schema defining a complex code list binding
<xs:element name="Vehicle" type="nc:VehicleType"
            substitutionGroup="nc:Vehicle">
  <xs:annotation>
    <xs:appinfo>
      <clsa:ComplexCodeListBinding
          codeListURI="http://example.org/code-list/vehicle-make-model">
        <clsa:ElementCodeListBinding elementName="ext:VehicleMakeCode"
                                     columnName="make"/>
        <clsa:ElementCodeListBinding elementName="ext:VehicleModelCode"
                                     columnName="model"/>
      </clsa:ComplexCodeListBinding>
    </xs:appinfo>
  </xs:annotation>
</xs:element>

Advantages of this strategy include:

2. Terminology

This document relies on terminology defined by other specifications and standards, as well as terminology specific to this specification. This section introduces many terms, and directs the reader to the external source definition of a term when appropriate. The following sections reflect the different sources and topics of this terminology:

2.1. RFC 2119: Key words for use in RFCs to Indicate Requirement Levels

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

2.2. RFC 3986: Uniform Resource Identifier (URI): Generic Syntax

[RFC3986] defines uniform resource identifier (URI), which it describes as:

A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource.

The term absolute URI is as defined by [RFC3986] Section 4.3, Absolute URI, identifying a uniform resource identifier that matches the grammar production absolute-URI.

The term resource is defined by [RFC3986] Section 1.1, Overview of URIs, which states:

This specification does not limit the scope of what might be a resource; rather, the term resource is used in a general sense for whatever might be identified by a URI. Familiar examples include an electronic document, an image, a source of information with a consistent purpose (e.g., today’s weather report for Los Angeles), a service (e.g., an HTTP-to-SMS gateway), and a collection of other resources.

2.3. XML

The term XML document is defined by [XML] Section 2, Documents, which states:

A data object is an XML document if it is well-formed, as defined in this specification.

2.4. XML Namespaces

This document uses XML Namespaces as defined by [XMLNamespaces].

The following namespace prefixes are used consistently within this specification. These prefixes are not normative; this document issues no requirement that these prefixes be used in any conformant artifact. Although there is no requirement for a schema or XML document to use a particular namespace prefix, the meaning of the following namespace prefixes have fixed meaning in this document.

2.5. XML Information Set

This document refers to content of XML documents using terms from [XML Infoset]. Terminology adapted from [XML Infoset] includes:

2.6. XML Schema

This specification provides definitions and mechanisms that may be used within XML Schemas and individual XML Schema documents for validation of information exchanges. To define these mechanisms, terminology from the XML Schema specification must be clarified.

Terms adapted from [XMLSchema1] include:

The XML Schema defines properties of schema components, including:

The XML Schema specification defines additional properties of information set information items as part of the post-schema-validation infoset (PSVI). These properties include:

To facilitate code lists representing ranges of values as described in Section 7.5, Columns supporting ranges of values, below, the following terms are adapted from [XMLSchema2], Section 4.2, Fundamental Facets, Subsection 4.2.1, bounded:

See also Section 2.8, NIEM Naming and Design Rules, below, for the term XML Schema document set.

2.7. Conformance Targets Attribute Specification

[CTAS] defines several terms used normatively within this specification.

The term conformance target is defined by [CTAS] Section 3.1, Conformance Target Defined which states:

A conformance target is 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.

The term conformance target identifier is defined by [CTAS] Section 3.1, Conformance Target Defined, which states:

A conformance target identifier is an internationalized resource identifier that uniquely identifies a conformance target.

The term effective conformance target identifier is defined by [CTAS] Section 4, Semantics and Use, which states:

An effective conformance target identifier of a conformant document is an internationalized resource identifier reference that occurs in the document’s effective conformance targets attribute.

2.8. NIEM Naming and Design Rules

The term application information (of a schema component) is defined by [NIEM NDR] Section 10.9, Machine-readable annotations, describing the contents of xs:appinfo annotations on the element that defines a schema component.

The term XML Schema document set is defined by [NIEM NDR] Section 3.4, XML Schema terminology, which states:

An XML Schema document set is a set of schema documents that together define an XML Schema suitable for assessing the validity of an XML document.

2.9. Code Lists

To facilitate the use of code lists, this document must define some terms related to code lists and their use. [Genericode] is the source of some of this terminology, although in this specification much of this terminology refers to code lists in the abstract, rather than only as concrete Genericode documents.

[Definition: code list]

A code list is a set of distinct entries with a corresponding set of columns. A code list may be thought of as a table, with table rows as distinct entries, table columns as code list columns, and individual cells as code values.

[Definition: distinct entry]

A distinct entry is a single conceptual entity within a code list. It is composed of a set of code values, each corresponding to a column of the code list. It may be thought of as a row of a table, where each individual cell of a row corresponds to a column of the table.

[Definition: code value]

A code value is a single data value within a distinct entry in a code list. Each code value of a distinct entry corresponds to a column of the code list.

[Genericode] uses the term value to refer to a data item that corresponds to a column within a distinct entry. Value is a very common word, with broadly-understood meaning, and using it by itself, but with a very specialized meaning, would be misconstrued in many cases. For that reason, this document prefers the term code value when referring to a value of a distinct entry.

[Definition: column]

A column of a code list is metadata that describes a code value within each distinct entry of the code list. Each code value within the code list corresponds to one column of the code list.

[Definition: code list identifier]

A code list identifier is an absolute URI that identifies a code list.

This document defines two designators for a column of a code list, the column identifier and the column name.

[Definition: column identifier]

A column identifier is an absolute URI that identifies a column of a code list.

A column identifier identifies a column irrespective of the specific code list in which it occurs. [Genericode] defines CanonicalUri and CanonicalVersionUri that are column identifiers, which it provides for assigning universal semantics to code list columns.

[Definition: column name]

A column name is a character string value that identifies a column within the scope of a code list.

A column name is a text (character string) value that identifies a column, only within the scope of a specific code list. A column within a Genericode code list document has an XML ID that uniquely identifies it within the document.

Note that all of the above definitions are abstract. They do not get into the details of Genericode, (e.g., canonical URIs, version URIs, location URIs, ColumnRefs, ColumnSets, and KeyRefs). These terms and identifiers are generically defined here so that they may be applied to CSV and Genericode documents, or to other methods of expressing code lists, including other data file formats and registry-based services.

To summarize, a code list is a set of distinct entries with a corresponding set of columns. Each distinct entry contains a set of code values. Each code value corresponds to a distinct column in the code list. Each column identifies and describes the code values within the distinct entries of the code list. A code list identifier is a name for the code list as a whole, and a column name is a name of a single column within a code list.

Further, this document defines the terms code list document, CSV code list document, and Genericode code list document. These are conformance targets of this specification. A code list document is a file, document or other resource that carries one or more code lists. A CSV code list document is a code list document that uses comma-separated values format defined by [RFC4180]. A Genericode code list document is a code list document that uses syntax defined by [Genericode].

2.10. RFC 4180: Comma-separated values (CSV) files

This document uses the definition of CSV files as defined by [RFC4180]. The following terms take their definitions from the ABNF (Augmented Backus-Naur Form) grammar defined by Section 2, Definition of the CSV Format of that specification.

2.11. XML Catalogs

This document relies on [XML Catalogs] for the mechanisms for identifying and finding a code list from its code list identifier.

The term entity catalog is defined by [XML Catalogs], which states in [XML Catalogs] Section 3, An Entity Catalog:

The catalog is effectively an ordered list of (one or more) catalog entry files. It is up to the application to determine the ordered list of catalog entry files to be used as the logical catalog.

The resources (i.e., files) that are within the same local cache, ZIP file, or other contained location as an entity catalog are the local context of the entity catalog.

The term catalog entry file is defined by [XML Catalogs] Section 2, Terminology, which states:

A catalog may be physically contained in one or more catalog entry files. A catalog entry file is a document that contains a set of catalog entries.

The term resolve refers to the process of resolving URI references, as described by [XML Catalogs] Section 7.2.2, Resolution of URI references, which defines the process for resolving a URI reference to a URI for a corresponding resource, as identified by an entity catalog.

[Definition: locally-resolved resource]

A locally-resolved resource for a URI relative to an entity catalog is the resource yielded through the process of resolving the URI into a resource URI using the entity catalog, and then producing the corresponding resource from the local context of the entity catalog.

3. Conformance targets

This document defines multiple conformance targets. Each conformance target is defined normatively by this specification. Each conformance target has an associated abbreviation, which is used to identify to which conformance targets a rule applies.

Table 3-1: Codes representing conformance targets
CodeConformance target
CLDcode list document
GC-CLDGenericode code list document
CSV-CLDCSV code list document
XSDcode list-enabled schema document
INScode list-enabled instance document
VSETcode list validation set
3.1. Code list document
[Definition: code list document]

A code list document is a file or resource that contains one or more code lists. It is a conformance target of this specification. A code list document MUST conform to all rules of this specification that apply to this conformance target. An XML document with an effective conformance target identifier of http://reference.niem.gov/niem/specification/code-lists/4.0/#CodeListDocument MUST be a code list document.

The specification for an implementation of a code list document by a class of resource (such as with Genericode or CSV) needs to specify the following characteristics:

  1. Candidate code list identifiers. Some code list documents specify what URIs may be used to reference the code list. Some resources may feature multiple code lists within a single resource, and the specification must describe how a specific code list is identified within the resource.
  2. The mapping between features of the resource and distinct entries.
  3. The mapping between features of the resource and code values.
  4. The mapping between features of the resource and column names.
  5. The method of identifying a column as being a well-known column (described in Section 7, Well-known columns and references, below).
  6. The method of identifying well-known column reference #code (described in Section 7, Well-known columns and references, below).
  7. The method of identifying the data type of a code value, which can be a data type defined by an XML Schema, or empty.

These characteristics are described for Genericode files in Section 6, Genericode code lists, below. They are described for CSV files in Section 5, Comma-separated values (CSV) code lists, below.

3.2. Genericode code list document
[Definition: Genericode code list document]

A Genericode code list document is a code list document. It is a conformance target of this specification. A Genericode code list document MUST conform to all rules of this specification that apply to this conformance target. The conformance target identifier for this conformance target is http://reference.niem.gov/niem/specification/code-lists/4.0/#GenericodeCodeListDocument.

Section 6, Genericode code lists, below, provides rules for Genericode code list documents.

3.3. CSV code list document
[Definition: CSV code list document]

A CSV code list document is a code list document. It is a conformance target of this specification. A CSV code list document MUST conform to all rules of this specification that apply to this conformance target. The conformance target identifier for this conformance target is http://reference.niem.gov/niem/specification/code-lists/4.0/#CSVCodeListDocument.

3.4. Code list-enabled schema document
[Definition: code list-enabled schema document]

A code list-enabled schema document is an XML Schema document that supports the use of code list documents for validation and meaning. It is a conformance target of this specification. A code list-enabled schema document MUST conform to all rules of this specification that apply to this conformance target. The conformance target identifier for this conformance target is http://reference.niem.gov/niem/specification/code-lists/4.0/#SchemaDocument.

Rule 3-1. Code list-enabled schema document has conformance target
[Rule 3-1] (XSD) (Constraint)

A code list-enabled schema document MUST have an effective conformance target identifier of http://reference.niem.gov/niem/specification/code-lists/4.0/#SchemaDocument

Rule 3-2. Document with conformance target is a code list-enabled schema document
[Rule 3-2] (VSET) (Constraint)

A resource with an effective conformance target identifier of http://reference.niem.gov/niem/specification/code-lists/4.0/#SchemaDocument MUST be a code list-enabled schema document.

3.5. Code list-enabled instance document
[Definition: code list-enabled instance document]

A code list-enabled instance document is an XML document that leverages this specification to connect data values with code lists. A code list-enabled instance document MUST conform to all rules of this specification that apply to this conformance target. An XML document with an effective conformance target identifier of http://reference.niem.gov/niem/specification/code-lists/4.0/#InstanceDocument MUST be a code list-enabled instance document.

Although this specification defines a conformance target identifier for a code list-enabled instance document, it does not require the conformance target identifier to appear within an instance document.

3.6. Code list validation set

A code list validation set is an abstract concept that brings together the necessary components to define validity of XML documents with respect to code lists, and to identify correspondences between XML data and code list distinct entries. There may be multiple code list validation sets in use at any point of a validation or analysis process; it is a concept meant to facilitate working with code lists.

[Definition: code list validation set]

A code list validation set is an abstraction that contains one or more of:

4. Binding XML content to code lists

XML content in a message may be identified as corresponding to content of a code list. This correspondence is referred to as a code list binding, connecting the XML content to the code list. This specification provides methods for binding XML content to code lists in two ways:

4.1. Multiple bindings

Code list bindings should be seen as additional semantics and validation for parts of a message. A particular piece of XML content may be bound to multiple code lists at the same time.

For example, a message may contain elements for vehicle make and vehicle model. These values may have multiple bindings, including:

4.2. Binding by URI

Content is bound to a code list using a URI as the identifier of the code list. This identifier may be any of the following:

4.3. Definition of code list binding

A code list binding brings together a set of columns from a code list with a corresponding set of data from an XML document. The binding can provide meaning for data in an XML document, and can provide additional validity constraints on an XML document. The code list binding defined here is an abstract concept, bringing together a code list (via a code list identifier), column names, and data values (such as from an information exchange package or other XML document). This abstract definition is leveraged in Section 4.4, Run-time binding, below, and Section 4.5, Schema-time binding, below.

A code list binding may be applied to a single value or to multiple values. The abstract definition of code list binding is applied to the concrete mechanisms for binding data values to code lists, through run-time binding or schema-time binding.

[Definition: code list binding]

A code list binding is an assigned correspondence between a set of data values, such as data within an XML document, and a set of columns within a code list, identified via a code list identifier and a set of column names.

A code list binding has the following properties:

  • a code list identifier
  • a set of column/value pairs, each having:

    • a column reference: either a column name or a well-known column reference, and
    • a data value
  • A boolean value, constraining.
4.4. Run-time binding

This document provides an XML Schema document for run-time binding of XML content to code lists. This schema is provided in Appendix B, XML Schema document for the code lists instance namespace, below.

4.4.1. Syntax for run-time code list binding
Rule 4-1. Content in the cli namespace conforms to schema
[Rule 4-1] (INS) (Constraint)

Any XML content in the namespace http://reference.niem.gov/niem/specification/code-lists/4.0/code-lists-instance/ MUST be schema-valid to the XML Schema definitions contained in the schema document in Appendix B, XML Schema document for the code lists instance namespace, below.

Rule 4-2. Code list URI is an absolute URI
[Rule 4-2] (INS) (Constraint)

The normalized value of an attribute cli:codeListURI MUST be an absolute URI.

Rule 4-3. Column identifier accompanied by code list identifier
[Rule 4-3] (INS) (Constraint)

An element having an attribute cli:codeListColumnName MUST have an attribute cli:codeListURI.

Rule 4-4. Constraining indicator accompanied by code list identifier
[Rule 4-4] (INS) (Constraint)

An element having an attribute cli:codeListConstrainingIndicator MUST have an attribute cli:codeListURI.

4.4.2. Run-time effective code list binding
Rule 4-5. Effective run-time binding.
[Rule 4-5] (INS) (Interpretation)

An element $element with an attribute $attribute cli:codeListURI denotes a code list binding of:

  • a code list identifier of the normalized value of the attribute cli:codeListURI
  • a single column/value pair, having:

    • a column reference of: if $element has attribute cli:codeListColumnName, then the normalized value of that attribute, else #code.
    • a data value that is the normalized value of $element.
  • A value for constraining that is: if $element has attribute cli:codeListConstrainingIndicator, then its value, otherwise true.
4.5. Schema-time binding

This document provides XML elements for annotating XML Schema document components, to indicate, at schema time, a code list binding between a code list and one or more data values of the code list.

4.5.1. Syntax for schema-time code list binding
Rule 4-6. Content in the clsa namespace conforms to schema
[Rule 4-6] (XSD) (Constraint)

Any XML content in the namespace http://reference.niem.gov/niem/specification/code-lists/4.0/code-lists-schema-appinfo/ MUST be schema-valid to the XML Schema definitions contained in the schema document in Appendix C, XML Schema document for the code list schema appinfo namespace, below.

Rule 4-7. Elements are xs:appinfo annotations
[Rule 4-7] (XSD) (Constraint)

An element clsa:SimpleCodeListBinding or clsa:ComplexCodeListBinding MUST have [parent] element xs:appinfo.

Rule 4-8. Code list URI is absolute URI
[Rule 4-8] (XSD) (Constraint)

An attribute codeListURI that has [owner element] of clsa:SimpleCodeListBinding or clsa:ComplexCodeListBinding MUST have a normalized value that is an absolute URI.

Rule 4-9. Simple code list binding to schema components
[Rule 4-9] (XSD) (Constraint)

Element clsa:SimpleCodeListBinding MUST be application information on one of:

Rule 4-10. Complex code list binding to schema components
[Rule 4-10] (XSD) (Constraint)

Element clsa:ComplexCodeListBinding MUST be application information on one of:

4.5.2. Simple binding of schema components
Rule 4-11. Attribute declaration effective simple binding
[Rule 4-11] (VSET) (Interpretation)

An element xs:attribute defining an attribute declaration $attribute-declaration with application information of an element $binding-element clsa:SimpleCodeListBinding entails:

  • Each attribute $attribute in the instance of the code list validation set with [attribute declaration] equal to $attribute-declaration entails a code list binding with:

    • A code list identifier that is the normalized value of the attribute codeListURI of $binding-element.
    • A column/value pair with:

      • A column reference of: if $binding-element has attribute columnName, then the normalized value of that attribute, else #code.
      • A data value that is the normalized value of $attribute
    • A value for constraining that is: if $binding-element has attribute constrainingIndicator, then its value, otherwise true.
Rule 4-12. Element declaration effective simple binding
[Rule 4-12] (VSET) (Interpretation)

An element xs:element defining an element declaration $element-declaration with application information of an element $binding-element clsa:SimpleCodeListBinding entails:

Rule 4-13. Type definition effective simple binding
[Rule 4-13] (VSET) (Interpretation)

An element xs:simpleType or xs:complexType defining a type definition $type-definition with application information of an element $binding-element clsa:SimpleCodeListBinding entails:

4.5.3. Complex binding of schema components
Rule 4-14. Element declaration effective complex binding
[Rule 4-14] (VSET) (Interpretation)

An element xs:element defining an element declaration $element-declaration with application information of an element $binding-element clsa:ComplexCodeListBinding entails:

  • Each element $element in the instance of the code list validation set with [element declaration] that is in the substitution group of $element-declaration entails a code list binding with:

    • A code list identifier that is the normalized value of the attribute codeListURI of $binding-element.
    • A set of column/value pairs, containing: For each clsa:ElementCodeListBinding child $element-binding of $binding-element:

      • A column/value pair with:

        • A column reference of: if $element-binding has attribute columnName, then the normalized value of that attribute, else #code.
        • A data value that is: if it exists, the first element child of $element that is in the substitution group of an element declaration with a name that is equal to the value of attribute elementName of $element-binding, otherwise empty.
    • A value for constraining that is: if $binding-element has attribute constrainingIndicator, then its value, otherwise true.
Rule 4-15. Complex type definition effective complex binding
[Rule 4-15] (VSET) (Interpretation)

An element xs:complexType defining a complex type definition $type-definition with application information of an element $binding-element clsa:ComplexCodeListBinding entails:

  • Each element $element in the instance of the code list validation set with [type definition] derived from $type-definition entails a code list binding with:

    • A code list identifier that is the normalized value of the attribute codeListURI of $binding-element.
    • A list of column/value pairs, containing: For each clsa:ElementCodeListBinding child $element-binding of $binding-element:

      • A column/value pair with:

        • A column reference of: if $element-binding has attribute columnName, then the normalized value of that attribute, else #code.
        • A data value that is: if it exists, the first element child of $element that is in the substitution group of an element declaration with a name that is equal to the value of attribute elementName of $element-binding, otherwise empty.
    • A value for constraining that is: if $binding-element has attribute constrainingIndicator, then its value, otherwise true.
4.6. Matches for code list bindings

A code list binding defined against a code list document may be matched to zero or more distinct entries within the code list. The process of finding matches for a code list binding $binding against a code list validation set is defined by the following rule.

Rule 4-16. Matches and validity for a code list binding
[Rule 4-16] (VSET) (Interpretation)

A code list binding matching against against a code list validation set yields a set of distinct entries and a validity value (valid or invalid).

The matches for a code list binding $binding against a code list validation set MUST be:

  • The code list identifier $identifier is provided by the $binding.
  • Using the entity catalog defined for the code list validation set, resolve code list identifier $identifier to a locally-resolved resource $resource.
  • If $resource is not a code list document, or if no resource is identified for $identifier, then this specification does not define any matches for $binding. The binding is evaluated to be invalid. In this case, the code list identified by $identifier SHOULD be handled by means other than this specification.
  • If $resource is a code list document, then the set of matches for $binding is the list of distinct entries in the code list for which every column referenced by $binding has the corresponding value.

    • A column/value pair in $binding with a column reference of #code matches as specified for the appropriate class of code list document for that column name.
    • A column/value pair in $binding with a column reference of #range matches:

      • If $resource does not contain a column corresponding to the well-known columns minimum-inclusive, minimum-exclusive, maximum-inclusive, or maximum-exclusive, then the binding has no matches.
      • Otherwise, yield all distinct entries for which all of the following are true, given that the value of the column/value pair is $value:

        • Either there is no code value for column minimum-inclusive, or the code value of that column is less than or equal to $value.
        • Either there is no code value for column minimum-exclusive, or the code value of that column is less than $value.
        • Either there is no code value for column maximum-inclusive, or the code value of that column is greater than or equal to $value.
        • Either there is no code value for column maximum-exclusive, or the code value of that column is greater than $value.
  • If the binding has no matches, then:

    • If the binding is constraining, then it is invalid.
    • If the binding is not constraining, then it is valid.
  • If the binding has one or more matches, then it is valid.

The above rule specifies that code list identifiers are to be resolved to locally-resolved resources, which are in the local context of the entity catalog. This specification does not specify that code list identifiers should be resolved by network fetches of code list resources. Code list identifiers are meant to be treated as identifiers, as names, and not as network locations of resources.

A code list binding that is used to connect a value to a service or other code list methodology that does not use code list documents will result in invalid matches. This is as designed; matches for services or other methodologies should be determined by a method other than this rule.

Rule 4-17. Value comparisons based on types

Rule 4-16, Matches and validity for a code list binding (VSET), above, requires values from an XML document to be compared to values from code lists. Whether values match, and how they compare, is dependent on what kind of data those values are. For example, text values and string values are compared using different methods. This rule establishes that typing of comparisons is based on the types of the values.

[XPathFunctions] Section 17, Casting provides a set of rules for type casting among XML Schema primitive types.

[Rule 4-17] (VSET) (Interpretation)

Comparisons between a value $instance-value of a column/value pair and a code value $code-value MUST be conducted as follows:

  1. $instance-value has a data type, $instance-data-type, provided by its XML Schema definition.
  2. $code-value has a data type, $code-data-type, as provided by its code list document as specified for its class of code list document. That data type is either a data type defined by the XML Schema definition language, or is empty.
  3. A data type, $comparison-data-type, is calculated as:

    • If $code-data-type is empty, then $instance-date-type.
    • If it exists, the lowest common ancestor of the two data types.
    • Otherwise, xs:string.
  4. $instance-value and $code-value are cast to $comparison-data-type, in accordance with [XPathFunctions] Section 17, Casting.
  5. Equality comparisons are conducted as appropriate for $comparison-data-type.
  6. Inequality comparisons (e.g., less than, greater than) for ranges are conducted as appropriate for lowest atomic base type of $comparison-data-type.
Rule 4-18. Code list identified by candidate code list identifiers

Each class of code list document specifies how its instances define code list identifiers that may refer to a code list. This rule ensures that code lists are referred to via the correct code list identifier, when it is defined.

[Rule 4-18] (VSET) (Constraint)

When a code list document defines candidate code list identifiers, a code list identifier against which a code list document resource is resolved MUST be a candidate code list identifier for that code list document.

5. Comma-separated values (CSV) code lists

This document provides for the use of a CSV file as an implementation of a code list document. This section lays out the rules for using CSV files as code list documents. The definitions of CSV structural terms are provided by [RFC4180], as noted in Section 2.10, RFC 4180: Comma-separated values (CSV) files, above.

Rule 5-1. CSV code list document is a CSV file
[Rule 5-1] (CSV-CLD) (Constraint)

A CSV code list document MUST be a CSV file.

Rule 5-2. CSV code list document has header
[Rule 5-2] (CSV-CLD) (Constraint)

A CSV code list document MUST have a CSV header.

Rule 5-3. CSV column name is not empty
[Rule 5-3] (CSV-CLD) (Constraint)

A CSV column name of a CSV code list document MUST not be empty.

Rule 5-4. CSV file as a code list document
[Rule 5-4] (CSV-CLD) (Interpretation)

A CSV file may act as a CSV code list document in the following manner:

  1. Code list identifiers: The CSV file does not specify its code list identifiers. Each CSV file contains a single code list. The CSV file MAY be resolved to any code list identifier.
  2. Distinct entries: Each CSV record of the CSV file constitutes a distinct entry.
  3. Code values: Each CSV field corresponds to a code value.
  4. Column names: The column name of a code value is the CSV column name corresponding by position within the CSV header to the position of the CSV field within its CSV record
  5. A column in a CSV file is a well-known column when its CSV column name is the same as the column name of a well-known column.
  6. A reference to column #code is matched, in order, to:

  7. A code value in a CSV file has no type; its data type is empty.
6. Genericode code lists

This document incorporates a Genericode document as an implementation of a code list document. This section lays out rules for Genericode documents and their use as code list documents.

Rule 6-1. Genericode code list document defined by Genericode
[Rule 6-1] (GC-CLD) (Constraint)

A Genericode code list document MUST be a Genericode code list document as defined by [Genericode] Section 3.2, Genericode Document Types, which states:

A Genericode code list document has the root element <gc:CodeList>. It contains metadata describing the code list as a whole, as well as explicit code list data — codes and associated values.

Rule 6-2. Document with conformance target is Genericode code list document
[Rule 6-2] (VSET) (Constraint)

A resource with an effective conformance target identifier of http://reference.niem.gov/niem/specification/code-lists/4.0/#GenericodeCodeListDocument MUST be a Genericode code list document.

Rule 6-3. Genericode code list document is schema-valid
[Rule 6-3] (GC-CLD) (Constraint)

A Genericode code list document MUST be schema-valid against the schema document for the Genericode namespace as provided at http://docs.oasis-open.org/codelist/ns/genericode/1.0/.

Rule 6-4. XML Schema alternate datatypes are treated the same as built in datatypes

[XMLSchema2] defines an alternate namespace name as an alias that may be used to refer to simple datatypes it defines. [XMLSchema2] Section 3.1, Namespace considerations states:

To facilitate usage in specifications other than the XML Schema definition language, such as those that do not want to know anything about aspects of the XML Schema definition language other than the datatypes, each ·built-in· datatype is also defined in the namespace whose URI is:

  • http://www.w3.org/2001/XMLSchema-datatypes

This applies to both ·built-in· ·primitive· and ·built-in· ·derived· datatypes.

[Genericode] uses this alternate namespace name as a default for the datatype library in Genericode documents, referring to it as the URI for W3C XML Schema datatypes. As this separate namespace is not expressing a semantic distinction, and in order to keep Genericode documents simple, this document specifies that the alternate namespace name is to be treated as if it was the namespace name for the XML Schema definition language.

[Rule 6-4] (GC-CLD) (Interpretation)

A datatype with a namespace name of http://www.w3.org/2001/XMLSchema-datatypes MUST be evaluated as if it had a namespace name of http://www.w3.org/2001/XMLSchema.

Rule 6-5. Genericode file as a code list document
[Rule 6-5] (GC-CLD) (Interpretation)

A Genericode code list document may act as a code list document in the following manner:

  1. Code list identifier: Candidate code list identifiers for the document are the values for CanonicalUri, CanonicalVersionUri, and LocationUri defined by the Genericode document for the code list.
  2. Distinct entries: Each row of the Genericode code list document constitutes a distinct entry.
  3. Code values: Each Value element of the Genericode code list document corresponds to a code value.
  4. Column names: The columns are as defined by Genericode; the column name of a column is the value of attribute Id of that column.
  5. A column in a Genericode code list document is a well-known column when its value for CanonicalUri or CanonicalVersionUri corresponds to the code list identifier specified for that well-known column.
  6. A reference to column #code is matched, in order, to:

    • a column corresponding to well-known column code,
    • a column with column name code,
    • the column in the first single-column key for the code list, or
    • the first column in the code list.
  7. A code value in a Genericode file has a type as specified by the data definition of its column. If the Type attribute references an element declaration, then the type is the type of that element. If a Parameter, which introduces gc:DatatypeFacet, is used, then the type is treated as an anonymous type derived from the type of the column. A value for which no data type is specified has an empty data type.
7. Well-known columns and references

This specification defines column identifiers and column names for several columns that have well-understood semantics. These identifiers and names may be used to define columns in code list documents that implement these semantics. These values may be used different ways in different contexts:

In addition to well-known columns, this specification defines well-known column references. A well-known column reference is used in code list bindings. The well-known column references defined by this specification are:

7.1. Column: code

Column name: code

Column identifier: http://reference.niem.gov/niem/specification/code-lists/4.0/column/code

Description: A code column carries a value that stands for some other value or meaning, or acts as an enumeration. A code value may be a single-column key within its code list, to uniquely identify some distinct entry.

7.2. Column: definition

Column name: definition

Column identifier: http://reference.niem.gov/niem/specification/code-lists/4.0/column/definition

Description: A definition column carries a human-readable meaning of a distinct entry. This is analogous to the data definition of an enumerated code in a simple type in a NIEM schema.

7.3. Column: subclass-of

Column name: subclass-of

Column identifier: http://reference.niem.gov/niem/specification/code-lists/4.0/column/subclass-of

Description: A subclass-of column indicates that a given distinct entry is a subclass of some other distinct entry. It is a key reference within its code list, referring to a distinct entry having the indicated value for its default code column.

7.4. Column: uri

Column name: uri

Column identifier: http://reference.niem.gov/niem/specification/code-lists/4.0/column/uri

Description: A uri column provides a uniform resource identifier for a distinct entry.

7.5. Columns supporting ranges of values

This specification establishes a set of columns that support code tables that describe ranges of values. This enables code lists to be used that map between sets of values. One use for this is to enable translation between continuous numeric values and discrete enumerated values. Another use is to support fixed-point integer values used to represent more meaningful numeric values. For example, fixed-length bit field values can be mapped to elevation in meters.

In Table 7-1, Example code list: directions, below, a direction value in degrees is mapped to enumerated values for the cardinal and ordinal directions. This code list establishes the ranges using the columns minimum-inclusive and maximum-exclusive. Each distinct entry contains a direction column, identifying to what direction the range is mapped. A Genericode code list document expressing this code list would define columns with CanonicalUri matching the column identifiers for minimum-inclusive and maximum-exclusive. A CSV code list document would define columns named minimum-inclusive and maximum-exclusive.

Table 7-1: Example code list: directions
minimum-inclusivemaximum-exclusivedirection
022.5north
22.567.5northeast
67.5112.5east
112.5157.5southeast
157.5202.5south
202.5247.5southwest
247.5292.5west
292.5337.5northwest
337.5360north

A code list binding that refers to range columns uses the column name #range. For example, Figure 7-1, Instance referencing range columns, below, uses a run-time binding. It identifies the code list with attribute cli:codeListURI. It refers to range columns with attribute cli:codeListColumnName set to #range.

Figure 7-1: Instance referencing range columns
<m:Position
   xmlns:cli="http://reference.niem.gov/niem/specification/code-lists/4.0/code-lists-instance/"
   xmlns:ext="http://example.org/code-lists/example/directions/extension"
   xmlns:m="http://release.niem.gov/niem/domains/maritime/4.0/"
   xmlns:nc="http://release.niem.gov/niem/niem-core/4.0/">
  <m:PositionHeadingMeasure>
    <ext:DegreeAngleValue
       cli:codeListURI="http://example.org/code-lists/example/directions/code-list/1"
       cli:codeListColumnName="#range">122.31</ext:DegreeAngleValue>
    <ext:AngleUnitText>deg</ext:AngleUnitText>
  </m:PositionHeadingMeasure>
</m:Position>

Matching into Table 7-1, Example code list: directions, above, would yield the distinct entry for southeast, since it is the sole entry with a minimum-inclusive value (112.5) that is less than or equal to 122.31, and a maximum-exclusive value (157.5) that is greater than 122.31.

7.5.1. Column: minimum-inclusive

Column name: minimum-inclusive

Column identifier: http://reference.niem.gov/niem/specification/code-lists/4.0/column/minimum-inclusive

Description: A value that is an inclusive lower bound of a range.

7.5.2. Column: minimum-exclusive

Column name: minimum-exclusive

Column identifier: http://reference.niem.gov/niem/specification/code-lists/4.0/column/minimum-exclusive

Description: A value that is an exclusive lower bound of a range.

7.5.3. Column: maximum-inclusive

Column name: maximum-inclusive

Column identifier: http://reference.niem.gov/niem/specification/code-lists/4.0/column/maximum-inclusive

Description: A value that is an inclusive upper bound of a range.

7.5.4. Column: maximum-exclusive

Column name: maximum-exclusive

Column identifier: http://reference.niem.gov/niem/specification/code-lists/4.0/column/maximum-exclusive

Description: A value that is an exclusive upper bound of a range.

7.6. Code list example using well-known columns

The following examples show well-known columns being reused in a code list. A single code list is presented as an abstract table, corresponding CSV, and portions of corresponding Genericode. First, Table 7-2, Use of columns in a code list, below, is a tabular representation.

Table 7-2: Use of columns in a code list
codedefinitionuri
application/jsonjsonhttps://www.iana.org/assignments/media-types/application/json
application/msworddochttps://www.iana.org/assignments/media-types/application/msword
application/pdfpdfhttps://www.iana.org/assignments/media-types/application/pdf

In this table, we see the well-known columns code, definition, and uri being used. The next three rows represent the distinct entries of the code list, with a code value for each column.

Figure 7-2, Definition of columns in Genericode, below, shows a CSV file corresponding to the abstract table. In this version, the columns are identifiable as well-known columns because each CSV column name is a column name of a well-known column defined above.

Figure 7-2: Definition of columns in Genericode
code,definition,uri
application/json,json,https://www.iana.org/assignments/media-types/application/json
application/msword,doc,https://www.iana.org/assignments/media-types/application/msword
application/pdf,pdf,https://www.iana.org/assignments/media-types/application/pdf

For the above code list, Genericode in Figure 7-3, Definition of columns in Genericode, below, defines columns that reuse the well-known columns. Each column is identifiable as a well-known column because its CanonicalUri value is a column identifier of a well-known column.

Figure 7-3: Definition of columns in Genericode
<Column Id="code" Use="required">
  <ShortName>code</ShortName>
  <CanonicalUri>http://reference.niem.gov/niem/specification/code-lists/4.0/column/code</CanonicalUri>
  <Data Type="normalizedString" Lang="en"/>
</Column>
<Column Id="definition" Use="optional">
  <ShortName>definition</ShortName>
  <CanonicalUri>http://reference.niem.gov/niem/specification/code-lists/4.0/column/definition</CanonicalUri>
  <Data Type="normalizedString" Lang="en"/>
</Column>
<Column Id="uri" Use="optional">
  <ShortName>uri</ShortName>
  <CanonicalUri>http://reference.niem.gov/niem/specification/code-lists/4.0/column/uri</CanonicalUri>
  <Data Type="anyURI" Lang="en"/>
</Column>

Figure 7-4, Distinct entries in Genericode, below, contains distinct entries for the code lists, in the form of Genericode rows. These rows contain the same data as the other code list representations above.

Figure 7-4: Distinct entries in Genericode
<Row>
  <Value ColumnRef="code">
    <SimpleValue>application/json</SimpleValue>
  </Value>
  <Value ColumnRef="definition">
    <SimpleValue>json</SimpleValue>
  </Value>
  <Value ColumnRef="uri">
    <SimpleValue>https://www.iana.org/assignments/media-types/application/json</SimpleValue>
  </Value>
</Row>
<Row>
  <Value ColumnRef="code">
    <SimpleValue>application/msword</SimpleValue>
  </Value>
  <Value ColumnRef="definition">
    <SimpleValue>doc</SimpleValue>
  </Value>
  <Value ColumnRef="uri">
    <SimpleValue>https://www.iana.org/assignments/media-types/application/msword</SimpleValue>
  </Value>
</Row>
<Row>
  <Value ColumnRef="code">
    <SimpleValue>application/pdf</SimpleValue>
  </Value>
  <Value ColumnRef="definition">
    <SimpleValue>pdf</SimpleValue>
  </Value>
  <Value ColumnRef="uri">
    <SimpleValue>https://www.iana.org/assignments/media-types/application/pdf</SimpleValue>
  </Value>
</Row>
Appendix A. References

[CTAS]: Roberts, Webb. NIEM Conformance Targets Attribute Specification, Version 3.0. NIEM Technical Architecture Committee, July 31, 2014. http://reference.niem.gov/niem/specification/conformance-targets-attribute/3.0/NIEM-CTAS-3.0-2014-07-31.html.

[Genericode]: Anthony B. Coates, ed. Code List Representation (Genericode) Version 1.0, Committee Specification. OASIS, December 28, 2007. http://docs.oasis-open.org/codelist/cs-genericode-1.0/doc/oasis-code-list-representation-genericode.html.

[NIEM NDR]: Roberts, Webb. National Information Exchange Model Naming and Design Rules, Version 4.0. NIEM Technical Architecture Committee, November 7, 2017. http://reference.niem.gov/niem/specification/naming-and-design-rules/4.0/niem-ndr-4.0.html.

[RFC2119]: Bradner, S. (1997, March). Key words for use in RFCs to Indicate Requirement Levels. Internet Engineering Task Force. Retrieved from http://www.ietf.org/rfc/rfc2119.txt

[RFC3986]: Berners-Lee, T., Fielding, R., and L. Masinter, Uniform Resource Identifier (URI): Generic Syntax, STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, http://www.rfc-editor.org/info/rfc3986.

[RFC4180]: Shafranovich, Y. Common Format and MIME Type for Comma-Separated Values (CSV) Files, RFC 4180. IETF Network Working Group, October 2005. http://www.ietf.org/rfc/rfc4180.txt.

[XPathFunctions]: Malhotra, Ashok, Jim Melton, Norman Walsh, and Michael Kay. XQuery 1.0 and XPath 2.0 Functions and Operators (Second Edition). W3C, December 14, 2010. https://www.w3.org/TR/xpath-functions/.

[XML]: Bray, T., Paoli, J., Sperberg-McQueen, C. M., Maler, E., & Yergeau, F. (2008, November 26). Extensible Markup Language (XML) 1.0 (Fifth Edition). The World Wide Web Consortium (W3C). Retrieved from http://www.w3.org/TR/2008/REC-xml-20081126/

[XML Catalogs]: Walsh, Norman. XML Catalogs—OASIS Standard V1.1, 7 October 2005. OASIS Open, Inc., October 7, 2005. https://www.oasis-open.org/committees/download.php/14809/std-entity-xml-catalogs-1.1.html.

[XML Infoset]: Cowan, John, and Richard Tobin. XML Information Set (Second Edition), 4 February 2004. http://www.w3.org/TR/2004/REC-xml-infoset-20040204/.

[XMLNamespaces]: Bray, T., Hollander, D., Layman, A., Tobin, R., & Thompson, H. S. (2009, December 8). Namespaces in XML 1.0 (Third Edition). W3C. Retrieved from http://www.w3.org/TR/2009/REC-xml-names-20091208/

[XMLSchema1]: Thompson, H. S., Beech, D., Maloney, M., & Mendelsohn, N. (2004, October 28). XML Schema Part 1: Structures Second Edition. Retrieved from http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/.

[XMLSchema2]: Biron, Paul V., and Ashok Malhotra. XML Schema Part 2: Datatypes Second Edition, October 28, 2004. http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/.

Appendix B. XML Schema document for the code lists instance namespace

The following XML Schema document defines the code lists instance namespace, a namespace for binding the content of XML documents to code lists at run time. This vocabulary may be incorporated into exchange specifications, and is used in exchanged XML documents to express code list bindings at run time. This schema document conforms to NIEM 3 and NIEM 4, and may be integrated into either NIEM 3 or NIEM 4-conformant schema sets.

<?xml version="1.0" encoding="US-ASCII"?>
<xs:schema
    ct:conformanceTargets="http://reference.niem.gov/niem/specification/naming-and-design-rules/4.0/#ReferenceSchemaDocument http://reference.niem.gov/niem/specification/naming-and-design-rules/3.0/#ReferenceSchemaDocument"
    targetNamespace="http://reference.niem.gov/niem/specification/code-lists/4.0/code-lists-instance/"
    version="4.0"
    xmlns:ct="http://release.niem.gov/niem/conformanceTargets/3.0/"
    xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:annotation>
    <xs:documentation>Definitions for the use of the NIEM Code Lists Specification, version 4.0, in XML message instances.</xs:documentation>
  </xs:annotation>

  <xs:attribute name="codeListURI" type="xs:anyURI">
    <xs:annotation>
      <xs:documentation>A universal identifier for a code list.</xs:documentation>
    </xs:annotation>
  </xs:attribute>

  <xs:attribute name="codeListColumnName" type="xs:string">
    <xs:annotation>
      <xs:documentation>A local name for a code list column within a code list.</xs:documentation>
    </xs:annotation>
  </xs:attribute>

  <xs:attribute name="codeListConstrainingIndicator" type="xs:boolean">
    <xs:annotation>
      <xs:documentation>True when a code list binding constrains the validity of a code list value, false otherwise.</xs:documentation>
    </xs:annotation>
  </xs:attribute>

</xs:schema>
Appendix C. XML Schema document for the code list schema appinfo namespace

The following XML Schema document defines the code lists schema appinfo namespace, a namespace for annotating XML Schema component definitions. These annotations connect XML components to code lists at schema development time.

<?xml version="1.0" encoding="US-ASCII"?>
<xs:schema 
   targetNamespace="http://reference.niem.gov/niem/specification/code-lists/4.0/code-lists-schema-appinfo/"
   version="4.0"
   xmlns:clsa="http://reference.niem.gov/niem/specification/code-lists/4.0/code-lists-schema-appinfo/"
   xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:annotation>
    <xs:documentation>This schema provides annotations for connecting content defined within an XML Schema document to the content of code lists.</xs:documentation>
  </xs:annotation>

  <xs:element name="SimpleCodeListBinding">
    <xs:annotation>
      <xs:documentation>An element for connecting simple content defined by an XML Schema component to a a column of a code list.</xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:attribute name="codeListURI" type="xs:anyURI" use="required">
        <xs:annotation>
          <xs:documentation>A universal identifier for a code list.</xs:documentation>
        </xs:annotation>
      </xs:attribute>
      <xs:attribute name="columnName" type="xs:string" use="optional">
        <xs:annotation>
          <xs:documentation>A local name for a code list column within a code list.</xs:documentation>
        </xs:annotation>
      </xs:attribute>
      <xs:attribute name="constrainingIndicator" type="xs:boolean" use="optional">
        <xs:annotation>
          <xs:documentation>True when a code list binding constrains the validity of a code list value, false otherwise.</xs:documentation>
        </xs:annotation>
      </xs:attribute>
    </xs:complexType>
  </xs:element>

  <xs:element name="ComplexCodeListBinding">
    <xs:annotation>
      <xs:documentation>An element for connecting complex content defined by an XML Schema component to a set of columns of a code list.</xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:sequence>
        <xs:element name="ElementCodeListBinding" form="qualified" maxOccurs="unbounded">
          <xs:complexType>
            <xs:attribute name="elementName" type="xs:QName" use="required">
              <xs:annotation>
                <xs:documentation>A qualified name of an XML element.</xs:documentation>
              </xs:annotation>
            </xs:attribute>
            <xs:attribute name="columnName" type="xs:string" use="optional">
              <xs:annotation>
                <xs:documentation>A local name for a code list column within a code list.</xs:documentation>
              </xs:annotation>
            </xs:attribute>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
      <xs:attribute name="codeListURI" type="xs:anyURI" use="required">
        <xs:annotation>
          <xs:documentation>A universal identifier for a code list.</xs:documentation>
        </xs:annotation>
      </xs:attribute>
      <xs:attribute name="constrainingIndicator" type="xs:boolean" use="optional">
        <xs:annotation>
          <xs:documentation>True when a code list binding constrains the validity of a code list value, false otherwise.</xs:documentation>
        </xs:annotation>
      </xs:attribute>
    </xs:complexType>
  </xs:element>

</xs:schema>
Appendix D. Example documents: Make–Model example

This section contains a single code list, with instances and supporting schemas for both run-time binding and schema-time binding:

A code list provides makes and models of vehicles.

The code list is used in XML exchanges. There are two methods provided by this specification for binding XML document content (messages) to code lists: schema-time binding through XML Schema appinfo annotations, and run-time binding through the cli:codeListURI attribute. The first example shows the code list bound to the message at schema time:

The second example shows the code list bound to the XML data through run-time binding, using the cli:codeListURI attribute.

Appendix D.1. Vehicle make and model code list
Table D-1: Vehicle make and model code list
Make codeMake descriptionModel codeModel descriptionClass
FORDFordFUSFusionAuto
HONDHondaCIVCivicAuto
HONDHondaCRVCRVSUV
DODGDodgeR15Ram 1500Pickup
NISSNissanALTAltimaAuto
FORDFordF15F-150Pickup
TOYTToyotaCOACorollaAuto
FORDFord500Five HundredAuto
HONDHondaACCAccordAuto
TOYTToyotaCAMCamryAuto
CHEVChevroletSLVSilveradoPickup
MERZMercedes-Benz500500 SeriesAuto
Appendix D.2. Make–Model code list CSV file
Make code,Make description,Model code,Model description,Class
FORD,Ford,FUS,Fusion,Auto
HOND,Honda,CIV,Civic,Auto
HOND,Honda,CRV,CRV,SUV
DODG,Dodge,R15,Ram 1500,Pickup
NISS,Nissan,ALT,Altima,Auto
FORD,Ford,F15,F-150,Pickup
TOYT,Toyota,COA,Corolla,Auto
FORD,Ford,500,Five Hundred,Auto
HOND,Honda,ACC,Accord,Auto
TOYT,Toyota,CAM,Camry,Auto
CHEV,Chevrolet,SLV,Silverado,Pickup
MERZ,Mercedes-Benz,500,500 Series,Auto
Appendix D.3. Make–Model code list Genericode file
<?xml version="1.0" encoding="US-ASCII"?>
<gc:CodeList xmlns:ct="http://release.niem.gov/niem/conformanceTargets/3.0/"
             xmlns:gc="http://docs.oasis-open.org/codelist/ns/genericode/1.0/"
             xmlns:gca="http://example.org/namespace/genericode-appinfo">
   <Annotation>
      <AppInfo>
         <gca:ConformanceTargets ct:conformanceTargets="http://reference.niem.gov/niem/specification/code-lists/4.0/#GenericodeCodeListDocument"/>
      </AppInfo>
  </Annotation>
   <Identification>
      <ShortName>VMA</ShortName>
      <Version>1</Version>
      <CanonicalUri>http://example.org/code-list/vehicle-make-model</CanonicalUri>
      <CanonicalVersionUri>http://example.org/code-list/vehicle-make-model/2013-03-05</CanonicalVersionUri>
   </Identification>
   <ColumnSet>
      <Column Id="make" Use="required">
         <ShortName>Make-code</ShortName>
         <Data Type="token"/>
      </Column>
      <Column Id="make-descr" Use="required">
         <ShortName>Make-description</ShortName>
         <Data Type="string"/>
      </Column>
      <Column Id="model" Use="required">
         <ShortName>Model-code</ShortName>
         <Data Type="token"/>
      </Column>
      <Column Id="model-descr" Use="required">
         <ShortName>Model-description</ShortName>
         <Data Type="string"/>
      </Column>
      <Column Id="class" Use="required">
         <ShortName>Class</ShortName>
         <Data Type="token"/>
      </Column>
      <Key Id="key-make-model">
         <ShortName>Key</ShortName>
         <ColumnRef Ref="make"/>
         <ColumnRef Ref="model"/>
      </Key>
   </ColumnSet>
   <SimpleCodeList>
      <Row>
         <Value>
            <SimpleValue>FORD</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>Ford</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>FUS</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>Fusion</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>Auto</SimpleValue>
         </Value>
      </Row>
      <Row>
         <Value>
            <SimpleValue>HOND</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>Honda</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>CIV</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>Civic</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>Auto</SimpleValue>
         </Value>
      </Row>
      <Row>
         <Value>
            <SimpleValue>HOND</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>Honda</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>CRV</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>CRV</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>SUV</SimpleValue>
         </Value>
      </Row>
      <Row>
         <Value>
            <SimpleValue>DODG</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>Dodge</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>R15</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>Ram 1500</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>Pickup</SimpleValue>
         </Value>
      </Row>
      <Row>
         <Value>
            <SimpleValue>NISS</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>Nissan</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>ALT</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>Altima</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>Auto</SimpleValue>
         </Value>
      </Row>
      <Row>
         <Value>
            <SimpleValue>FORD</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>Ford</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>F15</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>F-150</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>Pickup</SimpleValue>
         </Value>
      </Row>
      <Row>
         <Value>
            <SimpleValue>TOYT</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>Toyota</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>COA</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>Corolla</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>Auto</SimpleValue>
         </Value>
      </Row>
      <Row>
         <Value>
            <SimpleValue>FORD</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>Ford</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>500</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>Five Hundred</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>Auto</SimpleValue>
         </Value>
      </Row>
      <Row>
         <Value>
            <SimpleValue>HOND</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>Honda</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>ACC</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>Accord</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>Auto</SimpleValue>
         </Value>
      </Row>
      <Row>
         <Value>
            <SimpleValue>TOYT</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>Toyota</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>CAM</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>Camry</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>Auto</SimpleValue>
         </Value>
      </Row>
      <Row>
         <Value>
            <SimpleValue>CHEV</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>Chevrolet</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>SLV</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>Silverado</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>Pickup</SimpleValue>
         </Value>
      </Row>
      <Row>
         <Value>
            <SimpleValue>MERZ</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>Mercedes-Benz</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>500</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>500 Series</SimpleValue>
         </Value>
         <Value>
            <SimpleValue>Auto</SimpleValue>
         </Value>
      </Row>
   </SimpleCodeList>
</gc:CodeList>
Appendix D.4. XML instance with schema-time code list binding
<?xml version="1.0" encoding="US-ASCII"?>
<ext:Vehicle xmlns:ext="http://example.org/namespace/extension-schema-time">
  <ext:VehicleMakeCode>DODG</ext:VehicleMakeCode>
  <ext:VehicleModelCode>R15</ext:VehicleModelCode>
</ext:Vehicle>
Appendix D.5. Extension schema with schema-time code list binding
<?xml version="1.0" encoding="us-ascii"?>
<xs:schema
   ct:conformanceTargets="
     http://reference.niem.gov/niem/specification/naming-and-design-rules/4.0/#ReferenceSchemaDocument
     http://reference.niem.gov/niem/specification/code-lists/4.0/#SchemaDocument"
   targetNamespace="http://example.org/namespace/extension-schema-time"
   version="1"
   xmlns:clsa="http://reference.niem.gov/niem/specification/code-lists/4.0/code-lists-schema-appinfo/"
   xmlns:ct="http://release.niem.gov/niem/conformanceTargets/3.0/"
   xmlns:ext="http://example.org/namespace/extension-schema-time"
   xmlns:nc="http://release.niem.gov/niem/niem-core/4.0/"
   xmlns:niem-xs="http://release.niem.gov/niem/proxy/xsd/4.0/"
   xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:annotation>
    <xs:documentation>An extension schema for vehicle make and model values, showing schema-time binding of XML content to a code list.</xs:documentation>
  </xs:annotation>

  <xs:import namespace="http://release.niem.gov/niem/niem-core/4.0/"/>
  <xs:import namespace="http://release.niem.gov/niem/proxy/xsd/4.0/"/>

  <xs:element name="Vehicle" type="nc:VehicleType"
              substitutionGroup="nc:Vehicle">
    <xs:annotation>
      <xs:appinfo>
        <clsa:ComplexCodeListBinding
            codeListURI="http://example.org/code-list/vehicle-make-model">
          <clsa:ElementCodeListBinding elementName="ext:VehicleMakeCode"
                                       columnName="make"/>
          <clsa:ElementCodeListBinding elementName="ext:VehicleModelCode"
                                       columnName="model"/>
        </clsa:ComplexCodeListBinding>
      </xs:appinfo>
    </xs:annotation>
  </xs:element>

  <xs:element name="VehicleMakeCode" type="niem-xs:token"
              substitutionGroup="nc:VehicleMakeAbstract">
    <xs:annotation>
      <xs:documentation>A code for a manufacturer of a vehicle.</xs:documentation>
      <xs:appinfo>
        <clsa:SimpleCodeListBinding
            codeListURI="http://example.org/code-list/vehicle-make-model"
            columnName="make"/>
      </xs:appinfo>
    </xs:annotation>
  </xs:element>

  <xs:element name="VehicleModelCode" type="niem-xs:token"
              substitutionGroup="nc:VehicleModelAbstract">
    <xs:annotation>
      <xs:documentation>A code for a model of a vehicle.</xs:documentation>
      <xs:appinfo>
        <clsa:SimpleCodeListBinding
            codeListURI="http://example.org/code-list/vehicle-make-model"
            columnName="model"/>
      </xs:appinfo>
    </xs:annotation>
  </xs:element>

</xs:schema>
Appendix D.6. XML catalog for schema-time code list binding
<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
<catalog prefer="public" xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
  <uri name="http://example.org/namespace/extension-schema-time"
       uri="extension.xsd"/>
  <uri name="http://example.org/code-list/vehicle-make-model"
       uri="../make-model.gc"/>
  <nextCatalog catalog="../../niem/xml-catalog.xml"/>
</catalog>
Appendix D.7. XML instance with run-time code list binding
<?xml version="1.0" encoding="US-ASCII" standalone="yes"?>
<nc:Vehicle
    xmlns:cli="http://reference.niem.gov/niem/specification/code-lists/4.0/code-lists-instance/"
    xmlns:ext="http://example.org/namespace/extension-run-time"
    xmlns:nc="http://release.niem.gov/niem/niem-core/4.0/">
  <ext:VehicleMakeCode
      cli:codeListURI="http://example.org/code-list/vehicle-make-model"
      cli:codeListColumnName="make"
    >DODG</ext:VehicleMakeCode>
  <ext:VehicleModelCode
      cli:codeListURI="http://example.org/code-list/vehicle-make-model"
      cli:codeListColumnName="model"
    >R15</ext:VehicleModelCode>
</nc:Vehicle>
Appendix D.8. Extension schema with run-time code list binding
<?xml version="1.0" encoding="us-ascii"?>
<xs:schema
   ct:conformanceTargets="http://reference.niem.gov/niem/specification/naming-and-design-rules/4.0/#ExtensionSchemaDocument"
   targetNamespace="http://example.org/namespace/extension-run-time"
   version="1"
   xmlns:cli="http://reference.niem.gov/niem/specification/code-lists/4.0/code-lists-instance/"
   xmlns:ct="http://release.niem.gov/niem/conformanceTargets/3.0/"
   xmlns:ext="http://example.org/namespace/extension-run-time"
   xmlns:nc="http://release.niem.gov/niem/niem-core/4.0/"
   xmlns:structures="http://release.niem.gov/niem/structures/4.0/"
   xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:annotation>
    <xs:documentation>An extension schema for vehicle make and model values, providing for run-time binding of XML content to a code list.</xs:documentation>
  </xs:annotation>

  <xs:import namespace="http://release.niem.gov/niem/niem-core/4.0/"/>
  <xs:import namespace="http://release.niem.gov/niem/structures/4.0/"/>
  <xs:import namespace="http://reference.niem.gov/niem/specification/code-lists/4.0/code-lists-instance/"/>

  <xs:complexType name="CodeType">
    <xs:annotation>
      <xs:documentation>A data type for a code with codes sourced from an external code list.</xs:documentation>
    </xs:annotation>
    <xs:simpleContent>
      <xs:extension base="xs:token">
        <xs:attributeGroup ref="structures:SimpleObjectAttributeGroup"/>
        <xs:attribute ref="cli:codeListColumnName" use="optional"/>
        <xs:attribute ref="cli:codeListConstrainingIndicator" use="optional"/>
        <xs:attribute ref="cli:codeListURI" use="required"/>
      </xs:extension>
    </xs:simpleContent>
  </xs:complexType>

  <xs:element name="VehicleMakeCode" type="nc:CodeType"
              substitutionGroup="nc:VehicleMakeAbstract">
    <xs:annotation>
      <xs:documentation>A code for a manufacturer of a vehicle.</xs:documentation>
    </xs:annotation>
  </xs:element>

  <xs:element name="VehicleModelCode" type="nc:CodeType"
              substitutionGroup="nc:VehicleModelAbstract">
    <xs:annotation>
      <xs:documentation>A code for a model of a vehicle.</xs:documentation>
    </xs:annotation>
  </xs:element>

</xs:schema>
Appendix D.9. XML catalog for run-time code list binding
<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
<catalog prefer="public" xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
  <uri name="http://example.org/namespace/extension-run-time"
       uri="extension.xsd"/>
  <uri name="http://reference.niem.gov/niem/specification/code-lists/4.0/code-lists-instance/"
       uri="../../../code-lists-instance.xsd"/>
  <uri name="http://example.org/code-list/vehicle-make-model"
       uri="../make-model.gc"/>
  <nextCatalog catalog="../../niem/xml-catalog.xml"/>
</catalog>
Appendix E. Index
Appendix F. Index of definitions
Appendix G. Index of rules