Niem embedding schematron in xml schema documents

Webb Roberts, Georgia Tech Research Institute

This document specifies the data model, XML components, and XML data for use with the National Information Exchange Model (NIEM) version 3.0.

This document is draft of the specification for NIEM-conformant XML Schema documents, components, and instances. It represents the design that has evolved from the collaborative work of the NIEM Business Architecture Committee (NBAC) and the NIEM Technical Architecture Committee (NTAC) and their predecessors.

This specification is a product of the NIEM Program Management Office (PMO).

Send comments on this specification via email to niem-comments@lists.gatech.edu.

This Naming and Design Rules (NDR) document specifies XML Schema documents for use with the National Information Exchange Model (NIEM). NIEM is an information sharing framework based on the World Wide Web Consortium (W3C) Extensible Markup Language (XML) Schema standard. In February 2005, the U.S. Departments of Justice (DOJ) and Homeland Security (DHS) signed a cooperative agreement to jointly develop NIEM by leveraging and expanding the Global Justice XML Data Model (GJXDM) into multiple domains. NIEM is a result of a combined government and industry effort to improve information interoperability and exchange within the United States at federal, state, tribal, and local levels of government.

NIEM specifies a set of reusable information components for defining standard information exchange messages, transactions, and documents on a large scale: across multiple communities of interest and lines of business. These reusable components are rendered in XML Schema documents as type, element, and attribute definitions that comply with the W3C XML Schema specification. The resulting reference schemas are available to government practitioners and developers at http://niem.gov/.

The W3C XML Schema standard enables information interoperability and sharing by providing a common language for describing data precisely. The constructs it defines are basic metadata building blocks — baseline data types and structural components. Users employ these building blocks to describe their own domain-oriented data semantics and structures, as well as structures for specific information exchanges and components for reuse across multiple information exchanges. Rules that profile allowable XML Schema constructs and describe how to use them help ensure that those components are consistent and reusable.

This document specifies principles and enforceable rules for NIEM data components and schemas. Schemas and components that obey the rules set forth here are considered to be NIEM-conformant.

This document was developed to specify NIEM 3.0. Later releases of NIEM may be specified by later versions of this document. The document covers the following issues in depth:

• The underlying NIEM data model
• Guiding principles behind the design of NIEM
• Rules for using XML Schema constructs in NIEM
• Rules for modeling and structuring NIEM-conformant schemas
• Rules for creating NIEM-conformant instances
• Rules for naming NIEM components
• Rules for extending NIEM-conformant components

This document does NOT address the following:

• A formal definition of the NIEM data model. Such a definition would focus on the Resource Definition Framework (RDF) and concepts not strictly required for interoperability. This document instead focuses on definition of schemas that work with the data model, to ensure translatability and interoperability.
• A detailed discussion of NIEM architecture and schema versioning.
• The artifacts of the NIEM information exchange process.

This document is intended as a technical specification. It is not intended to be a tutorial or a user guide.

This document targets practitioners and developers who employ NIEM for information exchange and interoperability. Such information exchanges may be between or within organizations. The NIEM reference schemas provide system implementers much content on which to build specific exchanges. However, there is a need for extended and additional content. The purpose of this document is to define the rules for such new content so that it will be consistent with the NIEM reference schemas. These rules are intended to establish and, more important, enforce a degree of standardization on a national level.

This document uses formatting and syntactic conventions to clarify meaning and avoid ambiguity.

This document relies on references to many outside documents. Such references are noted by bold, bracketed inline terms. For example, a reference to RFC 2119 is shown as [RFC 2119]. All reference documents are recorded in Appendix A, References, below.

In addition to special formatting for definitions, principles, and rules, this document uses consistent formatting to identify NIEM components.

Courier : All words appearing in Courier font are values, objects, keywords, or literal XML text.

Italics: All words appearing in italics, when not titles or used for emphasis, are special terms with definitions appearing in this document.

Throughout the document, fragments of XML Schema or XML instances are used to clarify a principle or rule. These fragments are specially formatted in Courier font and appear in text boxes. An example of such a fragment follows:

This document uses both Clark notation and QName notation to represent qualified names.

QName notation is defined by [XML Namespaes], §4, Qualified Names . A QName for the XML Schema string datatype is xs:string . Namespace prefixes used within this specification are listed in Section 2.4, Use of namespaces, below.

This document sometimes uses Clark notation to represent qualified names in normative text. Clark notation is described by [ClarkNS], and provides the information in an XML qualified name (as defined by [XML Namespaes]) without the need to define a namespace prefix and then reference that namespace prefix. A Clark notation representation for the qualified name for the XML Schema string datatype is string .

Each Clark notation value consists of a namespace URI surrounded by curly braces, concatenated with a local name. Clark notation is frequently used to represent the qualified name for an attribute with no namespace, which is ambiguous when represented using QName notation. For example, the element targetNamespace , which has no [namespace name] property, is represented in Clark notation as <>targetNamespace .

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.

• xs : The namespace for the XML Schema definition language as defined by [XML Schema Structures] and [XML Schema Datatypes], http://www.w3.org/2001/XMLSchema .
• xsi : The namespace of attributes defined by [XML Schema Structures] for direct use in XML documents, http://www.w3.org/2001/XMLSchema-instance .
• sch : The Schematron namespace URI, as defined by [Schematron], http://purl.oclc.org/dsdl/schematron .
• nf : The namespace defined by this specification for XPath functions, http://reference.niem.gov/niem/specification/naming-and-design-rules/3.0/#NDRFunctions .
• ct : The namespace defined by [CTAS] for the conformanceTargets attribute, http://release.niem.gov/niem/conformanceTargets/3.0/ .
• appinfo : The namespace for the [appinfo namespace] , http://release.niem.gov/niem/appinfo/3.0/ .
• structures : The namespace for the [structures namespace] , http://release.niem.gov/niem/structures/3.0/ .

This document includes a variety of content. Some content is normative (binding and enforceable in implementations), while other content is informative (explanatory, but not part of the NIEM specification). In general, the informative material appears as supporting text and specific rationales for the normative material.

Conventions used within this document include:

A formal definition of a term associated with NIEM.

Definitions are normative.

A guiding principle for NIEM.

The principles represent the requirements, concepts, and goals that have helped shape the NIEM. Principles are informative, not normative, but act as the basis on which the rules are defined.

Accompanying each principle is a short discussion section that justifies the application of the principle to NIEM design.

Principles are numbered in the order in which they appear in the document.

An enforceable rule for NIEM.

Add info about rule classes

Rules state specific requirements on artifacts, such as schemas and instances. Most rules apply to conformant schemas, while others apply to instances. The rules are normative.

Rules are stated using both XML InfoSet terminology (elements and attributes) and XML Schema terminology (schema components). The choice of terminology is driven by which standard best expresses the rule. Certain concepts are more clearly expressed using XML InfoSet information items, others using the XML Schema data model; still others are best expressed using a combination of terminology drawn from both standards.

Remove the bit here about rationales

Rules have rationales that justify the need for the rule. For clarity, there may be multiple rules that have the same rationale.

Rules and supporting text may use Extended Backus-Naur Form (EBNF) notation as defined by [XML] §6, Notation .

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

Each rule is accompanied by a description of its applicability. This identifies the type of schema to which the rule applies or indicates whether the rule is applicable to XML documents or element information items. Each entry in the list is a code from Table 5-1, Codes representing conformance targets, below. If a code appears in the applicability list for a rule, then the rule applies to the corresponding conformance target. The conformance targets are defined in Section 4, Conformance targets, below.

This document defines many normative rules using Schematron rule-based validation syntax, as defined by [Schematron]. Effort has been made to make the rules precise and unambiguous. Very detailed text descriptions of rules can introduce ambiguity, and they are not directly executable by users. Providing NDR rules that are expressed as Schematron rules ensures that the rules are precise, and that they are directly executable through commercially-available and free tools.

Many rules herein do not have executable Schematron supporting them. Some are not fit for automatic validation, and others may be difficult or cumbersome to express in Schematron. In neither case are such rules be any less normative. A rule that has no Schematron is just as normative as a rule that does have Schematron.

The Schematron rules are written using XPath2 as defined by [XPath 2]. These executable rules are normative.

An execution of a Schematron pattern that issues a failed assert represents a validation error, and signfies that the assessed artifact vioates a requirement of a conformance rule.

An execution of a Schematron pattern that issues a report indicates cause for concern. This may be:

• An indication that the automated rules are not sufficient to validate a conformance rule, and that another means is required to ensure conformance. This is frequently a reference to another specification.
• an indication that an automated rule has found that the assessed artifact violates a recommendation of the specification (e.g., a SHOULD, rather than a MUST), and that attention should be paid to ensure that the artifact maintains the spirit of the specification.

In either case, the Schematron reporting mechanism may be used to identify specific location within artifacts that need further attention.

The Schematron within this document is supported by functions, to make the rules more comprehensible, and to abstract away process-specific operations. Each function has a normative XPath interface and a normative text definition. Any implementation provided for these functions should be considered informative, not normative, but may be useful for certain implementations of the rules.

The following XPath functions are defined normatively when used within Schematron by this specification:

nf:get-document-element($context as element()) as element()

nf:get-target-namespace($element as element()) as xs:anyURI

nf:resolve-element($context as element(), $qname as xs:QName) as element()*

nf:resolve-namespace($context as element(), $namespace-uri as xs:string) as element(xs:schema)*

nf:resolve-type($context as element(), $qname as xs:QName) as element()*

nf:has-effective-conformance-target($context as element(), $match as xs:anyURI*) as xs:boolean

The following Schematron namespace declarations are normative for the Schematron rules and supporting code within this specification:

Note that the binding of the prefix xml to the XML namespace ( http://www.w3.org/XML/1998/namespace ) is implicit.

This document uses standard terminology to explain the principles and rules that describe NIEM.

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 [RFC 2119].

The term XML document is as defined by [XML], §2.

When discussing XML documents, this document uses terminology and language as defined by [XML Infoset]. The term information item is frequently omitted.

An element element is an element information item, as defined by [XML Infoset], §2.2, Element Information Items .

Additional terms include:

• element: an element information item
• attribute: an attribute information item
• parent of an element: the [parent] property of an element information item
• child of an element: a member of the [children] property of an element information item
• owner of an attribute: the [owner element] property of an attribute information item
• document element: the [document element] property of a document information item, preferred over the common term root element .

The term document element refers to the element information item that is the value of the [document element] property of a document information item for an [XML document] , as defined by [XML Infoset] §2.1, The Document Information Item .

This document uses many terms from [XML Schema Structures] and [XML Schema Datatypes] in a normative way.

The term schema component is as defined by [XML Schema Structures] §2.2, XML Schema Abstract Data Model , which states:

Schema component is the generic term for the building blocks that comprise the abstract data model of the schema.

The term XML Schema is as defined by [XML Schema Structures] §2.2, XML Schema Abstract Data Model , which states:

An XML Schema is a set of schema components.

The term base type definition is as defined by [XML Schema Structures], §2.2.1.1.

The term simple type definition is as defined by [XML Schema Structures], §2.2.1.2.

The term complex type definition is as defined by [XML Schema Structures], §2.2.1.3.

• the XML Schema definition language: as described by [XML Schema Structures].
• a schema document: as defined by [XML Schema Structures].
• valid: as defined by [XML Schema Structures].
• an XML Schema document set: a set of schema documents that together define an XML schema suitable for assessing the validity of an XML document.

In this document, the name of the referenced schema component may appear without the suffix schema component (e.g., the term complex type definition may be used instead of complex type definition schema component ) to enhance readability of the text.

This document uses XML Namespaces as defined by [XML Namespaes] and [XML Namespaces Errata].

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

The term conformance target is as defined by [CTAS], 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 as defined by [CTAS], which states:

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

This section defines and describes conformance targets of this specification. Each conformance target has a formal definition, along with a notional description of the characterstics and intent of each. These include:

• Section 4.1.1, Reference schema document
• Section 4.1.2, Extension schema document
• Section 4.1.3, Schema document set
• Section 4.1.4, Instance documents and elements

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

A conformant reference schema document is a schema document that is intended to be the authoritative definition schema for a namespace. Examples include NIEM Core and NIEM domains.

Some characteristics of a reference schema document:

• It is explicitly designated as a reference schema via the conformance targets attribute.
• It provides the broadest, most fundamental definitions of components in its namespace.
• It provides the authoritative definition of business semantics for components in its namespace.
• It is intended to serve as the basis for components in information exchanges and extension schema documents.
• It satisfies all rules specified in the Naming and Design Rules for reference schemas.

Any schema that defines components that are intended to be incorporated into NIEM Core or a NIEM domain may be defined as a reference schema.

The rules for reference schema documents are more stringent than are the rules for other classes of NIEM-conformant schemas. Reference schema documents are intended to support the broadest reuse. They are very uniform in their structure. As they are the primary definitions for data components, they do not need to restrict other data definitions, and they are not allowed to use XML Schema’s restriction mechanisms. Reference schema documents are intended to be as regular and simple as possible.

A conformant extension schema document is a schema document that is intended to provide definitions of data components that are intended for reuse within a more narrow scope than reference schema documents. It is a conformance target of this specification. An extension schema document MUST conform to all rules of this specification that apply to this conformance target. An XML document with a conformance target identifier of http://reference.niem.gov/niem/specification/naming-and-design-rules/3.0/#ExtensionSchemaDocument MUST be a conformant reference schema document.

An extension schema is an XML Schema document that meets all of the following criteria:

• It is explicitly designated as an extension schema document via the conformance targets attribute.
• It provides the broadest, most fundamental definitions of components in its namespace.
• It provides the authoritative definition of business semantics for components in its namespace.
• It contains components that, when appropriate, use or are derived from the components in reference schema documents.
• It is intended to express the additional vocabulary required for an information exchange, above and beyond the vocabulary available from reference schemas, and to also support additional XML Schema validation requirements for an exchange.
• It satisfies all rules specified in the Naming and Design Rules for extension schemas.

An extension schema in an information exchange specification serves several functions. First, it defines new content within a new namespace, which may be an exchange-specific namespace or a namespace shared by several exchanges. This content is NIEM-conformant but has fewer restrictions on it than do [conformant reference schema documents] . Second, the extension schema document bases its content on content from reference schemas documents, where appropriate. Methods of deriving content include using (by reference) existing components, as well as creating extensions and restrictions of existing components.

For example, an information exchange specification may define a type for an exchange-specific phone number and base that type on a type defined by the NIEM Core reference schema document. This exchange-specific phone number type may restrict the NIEM Core type to limit those possibilities that are permitted of the base type. Exchange extensions and restrictions must include annotations and documentation to be conformant, but they are allowed to use restriction, choice, and some other constructs that are not allowed in reference schema documents.

Note that exchange specifications may define schemas that meet the criteria of reference schemas for those components that its developers wish to nominate for later inclusion in NIEM Core or in domains.

A conformant schema document set is a collection of XML Schema documents that together are capable of validating a conformant instance XML document. It is a conformance target of this specification. A conformant schema document set MUST conform to all rules of this specification that apply to this conformance target.

This document has specific rules about how NIEM content should be used in XML documents. As well as containing rules for XML Schema documents, this NDR contains rules for NIEM-conformant XML content at a finer granularity than the XML document.

A conformant instance XML document is an XML document that is an instance of a conformant schema document set. It is a conformance target of this specification. A conformant instance XML document MUST conform to all rules of this specification that apply to this conformance target.

A conformant instance XML document is an XML document that satisfies all of the following criteria:

• The document element is locally schema-valid.
• Each element information item within the XML document that has a namespace name matching the target namespace of a [conformant reference schema document] or [conformant extension schema document] is a [conformant element information item] .

Just make these term references

In this definition and the next definition below, the term XML document is as specified in [XML]. The terms document information item, document element, element information item, namespace name, and local name are as specified in [XML Infoset]. The term valid is as specified in [XML Schema Structures].

Schema-validity may be assessed against a single set of schemas or against multiple sets of schemas. Assessment against schemas is as directed by an IEPD, other instructions, or tools.

Note that the document element (root element) of a NIEM-conformant XML document is not required to be a NIEM-conformant element information item. Other specifications, such as the IEPD specification, may add additional constraints to these to specify IEPD or exchange conformance.

A conformant element information item is an element information item that satisfies all of the following criteria:

• Its namespace name and local name matches an element declared by a [conformant reference schema document] or [conformant extension schema document] .
• It occurs within a [conformant instance XML document] .
• It is locally schema-valid.
• It satisfies all rules specified in the Naming and Design Rules for NIEM-conformant element information items.

Because each NIEM-conformant element information item must be locally schema-valid, each element must validate against the schema definition of the element, even if the element information item is allowed within the document because of a wildcard with processContents of skip . Within a NIEM-conformant XML document, each element that is from a NIEM namespace conforms to its schema specification.

Rules within this document are annotated with conformance target codes. Each rule may be annotated with one or more codes for a conformance target. A rule within this document that is annotated with one of the following codes applies to the corresponding conformance target.

The term conformance target identifier is defined by [CTAS].

  The document MUST be a conformant document as defined by the NIEM Conformance Targets Attribute Specification.  

The term conformant document is defined by §3.2 of [CTAS].

  An element MUST own an attribute conformanceTargets if and only if it is a [document element].  

The term [document element] is a defined term.

  The document MUST have an effective conformance target identifier of http://reference.niem.gov/niem/specification/naming-and-design-rules/3.0/#ReferenceSchemaDocument.  

  The document MUST have an effective conformance target identifier of http://reference.niem.gov/niem/specification/naming-and-design-rules/3.0/#ExtensionSchemaDocument.  

NIEM provides a concrete data model, in the form of a set of XML Schema documents. These schemas may be used to build messages and information exchanges. The schemas spell out what kinds of objects exist and how those objects may be related. XML data that follows the rules of NIEM imply specific meaning. The varieties of XML Schema components used within NIEM-conformant schemas are selected to clarify the meaning of XML data. That is, schema components that do not have a clear meaning have been avoided. NIEM provides a framework within which XML data has a specific meaning.

One limitation of XML and XML Schema is that they do not describe the meaning of an XML document. The XML specification defines XML documents and defines their syntax but does not address the meaning of those documents. The XML Schema specification defines the XML Schema definition language, which describes the structure and constrains the contents of XML documents (schemas).

In a schema, the meaning of a schema component (e.g., element, attribute, or type) may be described using the xs:documentation element. Or, additional information may be included via the xs:appinfo element. Although this may enable humans to understand XML data, more information is needed to support the machine-understandable meaning of XML data. In addition, inconsistency among the ways that schema components may be put together may be a source of confusion.

The RDF Core Working Group of the World Wide Web consortium has developed a simple, consistent conceptual model, the RDF model. The RDF model is described and specified through a set of W3C Recommendations, the Resource Description Framework (RDF) specifications, making it a very well defined standard. The NIEM model and the rules contained in this NDR are based on the RDF model. This provides numerous advantages:

• NIEM’s conceptual model is defined by a recognized standard.
• NIEM’s conceptual model is very well defined.
• NIEM’s conceptual model provides a consistent basis for relating attributes, elements, types, and other XML Schema components.
• NIEM’s use of the RDF model defines what a set of NIEM data means. The RDF specification provides a detailed description of what a statement means. See [RDF Semantics]), §1.3, Intepretations . This meaning is leveraged by NIEM.
• NIEM’s use of the RDF model provides a basis for inferencing and reasoning about XML data that uses NIEM. That is, using the rules defined for the RDF model, programs can determine implications of relationships between NIEM-defined objects.

With the exception of Section 2, NIEM rules are explained in this document without reference to RDF or RDF concepts. Understanding RDF is not required to understand NIEM-conformant schemas or data based on NIEM. However, understanding RDF concepts may deepen understanding of NIEM.

The goal of this section is to clarify the meaning of XML data that is NIEM-conformant and to outline the implications of various modeling constructs in NIEM. The rules for NIEM- conformant schemas and instances are in place to ensure that a specific meaning can be derived from data. That is, the data makes specific assertions, which are well understood since they are derived from the rules for NIEM.

The key concepts underpinning the NIEM conceptual model are discussed in the remainder of this section:

• NIEM and the RDF Model
• NIEM Properties
• Unique Identification of Data Objects
• NIEM Data Model Is Explicit, Not Implicit
• NIEM Data Model Implementation in XML Schema

NIEM has its foundation in the RDF model. This helps to ensure that NIEM-conformant data has precise meaning. The RDF view of what data means is clarified by [RDF Semantics]:

…asserting a sentence makes a claim about the world…an assertion amounts to stating a constraint on the possible ways the world might be.

The RDF view of the meaning of data carries into NIEM: NIEM elements form statements that make claims about the world: that a person has a name, a residence location, a spouse, etc. The assertion of one set of facts does not necessarily rule out other statements: A person could have multiple names, could have moved, or could be divorced. Each statement is a claim asserted to be true by the originator of the statement.

This NDR discusses NIEM data in terms of objects, a term more accessible than the word used by RDF, resources. RDF defines the world in terms of resources. [RDF Semantics] describes what may constitute a resource:

…no assumptions are made here about the nature of resources; resource is treated here as synonymous with entity , i.e., as a generic term for anything in the universe of discourse.

RDF resources coincide with NIEM objects and associations. That is, both objects and associations in NIEM are RDF resources with the additional constraints:

• A NIEM object or association is an instance of a complex type defined by an XML Schema document.
• The XML Schema document that defines a NIEM object is a NIEM-conformant schema.

NIEM associations are defined as n-ary properties as described in [N-ary], use case 3. NIEM object types are defined in Section 7.4.1, Object Types. NIEM associations are defined in Section 7.4.3, Association Types. Assertions are made via NIEM-conformant XML data, described by Section 8, XML Instance Rules.

The XML Schema types that define NIEM objects and associations are related to each other via elements and attributes. That is, a type contains elements and attributes, and an element or attribute has a value that is an instance of an XML Schema type. In NIEM, these elements and attributes are XML Schema representations of RDF properties, which are described by [RDF Primer], 2.1 Basic Concepts :

RDF is based on the idea that the things being described have properties which have values, and that resources can be described by making statements…that specify those properties and values.

This describes how NIEM works: schemas describe things and their properties. NIEM- conformant data specifies objects, the values of their properties, and the relationships between them.

There are several kinds of assertions that may be made with NIEM-conformant data. Examples include:

• An assertion that an object exists. An occurrence of an element commonly establishes the existence of an object. Such an object may be tangible or intangible. For example, the element nc:Person in an exchange implies that a person does or did exist. An element may also express that an object does not exist (e.g., the license plate ABC123 was never issued), but this is an uncommon case. Descriptions of objects may carry an implicit assumption that objects exist. Such an assumption is dependent on the message in which such descriptions are made. If an object that is described does not exist, it should be made explicit in the definition of an element containing or referring to the object.
• An assertion that an object has a characteristic. A feature or quality of an object is commonly represented by an element appearing within the element that establishes the object. For example, the height of a person is described by the nc:PersonHeightMeasure element. The nc:PersonHeightMeasure element occurs as XML content of the nc:Person element. In some cases, a characteristic may be represented by an attribute owned by an element.
• An assertion that an object participates in a relationship. A relationship between objects may be established in any of several ways:
  • Both objects may be referenced from an association that establishes the relationship. Associations are also useful for expressing n-ary relationships, as well as relationships supported by additional data.
  • An element may occur within one object that indicates the relationship with the other object. This element may be either a content element or a reference element.

  The NIEM Core schema and some domain schemas have been normalized such that a minimum number of reference or content elements establish relationships. In these cases, use of an association is the more common method for establishing a relationship. However, in an exchange, using a reference or content element to express a relationship may be the simpler, preferred method for expressing a relationship.

  7.2. NIEM properties

  NIEM-conformant data describes characteristics of objects and relationships between objects. In RDF, these characteristics and relationships are called properties of objects, which is also how NIEM refers to them. NIEM represents properties with element declarations and attribute declarations.

  Within data, a property relates XML data much as a verb relates nouns in a sentence: a verb has a subject and an object.

  • The property itself: What relationship is being asserted? For example, the property may say that a weapon has a user, or that someone has hair of a particular color.
  • The subject: About what object is the property being asserted? This would be the weapon that has the user, or the person whose hair is being described.
  • The object: What is the value of the property, or with what other object does the relationship exist? This would be the person who is the user of the weapon or the person whose hair has the color brown.

  A property relates two objects. Data will describe an object having a characteristic with a specific value or will describe an object with a particular relationship to another object. All properties are pair-wise: between two objects, or between an object and a value.

  In theory, any relationship that involves more than two objects may be modeled as a set of binary properties. In NIEM, such relationships may be expressed either as a set of properties (i.e., as element and attribute declarations) or as a complex type defining an association.

  7.3. Unique identification of data objects

  In NIEM, an exchange is generally adhoc. That is, a message may be generated without any persistence. It exists only to exchange data and may not have any universal meaning beyond that specific exchange. As such, a message may or may not have a URI as an identifier. NIEM was designed with the assumption that a given exchange need not have any unique identifier; NIEM does not require a unique identifier. NIEM also does not require any object (data instance) to be identified by a URI. This differs from RDF, in which all entities (other than literal values) are identified by globally meaningful URIs.

  A NIEM-conformant instance uses XML IDs to identify objects within an XML document; The NIEM XML ID is an attribute structures:id of type xs:ID . These IDs are not assumed by NIEM to have any universal significance; they need only be unique within the XML document. The use of an ID is required only when an object must be referenced within the document. NIEM recognizes no correlation between these local IDs and any URI.

  Any given implementation, message, or IEPD may be defined to apply a URI or other universally meaningful identifier to an object or message. However, NIEM has no such requirement.

  7.4. NIEM data model is explicit, not implicit

  In NIEM data, that which is not stated is not implied. If data says a person’s name is John, it is not implicitly saying that he does not have other names, or that John is his legal name, or that he is different from a person known as Bob. The only assertion being made is that one of the names by which this person is known is John .

  This is one reason that definitions of NIEM content are so important. The definitions must state exactly what any given statement implies. The concept of legal name may be defined that makes additional assertions about a name of a person. Such assertions must be made explicit in the definition of the relationship.

  7.5. NIEM data model implementation in XML Schema

  NIEM defines rules for XML Schema documents that enforce the NIEM conceptual model. The schemas that follow these rules are referred to as NIEM-conformant schemas.

  As discussed above, NIEM classes and properties are mapped onto XML Schema components. The following is an example of how a NIEM class for a person is rendered as an XML Schema complex type definition:

  Figure 7-1: Conceptual class rendered as XML Schema complex type

    A data type for a human being.              

  Note that the complex type definition incorporates not only the class itself, but also identifies properties that have a range (e.g., rdfs:range ) of the class.

  The following is an example of how a property for a conveyance operator is rendered as a NIEM element declaration:

  Figure 7-2: Conceptual property rendered as element declaration

    A person who operates or drives a conveyance.  

  NIEM also defines rules for XML documents that enforce the NIEM conceptual model. An XML document is a [conformant instance XML document] if it follows the rules specified by the NIEM-conformant schema, as well as additional rules that are NIEM-specific. For example, in a NIEM-conformant XML document, a reference ( structures:ref ) must refer to a data element that is of an appropriate XML Schema type. If this is not the case, the document may be valid according to the schema, but it will not be a [conformant instance XML document] .

  8. Guiding principles

  Principles in this specification provide a foundation for the rules. These principles are generally applicable in most cases. They should not be used as a replacement for common sense or appropriate special cases.

  The principles are not operationally enforceable; they do not specify constraints on XML Schema documents and instances. The rules are the normative and enforceable manifestation of the principles.

  The principles discussed in this section are categorized as follows:

  • Specification Guidelines
  • XML Schema Design Guidelines
  • Modeling Design Guidelines
  • Implementation Guidelines
  8.1. Specification guidelines

  The principles in this section address what material should be included in this NDR and how it should be represented.

  8.1.1. Keep specification to a minimum

  This specification should state what is required for interoperability, not all that could be specified. Certain decisions (such as normative XML comments) could create roadblocks for interoperability, making heavy demands on systems for very little gain. The goal is not standardization for standardization’s sake. The goal is to maximize interoperability and reuse.

  [Principle 1]

  This specification SHOULD specify what is necessary for semantic interoperability and no more.

  The term semantic interoperability is here defined as the ability of two or more computer systems to exchange information and have the meaning of that information automatically interpreted by the receiving system accurately enough to produce useful results.

  8.1.2. Focus on rules for schemas

  This specification should try, as much as is possible, to specify schema-level content. This is a specification for schemas, and so it should specify schemas. It should avoid specifying complex data models or data dictionaries.

  [Principle 2]

  This specification SHOULD focus on providing rules for specifying schemas.

  8.1.3. Use specific, concise rules

  A rule should be as precise and specific as possible to avoid broad, hard-to-modify rules. Putting multiple clauses in a rule makes it harder to enforce. Using separate rules allows specific conditions to be clearly stated.

  [Principle 3]

  This specification SHOULD feature rules thatare as specific, precise, and concise as possible.

  8.2. XML Schema design guidelines

  The principles in this section address how XML Schema technology should be used in designing NIEM-conformant schemas and instances.

  8.2.1. Disallow content modification with XML processors

  XML Schema has constructs that can make the data provided by XML processors different before and after schema processing. Anexample of this is the use of XML Schema attribute declarations with default values. Before schema validation, there may be no attribute value, but after processing, the attribute value exists.

  Within NIEM, the purpose of processing instances against schemas is solely validation: testing that data instances match desired constraints and guidelines. It should not be used to change the content of data instances.

  [Principle 4]

  The content of a NIEM-conformant data instance SHOULD NOT be modified by processing against XML Schema documents.

  8.2.2. Use XML validating parsers for content validation

  NIEM is designed for XML Schema validation. A primary goal is to maximize the amount of validation that may be performed by XML Schema-validating parsers.

  XML Schema validates content using content models: descriptions of what elements and attributes may be contained within an element, and what values are allowable. It is the XML element hierarchy (elements with attributes and unstructured content, contained by other elements) that the XML Schema definition language specifies and that XML Schema validating parsers can validate.

  Mechanisms involving linking using attribute and element values are useful, but they should only be relied on when absolutely necessary, as XML Schema-validating parsers cannot readily validate them. For example, if a link is established via attribute values, an XML Schema- validating parser cannot determine that participants have appropriate type definitions. Whenever possible, NIEM content should rely on XML syntax that can be validated with XML Schema.

  [Principle 5]

  NIEM-conformant schemas and NIEM-conformant XML documents SHOULD use XML Schema validating parsers for validation of XML content.

  8.2.3. Validate for conformance to reference schemas

  Systems that operate on XML data have the opportunity to perform multiple layers of processing. Middleware, XML libraries, schemas, and application software may process data. The primary purpose of XML Schema validation is to restrict processed data to that data that conforms to agreed-upon rules. This restriction is achieved by marking as invalid that data that does not conform to the rules defined by the schema.

  [Principle 6]

  Systems that use NIEM-conformant data SHOULD mark as invalid data that does not conform to the rules defined by applicable XML Schema documents.

  8.2.4. Allow multiple schemas for XML constraints

  The NIEM does not attempt to create a one-size-fits-all schema to perform all validation. Instead, it creates a set of reference schemas, on which additional constraints may be placed. It also does not focus on language-binding XML Schema implementations, which convert XML Schema definitions into working programs. It is, instead, focused on normalizing language and preserving the meaning of data.

  [Principle 7]

  Constraints on XML instances MAY be validated by multiple schema validation passes, using multiple schemas for a single namespace.

  8.2.5. Define one reference schema per namespace

  NIEM uses the concept of a reference schema, which defines the structure and content of a namespace. For each NIEM-conformant namespace, there is exactly one NIEM reference schema. A user may use a subset schema or constraint schema in place of a reference schema, but all NIEM-conformant XML documents must validate against a single reference schema for each namespace.

  [Principle 8]

  Each NIEM-conformant namespace SHOULD be defined by exactly one reference schema.

  8.2.6. Disallow mixed content

  XML data that use mixed content are difficult to specify and complicate the task of data processing. Much of the payload carried by mixed content is unchecked and does not facilitate data standardization or validation.

  [Principle 9]

  NIEM-conformant schemas SHOULD NOT specify data that uses mixed content.

  8.2.7. Specify types for all constructs

  Schema components within NIEM all have names. This means that there are no anonymous types, elements, or other components defined by NIEM. Once an application has determined the name (i.e., namespace and local name) of an attribute or element used in NIEM-conformant instances, it will also know the type of that attribute or element.

  There are no local attributes or elements defined by NIEM, only global attributes and elements. This maximizes the ability of application developers to extend, restrict, or otherwise derive definitions of local components from NIEM-conformant components. Using named global components in schemas maximizes the capacity for reuse.

  [Principle 10]

  NIEM-conformant schemas SHOULD NOT use or define local or anonymous components, as they adversely affect reuse.

  8.2.8. Avoid wildcards in reference schemas

  Wildcards in NIEM-conformant schemas work in opposition to standardization. The goal of creating harmonized, standard schemas is to standardize definitions of data. The use of wildcard mechanisms (such as xs:any , which allows insertion of an arbitrary number of elements from any namespace) allows nonstandard data to be passed via otherwise standardized exchanges.

  Avoidance of wildcards in the standard schemas encourages the separation of standardized and nonstandardized data. It encourages users to incorporate their data into NIEM in a standardized way. It also encourages users to extend in a way that may be readily incorporated into NIEM.

  [Principle 11]

  NIEM-conformant components SHOULD NOT incorporate wildcards unless absolutely necessary, as they hinder standardization by encouraging use of nonstandardized data rather than standardized data.

  8.2.9. Provide default reference schema locations

  [XML Schema Structures] provides three ways to specify the physical location of an XML Schema document: schemaLocation , an attribute of the element xs:import , along with xsi:schemaLocation and xsi:noNamespaceSchemaLocation , attributes of an XML Schema document element. In all of these uses, the specification explicitly maintains that the schema location specified is a hint, which may be overridden by applications.

  [Principle 12]

  Schema locations specified within NIEM-conformant reference schemas SHOULD be interpreted as hints and as default values by processing applications.

  8.2.10. Use open standards

  The cooperative efforts of many knowledgeable individuals have resulted in many important published information standards. Where appropriate and applicable, NIEM ought to leverage these standards.

  [Principle 13]

  NIEM standards and schemas SHOULD leverage and enable use of other open standards.

  8.3. Modeling design guidelines

  The principles in this section address the design philosophy used in designing the NIEM conceptual model.

  8.3.1. Namespaces enhance reuse

  NIEM is designed to maximize reuse of namespaces and the schemas that define them. When referring to a concept defined by NIEM, a user should ensure that instances and schemas refer to the namespace defined by NIEM. User-defined namespaces should be used for specializations and extension of NIEM constructs but should not be used when the NIEM structures are sufficient.

  [Principle 14]

  NIEM-conformant instances and schemas SHOULD reuse components from NIEM distribution schemas when possible.

  NIEM relies heavily on XML namespaces to prevent naming conflicts and clashes. Reuse of any component is always by reference to both its namespace and its local name. All NIEM component names have global scope. Therefore, validation always occurs against the reference schemas or subsets thereof.

  Example:

  Figure 8-1: Example of the use of a namespace

  In this example, nc:BinaryCaptureDate is reused by referencing its element declaration through both its namespace (which is bound to the prefix nc: ) and its local name ( BinaryCaptureDate ). If an element named BinaryCaptureDate is declared in another namespace, it is an entirely different element than nc:BinaryCaptureDate . There is no implicit relationship to nc:BinaryCaptureDate .

  From a business perspective, the two elements are likely to be related in the sense that they may have very similar semantic meanings. They may have essentially the same meaning, but slightly different properties. Such a relationship may commonly exist. However, any relationship between the two elements must be made explicit using methods outlined in this document.

  [Principle 15]

  A component SHOULD be identified by its local name together with its namespace. A namespace SHOULD be a required part of the name of a component. A component’s local name SHOULD NOT imply a relationship to components with similar names from other namespaces.

  8.3.2. Design NIEM for extensibility

  NIEM is designed to be extended. Numerous methods are considered acceptable in creating extended and specialized components.

  [Principle 16]

  NIEM-conformant schemas and standards SHOULD be designed to encourage and ease extension and augmentation by users and developers outside the standardization process.

  8.4. Implementation guidelines

  The principles in this section address issues pertaining to the implementation of applications that use NIEM.

  8.4.1. Avoid displaying raw XML data

  XML data should be made human-understandable when possible, but it is not targeted at human consumers. HTML is intended for browsers. Browsers and similar technology provide human interfaces to XML and other structured content. As such, structured XML content does not belong in places targeting humans. Human-targeted information should be of a form suitable for presentation.

  [Principle 17]

  XML data SHOULD be designed for automatic processing. XML data SHOULD NOT be designed for literal presentation to people. NIEM standards and schemas SHOULD NOT use literal presentation to people as a design criterion.

  8.4.2. Leave implementation decisions to implementers

  NIEM is intended to be an open specification supported by many diverse implementations. It was designed from data requirements and not from or for any particular system or implementation. Use of NIEM should not depend on specific software, other than XML Schema-validating parsers.

  [Principle 18]

  NIEM SHOULD NOT depend on specific software packages, software frameworks, or software systems for interpretation of XML instances.

  [Principle 19]

  NIEM schemas and standards SHOULD be designed such that software systems that use NIEM may be built with a variety of off-the-shelf and free software products.

  8.5. Modeling guidelines

  The NIEM Naming and Design Rules (NDR) specify NIEM-conformant components, schemas, and instances. These guidelines influence and shape the more-specific principles and rules in this document. They are derived from best practices and from discussions within the NIEM Business Architecture Committee (NBAC) and the NIEM Technical Architecture Committee (NTAC). This list may grow and evolve as NIEM matures.

  The principles in this section address decisions that data modelers must face when creating NIEM-conformant schema representations of domain data. These guidelines are not absolute (the key word is SHOULD). It may not be possible to apply all guidelines in every case. However, they should always be considered.

  8.5.1. Documentation

  As will be described in later sections of this document, all NIEM components are documented through their definitions and names. Although it is often very difficult to apply, a data component definition should be drafted before the data component name is finalized.

  Drafting the definition for a data component first ensures that the author understands the exact nature of the entity or concept that the data component represents. The component name should subsequently be composed to summarize the definition. Reversing this sequence often results in [data definitions] that very precisely describe the component name but do not adequately describe the entity or concept that the component is designed to represent. This can lead to the ambiguous use of such components.

  [Principle 20]

  A data component definition SHOULD be drafted before the associated data element name is composed.

  8.5.2. Consistent naming

  Components in NIEM should be given names that are consistent with names of other NIEM components. Having consistent names for components has several advantages:

  1. It is easier to determine the nature of a component when it has a name that conveys the meaning and use of the component.
  2. It is easier to find a component when it is named predictably.
  3. It is easier to create a name for a component when clear guidelines exist.
  [Principle 21]

  Components in NIEM SHOULD be given names that are consistent with names of other NIEM components. Such names SHOULD be based on simple rules.

  8.5.3. Reflect the real world

  NIEM provides a standard for data exchange. To help facilitate unambiguous understanding of NIEM reusable components, the names and structures should represent and model the informational aspects of objects and concepts that users are most familiar with. Types should not simply model collections of data.

  [Principle 22]

  Component definitions in NIEM-conformant schemas SHOULD reflect real-world concepts.

  8.5.4. Be consistent

  There should be no conflicts of meaning among types. This holds for types within a namespace, as well as types in different namespaces. A type should be used consistently in similar situations for similar purposes. Types should be defined for clear understanding and ease of intended use.

  [Principle 23]

  Component definitions in NIEM-conformant schemas SHOULD have semantic consistency.

  8.5.5. Reserve inheritance for specialization

  Specialization should not be applied simply for the sake of achieving property inheritance. Specialization should be applied only where it is meaningful and appropriate to model permanent sibling subclasses of a base class that are mutually exclusive of one another.

  [Principle 24]

  Complex type definitions in NIEM-conformant schemas SHOULD use type inheritance only for specialization.

  Note that application of type augmentations is a well-defined exception to this guideline.

  8.5.6. Do not duplicate definitions

  A real-world entity should be modeled in only one way. The definition of a type or element should appear once and only once. Multiple components of identical or closely similar semantics hinder interoperability because too many valid methods exist for representing the same data. For each data concept that must be represented, there should be only one component (and associated type) to represent it.

  Components with very similar semantics may exist in different contexts. For example, a complex type created for a particular exchange may appear to have identical or closely similar semantics to a complex type defined in the NIEM Core schema. However, the type defined at the exchange level will have much more precise business requirements and syntax, compared with the broad definitions that are heavily reused. Specific contextual definitions should be considered semantic changes. This includes the application of augmentations to create a specialized type for a specific use.

  Two components may have the same definition while having different representations. For example, a string may hold the complete name of a person, or the name may be represented by a structure that separates the components of the name into first, last, etc. The definition of alternative representations should not be considered duplication.

  [Principle 25]

  Multiple components with identical or undifferentiated semantics SHOULD NOT be defined. Component definitions SHOULD have clear, explicit distinctions.

  8.5.7. Keep it simple

  All NIEM content and structure is fundamentally based on business requirements for information exchange. To encourage adoption and use in practice, NIEM must implement business requirements in simple, consistent, practical ways.

  [Principle 26]

  NIEM-conformant schemas SHOULD have the simplest possible structure, content, and architecture consistent with real business requirements.

  8.5.8. Be aware of scope

  The scope of components defined in NIEM-conformant schemas should be carefully considered. Some components represent simple data values, while others represent complex objects with many parts and relationships. Components should exist in layers. Components should exist as small, narrowly scoped, atomic entities that are used to consistently construct more broadly scoped, complex components (and so on).

  [Principle 27]

  Components defined by NIEM-conformant schemas SHOULD be defined appropriate for their scope.

  8.5.9. Be mindful of namespace cohesion

  Namespaces should maximize cohesion. The namespace methodology helps prevent name clashes among communities or domains that have different business perspectives and may choose identical data names to represent different data concepts. A namespace should be designed so that its components are consistent, may be used together, and may be updated at the same time.

  [Principle 28]

  XML namespaces defined by NIEM-conformant schemas SHOULD encapsulate data components that are coherent, consistent, and internally related as a set. A namespace SHOULD encapsulate components that tend to change together.

  9. Conformance to standards 9.1. Conformance to XML [Rule 9-1] (REF, EXT, INS) (Constraint)

    The document MUST be a well-formed XML document, as defined by Extensible Markup Language.  

  See [XML] for the normative definition of well-formed XML document.

  9.2. Conformance to XML Namespaces [Rule 9-2] (REF, EXT, INS) (Constraint)

    The document MUST be namespace-well-formed.   

  The term namespace-well-formed is normatively defined by [XML Namespaes] and [XML Namespaces Errata].

  [Rule 9-3] (REF, EXT, INS) (Constraint)

    The document MUST be namespace-valid.   

  The term namespace-valid is normatively defined by [XML Namespaes] and [XML Namespaces Errata].

  9.3. Conformance to XML Schema [Rule 9-4] (REF, EXT) (Constraint)

    The document MUST be a schema document. The document element of the XML document must be xs:schema.   

  The term schema document is defined by [XML Schema Structures].

  9.4. ISO 11179 Part 4

  Good data definitions are fundamental to data interoperability. You cannot effectively exchange what you cannot understand. NIEM employs the guidance of [ISO 11179-4] as a baseline for its data component definitions. [ISO 11179-4] All NIEM components are documented.

  To advance the goal of creating semantically rich NIEM-conformant schemas, it is necessary that data definitions be descriptive, meaningful, and precise. [ISO 11179-4] provides standard structure and rules for defining data definitions. NIEM uses this standard for component definitions.

  Note that the metadata maintained for each NIEM component contains additional details, including domain-specific usage examples and keywords. Such metadata is used to enhance search and discovery of components in a registry, and therefore, is not included in schemas.

  For convenience and reference, the summary requirements and recommendations in [ISO 11179-4] are reproduced here:

  • Be stated in the singular.
  • State what the concept is, not only what it is not.
  • Be stated as a descriptive phrase or sentence(s).
  • Contain only commonly understood abbreviations.
  • Be expressed without embedding definitions of other data or underlying concepts.
  • State the essential meaning of the concept.
  • Be precise and unambiguous.
  • Be concise.
  • Be able to stand alone.
  • Be expressed without embedding rationale, functional usage, or procedural information.
  • Avoid circular reasoning.
  • Use the same terminology and consistent logical structure for related definitions.
  • Be appropriate for the type of metadata item being defined.

  In addition to the requirements and recommendations of [ISO 11179-4], NIEM applies additional rules to data definitions. These rules are detailed in Section 7.2.1, Human-Readable Documentation.

  These definitions leverage the term definition as defined by [ISO 11179-4]:

  representation of a concept by a descriptive statement which serves to differentiate it from related concepts

  [Definition: ]

  The data definition of a schema component is the content of the first occurrence of the element xs:documentation that is an immediate child of an occurrence of an element xs:annotation that is an immediate child of the element that defines the component.

  [Definition: ]

  In a NIEM-conformant schema, a documented component is an XML Schema component that has an associated [data definition] . Each documented component has a textual definition, so that the component may be well-understood.

  Figure 9-1: Example of data definition of element nc:Activity

    A single or set of related actions, events, or process steps.  

  9.5. ISO 11179 Part 5

  Names are a simple but incomplete means of providing semantics to data components. Data definitions, structure, and context help to fill the gap left by the limitations of naming. The goals for data component names should be syntactic consistency, semantic precision, and simplicity. In many cases, these goals conflict and it is sometimes necessary to compromise or to allow exceptions to ensure clarity and understanding. To the extent possible, NIEM applies [ISO 11179-5] to construct NIEM data component names.

  The set of NIEM data components is a collection of data representations for real-world objects and concepts, along with their associated properties and relationships. Thus, names for these components would consist of the terms (words) for object classes or that describe object classes, their characteristic properties, subparts, and relationships.

  9.5.1. Component names follow ISO 11179 Part 5 Annex A [Rule 9-5] (REF, EXT) (Constraint)

  A NIEM component name SHALL be formed by applying the informative guidelines and examples detailed in Annex A of [ISO 11179-5], with exceptions as specified in this document, most notably those specified in Section 9, Naming Rules.

  The guidelines and examples of [ISO 11179-5] provide a simple, consistent syntax for data names that captures context and thereby imparts a reasonable degree of semantic precision.

  NIEM uses the guidelines and examples of [ISO 11179-5] as a baseline for normative naming rules. However, some NIEM components require bending of these rules. Special naming rules for these classes of components are presented and discussed in Section 9. In spite of these exceptions, most NIEM component names can be disassembled into their [ISO 11179-5] constituent words or terms.

  Example:

  The NIEM component name AircraftFuselageColorCode disassembles as follows:

  • Object class term = Aircraft
  • Qualifier term = Fuselage
  • Property term = Color
  • Representation term = Code

  Section 9, Naming Rules, details the specific rules for each kind of term and how to construct NIEM component names from it. Exceptions for special components are also described in Section 9.

  10. Strategy for a NIEM profile of XML Schema 10.1. Wildcards

  There are many constructs within XML Schema that act as wildcards. That is, they introduce buckets that may carry arbitrary or otherwise nonvalidated content. Such constructs violate [Principle 11], and as such provide implicit workarounds for the difficult task of agreeing on the content of data models. Such workarounds should be made explicitly, outside the core data model.

  The following restrictions help to ban wildcards and arbitrary data:

  • Use of the type xs:anyType is prohibited.
  • Use of the type xs:anySimpleType is prohibited in most cases.
  • Use of the element xs:any is prohibited in reference schemas.
  • Use of the element xs:anyAttribute is prohibited in reference schemas.
  10.2. Components are globally reusable

  Each component defined by a NIEM-conformant schema may be reused from outside the schema document. Every NIEM component has a name. That is, type definitions, and element and attribute declarations are given explicit names; local and anonymous component definition is not allowed.

  This is supported by the following restrictions:

  • Each declaration of an element, attribute, or type is a top-level component (child of xs:schema , rather than a local component defined within another component.
  • There are no anonymous type declarations.

  Additional restrictions ensure that NIEM components are also defined such that new components may be derived from them and substituted for them. Reference schemas are defined to maximize reuse, while extension schemas are defined to enable a developer to customize schema definitions to match her exchange needs. In reference schemas, the following restrictions help enforce reusability through extension and substitution:

  • Element and type declarations in reference schemas may not use block or blockDefault.
  • Element and type declarations in reference schemas may not use final or finalDefault.
  10.3. Avoid recursive model groups

  XML Schema provides the capability for model groups to be recursively defined. This means that a sequence may contain a sequence, and a choice may contain a choice. These rules are designed to keep content models simple, comprehensive, and reusable: The content of an element should boil down to a simple list of elements, defined in as straightforward a manner as is possible to meet requirements.

  10.4. Ensure schema processing does not alter processed data

  XML Schema provides the capability for element and attribute declarations to provide default values when XML instances using those components do not provide values. This is done through the use of the attributes default and fixed , both of which provide default values to attributes and element content.

  The use of default values means that the act of validating a schema will insert a value into an XML instance where none existed prior to schema validation. Schema validation is for rejection of invalid instances, not for modifying instance content, as specified in [Principle 4].

  The transparency of validation to data content is ensured through a prohibition on the use of default and fixed attributes in NIEM-conformant schema documents.

  10.5. Use namespaces rigorously

  Require that every component defined by or used in a NIEM schema has a target namespace.

  XML Schema requires that namespaces used in external references be imported using the xs:import element. The xs:import element appears as an immediate child of the xs:schema element. A schema must import any namespace which is not the local namespace, and which is referenced from the schema.

  The behavior of import statements is not necessarily intuitive. In short, the import introduces namespace into the schema in which the import appears; it has no transitive effect. If the namespaces of an import statement are not referenced from the schema, then the import statement has no effect.

  Certain tools have been seen introducing transitive behavior on imports, which is not portable across XML Schema validating parsers. If namespace 1 imports namespace 2 which imports namespace 3, a reference from namespace 1 to namespace 3 is not legal; namespace 1 must explicitly import namespace 3. A tool that imports transitively may allow schema 1 to reference 3 without a direct import of namespace 3. This is prohibited by rules which require imports of namespaces of referenced components.

  10.6. Documentation is for people; appinfo is for machines

  The XML Schema specification defines two types of annotations: user information and application information. It defines that user information is for human consumption, while application information is for automatic processing.

  Annotations in XML Schema provide for human- and machine-targeted annotations of schema components. [XML Schema Structures] The two types: human-targeted and machine-targeted, are kept separate by the use of two separate container elements defined by XML Schema: xs:documentation and xs:appinfo .

  XML Schema describes the content of xs:documentation elements as user information. This information is targeted for reading by humans. The XML Schema specification does not say what form human-targeted information should take. Within NIEM, user information is plain text with no formatting or XML structure.

  According to the XML Schema specification, the content of xs:documentation elements is intended for human consumption, whereas other structured XML content is intended for machine consumption. Therefore, the xs:documentation element MUST NOT contain structured XML data. As such, any XML content appearing within a documentation element is in the context of human-targeted examples and should be escaped using < and > . This rule also prohibits comments within documentation elements.

  XML comments are not XML Schema constructs and are not specifically associated with any schema-based components. As such, comments are not considered semantically meaningful by NIEM and may not be retained through processing of NIEM schemas.

  11. Profile of XML Schema

  NIEM-conformant schemas use a profile of XML Schema. The W3C XML Schema Language provides many features that allow a developer to represent a data model many different ways. A number of XML Schema constructs are not used within NIEM-conformant schemas. Many of these constructs provide capability that is not currently needed within NIEM. Some of these constructs create problems for interoperability, with tool support, or with clarity or precision of data model definition.

  This section establishes a profile of XML Schema for NIEM-conformant schemas. Because the XML Schema specifications are flexible, comprehensive rules are needed to achieve a balance between establishing uniform schema design and providing developers flexibility to solve novel data modeling problems.

  Note that external schemas (i.e., non-NIEM-conformant schemas) do not need to obey the rules set forth in this section. So long as schema components from external schemas are adapted for use with NIEM according to the modeling rules in Section 7.7, they may be used as they appear in the external standard, even if the schema components themselves violate the rules for NIEM-conformant schemas.

  The following sections are broken down in the order provided by [XML Schema Structures], §2.2, XML Schema Abstract Data Model , followed by a section on a schema document as a whole and a section on schema namespaces and assembly:

  • Section 11.1, Type definition components
  • Section 11.2, Declaration components
  • Section 11.3, Model group components
  • Section 11.4, Identity-constraint definition components
  • Section 11.5, Group definition components
  • Section 11.6, Annotation components
  • Section 11.7, Schema as a whole
  • Section 11.8, Schema assembly

  add issue about requiring imports of referenced components

  11.1. Type definition components 11.1.1. Type definition hierarchy 11.1.1.1. Types prohibited as base types 11.1.1.1.1. No base type of xs:ID [Rule 11-1] (REF, EXT) (Constraint)

    A schema component MUST NOT have an attribute <>base with a value of xs:ID.  

  11.1.1.1.2. No base type of xs:IDREF [Rule 11-2] (REF, EXT) (Constraint)

    A schema component MUST NOT have an attribute <>base with a value of xs:IDREF.  

  11.1.1.1.3. No base type of xs:anyType [Rule 11-3] (REF, EXT) (Constraint)

    A schema component MUST NOT have an attribute <>base with a value of xs:anyType.  

  XML Schema has the concept of the ur-type, a type that is the root of all other types. This type is realized in schemas as xs:anyType .

  NIEM-conformant schemas must not use xs:anyType , because this feature permits the introduction of arbitrary content (i.e., untyped and unconstrained data) into an XML instance. NIEM intends that the schemas describing that instance describe all constructs within the instance.

  11.1.1.1.4. No base type of xs:anySimpleType [Rule 11-4] (REF, EXT) (Constraint)

    A schema component MUST NOT have an attribute <>base with a value of xs:anySimpleType.  

  XML Schema provides a restriction of the ur-type that contains only simple content. This provides a wildcard for arbitrary text. It is realized in XML Schema as xs:anySimpleType .

  NIEM-conformant schemas must not use xs:anySimpleType because this feature is insufficiently constrained to provide a meaningful starting point for content definitions. Instead, content should be based on one of the more specifically defined simple types defined by XML Schema.

  11.1.1.1.5. No base type of xs:NOTATION [Rule 11-5] (REF, EXT) (Constraint)

    A schema component MUST NOT have an attribute <>base with a value of xs:NOTATION.  

  XML Schema notations allow the attachment of system and public identifiers on fields of data. The notation mechanism does not play a part in validation of instances and is not supported by NIEM.

  11.1.2. Simple type definitions 11.1.2.1. Simple type definition is top-level [Rule 11-6] (REF, EXT) (Constraint)

    A simple type definition MUST be top-level.  

  NIEM does not support anonymous types in NIEM-conformant schemas. All XML Schema top-level types (children of the document element) are required by XML Schema to be named. By requiring NIEM type definitions to be top level, they are forced to be named and are globally reusable.

  11.1.2.2. Simple type data definitions 11.1.2.2.1. Simple type has data definition [Rule 11-7] (REF, EXT) (Constraint)

    A simple type MUST be a documented component.  

  11.1.2.2.2. Simple type data definition is not empty [Rule 11-8] (REF, EXT) (Constraint)

    A data definition MUST NOT be empty.  

  11.1.2.3. Simple types prohibited as list item types

  There is no explicit prohibition on the use of xs:NOTATION as list item type, because it is prohibited by [XML Schema Datatypes].

  There is no prohibition on xs:anyType as a list item type, because xs:anyType is not a simple type.

  11.1.2.3.1. No list item type of xs:ID [Rule 11-9] (REF, EXT) (Constraint)

    A schema component MUST NOT have an attribute <>itemType with a value of xs:ID.  

  11.1.2.3.2. No list item type of xs:IDREF [Rule 11-10] (REF, EXT) (Constraint)

    A schema component MUST NOT have an attribute <>itemType with a value of xs:IDREF.  

  11.1.2.3.3. No list item type of xs:anySimpleType [Rule 11-11] (REF, EXT) (Constraint)

    A schema component MUST NOT have an attribute <>itemType with a value of xs:anySimpleType.  

  11.1.2.4. Simple types prohibited as union member types

  There is no explicit prohibition on the use of xs:NOTATION as a union member type, because it is prohibited by [XML Schema Datatypes].

  There is no prohibition on xs:anyType as a union member type, because xs:anyType is not a simple type.

  11.1.2.4.1. No union member types of xs:ID [Rule 11-12] (REF, EXT) (Constraint)

    A schema component MUST NOT have an attribute <>memberTypes that includes a value of xs:ID.  

  11.1.2.4.2. No union member types of xs:IDREF [Rule 11-13] (REF, EXT) (Constraint)

    A schema component MUST NOT have an attribute <>memberTypes that includes a value of xs:IDREF.  

  11.1.2.4.3. No union member types of xs:anySimpleType [Rule 11-14] (REF, EXT) (Constraint)

    A schema component MUST NOT have an attribute <>memberTypes that includes a value of xs:anySimpleType.  

  11.1.2.5. No simple type disallowed derivation [Rule 11-15] (REF) (Constraint)

    An element xs:simpleType MUST NOT have an attribute <>final.  

  11.1.2.6. Enumeration data definitions 11.1.2.6.1. Enumeration has data definition [Rule 11-16] (REF, EXT) (Constraint)

    An enumeration facet MUST be a documented component.  

  11.1.2.6.2. Enumeration data definition is not empty [Rule 11-17] (REF, EXT) (Constraint)

    A data definition MUST NOT be empty.  

  11.1.3. Complex type definitions 11.1.3.1. Complex type definitions are top-level [Rule 11-18] (REF, EXT) (Constraint)

    A complex type definition must be top-level.  

  Note that this implies that every xs:complexType element has a name attribute.

  11.1.3.2. Complex type data definitions 11.1.3.2.1. Complex type has data definition [Rule 11-19] (REF, EXT) (Constraint)

    A complex type MUST be a documented component.  

  11.1.3.2.2. Complex type data definition is not empty [Rule 11-20] (REF, EXT) (Constraint)

    A data definition MUST NOT be empty.  

  11.1.3.3. No mixed content 11.1.3.3.1. No mixed content on complex type [Rule 11-21] (REF, EXT) (Constraint)

    A complex type declaration MUST NOT have mixed content.  

  Mixed content allows the mixing of data tags with text. Languages such as XHTML use this syntax for markup of text. NIEM-conformant schemas define XML that is for data exchange, not text markup. Mixed content creates complexity in processing, defining, and constraining content.

  Well-defined markup languages exist outside NIEM and may be used with NIEM data. External schemas may include mixed content and may be used with NIEM. However, mixed content must not be defined by NIEM-conformant schemas in keeping with [Principle 9].

  11.1.3.3.2. No mixed content on complex content [Rule 11-22] (REF, EXT) (Constraint)

    A complex type declaration MUST NOT have mixed content.  

  See [Rule 11-21], above, for the rationale for this rule.

  11.1.3.4. Complex type content is explicitly simple or complex [Rule 11-23] (REF, EXT) (Constraint)

    An element xs:complexType MUST have a child element xs:simpleContent or xs:complexContent.  

  XML Schema provides shorthand to defining complex content of a complex type, which is to define the complex type with immediate children that specify elements, or other groups, and attributes. In the desire to normalize schema representation of types and to be explicit, NIEM forbids the use of that shorthand.

  11.1.3.5. Complex content

  Within a reference schema, a complex type with complex content can be created in one of two ways:

  1. By extension of an existing NIEM complex type with complex content.
  2. By extension of a type defined in the structures namespace.

  Both of these methods use the element xs:extension . Within extension schemas, exchange schemas, and subset schemas, the use of xs:restriction to create complex types with complex content is also allowed.

  11.1.3.5.1. Complex content uses extension [Rule 11-24] (REF) (Constraint)

    An element xs:complexContent MUST have a child xs:extension.  

  NIEM does not support the use of complex type restriction in reference schemas. The use of restriction in a reference schema would reduce the ability for that schema to be reused. Restriction may be used in extension schemas.

  Note that XML Schema requires use of the attribute base on xs:extension .

  11.1.3.5.2. Complex type with complex content must have complex content [Rule 11-25] (SET, REF, EXT) (Constraint)

     The base type of complex type that has complex content MUST have complex content.  

  11.1.3.6. Simple content 11.1.3.6.1. Simple content uses extension

  Within a NIEM-conformant schema, a complex type with simple content can be created in one of two ways:

  1. By extension of an existing complex type with simple content.
  2. By extension of an existing simple type.

  Both of these methods use the element xs:extension . Although these two methods have similar syntax, there are subtle differences. NIEM’s conformance rules ensure that any complex type has the necessary attributes for representing IDs, references, metadata, and relationship metadata. Case 1 does not require adding these attributes, as they are guaranteed to occur in the base type. However, in case 2, in which a new complex type is created from a simple type, the attributes for complex types must be added. This is done by reference to the attribute group structures:SimpleObjectAttributeGroup .

  [Rule 11-26] (REF) (Constraint)

    A complex type definition with simple content schema component must have a derivation method of extension.  

  This rule ensures that the definition of a complex type with simple content will use XML Schema extension. This allows for the above cases while disallowing more complicated syntactic options available in XML Schema. The above rule allows for use of xs:restriction within xs:simpleContent in extension schemas.

  11.1.3.6.2. Complex types with simple content have structures:SimpleObjectAttributeGroup [Rule 11-27] (REF) (Constraint)

    A complex type definition with simple content schema component with a derivation method of extension that has a base type definition that is a simple type MUST incorporate the attribute group SimpleObjectAttributeGroup.  

  This rule ensures that a complex type with simple content that is created as an immediate extension of a simple type adds the attributes required for specific NIEM linking mechanisms.

  This creates a pattern for complex type with simple content definition as follows:

  Figure 11-1: Example of complex type with simple content derived from a simple type 11.1.3.7. No complex type disallowed substitutions [Rule 11-28] (REF) (Constraint)

    An element xs:complexType MUST NOT have an attribute <>block.  

  11.1.3.8. No complex type disallowed derivation [Rule 11-29] (REF) (Constraint)

    An element xs:complexType MUST NOT have an attribute <>final.  

  11.2. Declaration components 11.2.1. Element declaration 11.2.1.1. Element declaration is top-level [Rule 11-30] (REF, EXT) (Constraint)

    An element declaration MUST be top-level.  

  All schema components defined by NIEM-conformant schemas must be named, accessible from outside the defining schema, and reusable across schemas. Local element definitions provide named elements that are not reusable outside the context in which they are defined.Requiring named NIEM elements to be top level ensures that they are globally reusable.

  11.2.1.2. Element declaration data definitions 11.2.1.2.1. Element declaration has data definition [Rule 11-31] (REF, EXT) (Constraint)

    An element declaration MUST be a documented component.  

  11.2.1.2.2. Element declaration data definition is not empty [Rule 11-32] (REF, EXT) (Constraint)

    A data definition MUST NOT be empty.  

  11.2.1.3. Untyped element is abstract [Rule 11-33] (REF, EXT) (Constraint)

    A top-level element declaration that has no type MUST be abstract.  

  Untyped element declarations act as wildcards that may carry arbitrary data. By declaring such types abstract, NIEM allows the creation of type independent semantics without allowing arbitrary content to appear in XML instances.

  11.2.1.4. Element of type xs:anySimpleType is abstract

  The type xs:anySimpleType does not have any concrete semantics; The use of xs:anySimpleType is limited to the case where an abstract element is of type xs:anySimpleType, to act as a base for concrete implementations of the element.

  [Rule 11-34] (REF, EXT) (Constraint)

    An element declaration that has a type xs:anySimpleType MUST be abstract.  

  11.2.1.5. Element type not in the XML Schema namespace [Rule 11-35] (REF, EXT) (Constraint)

    An element type that is not xs:anySimpleType MUST NOT have a namespace name xs.  

  The prohibition of element types having the XML Schema namespace subsumes a prohibition of the type xs:anyType .

  11.2.1.6. Element type not in a special namespace [Rule 11-36] (REF, EXT) (Constraint)

    An element type MUST NOT have a namespace name that is in a special namespace.  

  11.2.1.7. Element type is not a simple type [Rule 11-37] (SET) (Constraint)

    An element type MUST NOT be a simple type.  

  11.2.1.8. No element disallowed substitutions [Rule 11-38] (REF) (Constraint)

    An element xs:element MUST NOT have an attribute <>block.  

  11.2.1.9. No element disallowed derivation [Rule 11-39] (REF) (Constraint)

    An element xs:element MUST NOT have an attribute <>final.  

  11.2.1.10. No element value constraints 11.2.1.10.1. No element default values [Rule 11-40] (REF, EXT) (Constraint)

    An element xs:element MUST NOT have an attribute <>default.  

  11.2.1.10.2. No element fixed values [Rule 11-41] (REF, EXT) (Constraint)

    An element xs:element MUST NOT have an attribute <>fixed.  

  11.2.1.11. Element declaration is nillable [Rule 11-42] (REF) (Constraint)

    An [element declaration schema component] MUST have the nillable property with a value of true.  

  11.2.2. Element substitution groups 11.2.3. Attribute declarations 11.2.3.1. Attribute declarations are top-level [Rule 11-43] (REF, EXT) (Constraint)

    An attribute declaration MUST be top-level.  

  All schema components defined by NIEM-conformant schemas are named, accessible from outside the defining schema, and reusable across schemas. Local attribute definitions provide named attributes that are not reusable outside the context in which they are defined. Requiring named NIEM attributes to be top level ensures that they are globally reusable.

  11.2.3.2. Attribute declaration data definitions 11.2.3.2.1. Attribute declaration has data definition [Rule 11-44] (REF, EXT) (Constraint)

    An attribute declaration MUST be a documented component.  

  11.2.3.2.2. Attribute declaration data definition is not empty [Rule 11-45] (REF, EXT) (Constraint)

    A data definition MUST NOT be empty.  

  11.2.3.3. Attribute declaration has type [Rule 11-46] (REF, EXT) (Constraint)

    A top-level attribute declaration MUST have a type.  

  Untyped XML Schema attributes allow arbitrary content, with no semantics. Attributes must have a type so that specific syntax and semantics will be provided.

  11.2.3.4. Prohibited attribute types

  There is no explicit prohibition on the use of xs:NOTATION as an attribute type, because it is prohibited by [XML Schema Datatypes].

  These types are only explicitly prohibited from attributes, not elements, because the case is covered by a general prohibition against elements having simple types.

  11.2.3.4.1. No attribute type of xs:ID [Rule 11-47] (REF, EXT) (Constraint)

    A schema component MUST NOT have an attribute <>type with a value of xs:ID.  

  11.2.3.4.2. No attribute type of xs:IDREF [Rule 11-48] (REF, EXT) (Constraint)

    A schema component MUST NOT have an attribute <>type with a value of xs:IDREF.  

  11.2.3.5. No attribute value constraints 11.2.3.5.1. No attribute default values [Rule 11-49] (REF, EXT) (Constraint)

    An element xs:attribute MUST NOT have an attribute <>default.  

  11.2.3.5.2. No attribute fixed values [Rule 11-50] (REF, EXT) (Constraint)

    An element xs:attribute MUST NOT have an attribute <>fixed.  

  11.2.4. Notation declaration 11.2.4.1. No use of element xs:notation [Rule 11-51] (REF, EXT) (Constraint)

    The schema SHALL NOT contain the element xs:notation.  

  11.3. Model group components 11.3.1. Model group

  Complex content definitions in XML Schema use model group schema components. These schema components, xs:all , xs:choice and xs:sequence , also called compositors, provide for ordering and selection of particles within a model group.

  XML Schema defines a particle as an occurrence of xs:element , xs:sequence , xs:choice , xs:any (wildcard) and xs:group (model group) within a content model. For example, an xs:sequence within an XML Schema complex type is a particle. An xs:element occurring within an xs:sequence is also a particle.

  11.3.1.1. Model group does not affect meaning [Rule 11-52] (EXT) (Interpretation)

  The use of model groups xs:all , xs:sequence , and xs:choice SHALL NOT define the semantics of an instance. The meaning of an element occurrance within an element occurrence SHALL be identical, regardless of the model group used to define a [schema component] .

  11.3.1.2. No xs:all [Rule 11-53] (REF, EXT) (Constraint)

    The schema SHALL NOT contain the element xs:all  

  The element xs:all provides a set of particles (e.g., elements) that may be included in an instance, in no particular order. This can greatly complicate processing and may be difficult to comprehend and satisfy.

  11.3.1.3. Sequence 11.3.1.3.1. xs:sequence must be child of xs:extension [Rule 11-54] (REF) (Constraint)

    An element xs:sequence must be a child of element xs:extension.  

  11.3.1.3.2. xs:sequence must be child of xs:extension or xs:restriction [Rule 11-55] (EXT) (Constraint)

    An element xs:sequence must be a child of element xs:extension or xs:restriction.  

  11.3.1.4. Choice 11.3.1.4.1. No xs:choice [Rule 11-56] (REF) (Constraint)

    The schema SHALL NOT contain the element xs:choice  

  The element xs:choice provides an exclusive set of particles, one of which may appear in an instance. This can greatly complicate processing and may be difficult to comprehend, satisfy, and reuse.

  The element xs:choice may be used in extension schemas, as it presents a simple way for a schema writer to represent a set of optional content.

  11.3.1.4.2. xs:choice must be child of xs:sequence [Rule 11-57] (EXT) (Constraint)

    An element xs:choice must be a child of element xs:sequence.  

  11.3.2. Particle 11.3.2.1. Sequence cardinality

  XML Schema allows each particle to specify cardinality (how many times the particle may appear in an instance). NIEM restricts the cardinality of xs:sequence particles to exactly one, to ensure that content model definitions are defined in as straightforward a manner as possible.

  Note also that element declarations acting as a particle (particles formed by xs:element ) may have any cardinality; they are not restricted by this rule. Should a user desire the behavior that would be obtained from the use of specific cardinality on sequences, she should define cardinality on specific elements.

  11.3.2.1.1. Sequence minimum cardinality [Rule 11-58] (REF, EXT) (Constraint)

    An element xs:sequence MUST either not have the attribute <>minOccurs, or that attribute MUST have a value of 1.  

  11.3.2.1.2. Sequence maximum cardinality [Rule 11-59] (REF, EXT) (Constraint)

    An element xs:sequence MUST either not have the attribute <>maxOccurs, or that attribute MUST have a value of 1.  

  11.3.2.2. Choice cardinality 11.3.2.2.1. Choice minimum cardinality [Rule 11-60] (EXT) (Constraint)

    An element xs:choice MUST either not have the attribute <>minOccurs, or that attribute MUST have a value of 1.  

  11.3.2.2.2. Choice maximum cardinality [Rule 11-61] (EXT) (Constraint)

    An element xs:choice MUST either not have the attribute <>maxOccurs, or that attribute MUST have a value of 1.  

  11.3.3. Attribute use 11.3.3.1. Attribute ref defined by conformant schemas [Rule 11-62] (REF, EXT) (Constraint)

     An attribute <>ref MUST have the target namespace or a namespace that is imported as conformant.  

  11.3.4. Attribute group 11.3.4.1. Only known attribute groups

  In NIEM-conformant schemas, use of attribute groups is restricted. The only attribute group that plays a part in NIEM-conformant schemas is structures:SimpleObjectAttributeGroup . This attribute group provides the attributes necessary for IDs, references, metadata, and relationship metadata.

  [Rule 11-63] (REF, EXT) (Constraint)

    An attribute group reference MUST be structures:SimpleObjectAttributeGroup or have the IC-ISM or IC-NTK namespace.  

  11.3.5. Wildcard 11.3.5.1. No use of xs:any [Rule 11-64] (REF, EXT) (Constraint)

    The schema SHALL NOT contain the element xs:any.  

  The xs:any particle (see Model Group Restrictions for an informative definition of particle) provides a wildcard that may carry arbitrary content. The particle xs:any may appear within constraint schemas, extension schemas, and exchange schemas.

  11.3.5.2. No use of xs:anyAttribute [Rule 11-65] (REF, EXT) (Constraint)

    The schema SHALL NOT contain the element xs:anyAttribute.  

  The xs:anyAttribute element provides a wildcard, where arbitrary attributes may appear. The element xs:anyAttribute may appear within constraint schemas or within other schemas that are not NIEM-conformant, but it is prohibited in NIEM- conformant schemas.

  11.4. Identity-constraint definition components

  XML Schema provides NIEM with the ability to apply uniqueness constraints to schema-validated content. These mechanisms, however, establish relationships in a way that is very difficult to understand, extend, and keep consisent through schema reuse.

  11.4.1. No use of xs:unique [Rule 11-66] (REF, EXT) (Constraint)

    The schema SHALL NOT contain the element xs:unique.  

  11.4.2. No use of xs:key [Rule 11-67] (REF, EXT) (Constraint)

    The schema SHALL NOT contain the element xs:key.  

  11.4.3. No use of xs:keyref [Rule 11-68] (REF, EXT) (Constraint)

    The schema SHALL NOT contain the element xs:keyref.  

  11.4.4. No use of xs:selector [Rule 11-69] (REF, EXT) (Constraint)

    The schema SHALL NOT contain the element xs:selector.  

  11.4.5. No use of xs:field [Rule 11-70] (REF, EXT) (Constraint)

    The schema SHALL NOT contain the element xs:field.  

  11.5. Group definition components 11.5.1. Model group definition 11.5.1.1. No use of xs:group [Rule 11-71] (REF, EXT) (Constraint)

    The schema MUST NOT contain the element xs:group.  

  NIEM does not allow groups of elements to be named other than as named complex types. A group in XML Schema creates a named entity that may be included in multiple types, and which consists of a sequence of or choice between element particles. The NIEM has not developed a semantic model for these components, and they are not integrated into NIEM’s design.

  11.5.2. Attribute group definition 11.5.2.1. No definition of attribute groups

  The only attribute groups used in NIEM-conformant schemas are structures:SimpleObjectAttributeGroup and attribute groups defined by the IC-ISM and IC-NTK schemas. Therefore, NIEM-conformant schemas do not define additional attribute groups.

  [Rule 11-72] (REF, EXT) (Constraint)

    The schema MUST NOT contain an attribute group definition schema component.  

  11.6. Annotation components 11.6.1. Comments are not recommended [Rule 11-73] (REF, EXT) (Constraint)

    An XML Comment is not an XML Schema annotation component; XML Comments SHOULD NOT appear in the schema.  

  Since XML comments are not associated with any specific XML Schema construct, there is no standard way to interpret comments. As such, comments should be reserved for internal use, and XML Schema annotations should be preferred for meaningful information about components. NIEM specifically defines how information should be encapsulated in NIEM-conformant schemas via xs:annotation elements.

  11.6.2. Documentation elements have no element children [Rule 11-74] (REF, EXT) (Constraint)

    A child of element xs:documentation MUST be text or an XML comment.  

  11.6.3. Application information annotations

  XML Schema provides special annotations for support of automatic processing. The XML Schema specification provides the element xs:appinfo to carry such content and does not specify what style of content they should carry. In NIEM, xs:appinfo elements carry structured XML content.

  11.6.3.1. Appinfo has elements [Rule 11-75] (REF, EXT) (Constraint)

    A child of element xs:appinfo MUST be an element or an XML comment.  

  Application information elements are intended for automatic processing; the meaning of an appinfo annotation is provided via elements.

  11.6.3.2. Appinfo child elements have namespaces [Rule 11-76] (REF, EXT) (Constraint)

    An element that is a child of xs:appinfo MUST have a namespace name.  

  The XML namespaces specification includes the concept of content not in a namespace. Use of elements without namespaces can lead to conflicting data definitions, and makes it difficult to identify relevant data definitions.

  11.6.3.3. Appinfo descendants are not XML Schema elements [Rule 11-77] (REF, EXT) (Constraint)

    An element with a namespace name of xs: MUST NOT have an ancestor element xs:appinfo.  

  NIEM-conformant schemas are designed to be very easily processed. Although uses of XML Schema elements as content of xs:appinfo elements could be contrived, it is not current practice and complicates the processing of XML elements by their namespaces and names. Forbidding the use of XML Schema elements outside valid uses of schema simplifies such processing.

  11.7. Schema as a whole

  The XML Schema language defines that the document element xs:schema may contain the optional attributes attributeFormDefault and elementFormDefault . The values of these attributes are not material to a NIEM-conformant schema, as each attribute and element defined by a NIEM-conformant schema must be defined at the toplevel and so is qualified its target namespace.

  11.7.1. Schema data definitions 11.7.1.1. Schema has data definition [Rule 11-78] (REF, EXT) (Constraint)

    A schema document element MUST be a documented component.  

  11.7.1.2. Schema data definition is not empty [Rule 11-79] (REF, EXT) (Constraint)

    A data definition MUST NOT be empty.  

  11.7.2. Define target namespace [Rule 11-80] (REF, EXT) (Constraint)

    The schema MUST define a target namespace.  

  Schemas without defined namespaces provide definitions that are ambiguous, in that they are not universally identifiable.

  11.7.3. Target namespace is absolute URI [Rule 11-81] (REF, EXT) (Constraint)

     as defined by RFC 3986.]]>  

  Absolute URIs are the only universally meaningful URIs. URIs include both URLs and URNs. Finding the target namespace using standard XML Base technology is complicated and not specified by XML Schema. Relative URIs are not universally identifiable, as they are context-specific.

  11.7.4. Schema document version

  It is very useful to be able to tell one version of a schema from another. Apart from the use of namespaces for versioning, it is sometimes necessary to release multiple versions of schema documents. Such use might include:

  • Subset schemas and constraint schemas
  • Error corrections or bug fixes
  • Documentation changes
  • Contact information updates

  In such cases, a different value for the version attribute implies a different version of the schema. No specific meaning is assigned to specific version identifiers.

  Note that some of the above uses for the version attribute are not employed in management of NIEM Core and domain schemas. An author of an application schema or exchange may use the version attribute for these purposes within their schemas.

  11.7.4.1. Schema must have version [Rule 11-82] (REF, EXT) (Constraint)

    An element xs:schema must have an attribute <>version.  

  11.7.4.2. Schema version must not be empty. [Rule 11-83] (REF, EXT) (Constraint)

    An attribute version owned by an element xs:schema must not be empty.  

  11.7.5. No disallowed substitutions [Rule 11-84] (REF) (Constraint)

    An element xs:schema MUST NOT have an attribute <>blockDefault.  

  11.7.6. No disallowed derivations [Rule 11-85] (REF) (Constraint)

    An element xs:schema MUST NOT have an attribute <>finalDefault.  

  11.8. Schema assembly 11.8.1. No use of xs:redefine [Rule 11-86] (REF, EXT) (Constraint)

    The schema MUST NOT contain the element xs:redefine.  

  The xs:redefine element allows an XML Schema document restrict and extend components from a namespace, in a separate schema document from the one that initially defined that namespace. Such redefinition introduces duplication of definitions, allowing multiple definitions to exist for components from a single namespace. This violates [Principle 8], that a single reference schema defines a NIEM-conformant namespace.

  11.8.2. No use of xs:include [Rule 11-87] (REF, EXT) (Constraint)

    The schema MUST NOT contain the element xs:include.  

  Element xs:include brings schemas defined in separate files into the current namespace. It breaks a namespace up into arbitrary partial schemas, which needlessly complicates the schema structure, making it harder to reuse and process, and also increases the likelihood of conflicting definitions.

  Inclusion of schemas that do not have namespaces also complicates schema understanding. This inclusion makes it difficult to find the realization of a specific schema artifact and create aliases for schema components that should be reused. Inclusion of schemas also violates [Principle 8], as it uses multiple schemas to construct a namespace.

  11.8.3. xs:import must have namespace [Rule 11-88] (REF, EXT) (Constraint)

    An element xs:import MUST have an attribute <>namespace.  

  An import that does not specify a namespace is enabling references to non-namespaced components. NIEM requires that all components have a defined namespace. It is important that the namespace declared by a schema be universally defined and unambiguous.

  12. NIEM XML Schema modeling

  This section focuses on building NIEM data models using XML schema. Whereas Section 11, Profile of XML Schema, above, addressed shrinking the XML Schema definition language to a smaller set of features, this section constructs new NIEM-specific features to address modeling and interoperability problems. This includes naming rules, categories of types, and augmentations.

  This section is organized by concept, rather than component type. This section is integrated with the following sections:

  • Section 13, NIEM XML Schema modeling rules, below, is organized by component type, and provides a majority of the constraint rules for schemas that define NIEM models.
  • Section 14, XML instance document rules, below, provides rules for XML documents that are instances of NIEM models.
  12.1. Categories of NIEM components

  The NIEM rules on categories of types, and other components, use the name of a type as the key indicator of the type's category. This make the rules much simpler than doing a deep examination of each type and its base types to identify its category. For example, for complex types, the names follow a pattern:

  • Name ends with AssociationType → type is an association type.
  • Name ends with MetadataType → type is a metadata type.
  • Name ends with AugmentationType → type is an augmentation type.
  • Otherwise → type is an object type.
  12.1.1. Classes of complex types [Rule 12-1] (REF, EXT) (Constraint)

  Within the schema, a complex type definition SHALL be one of the following:

  1. An object type.
  2. An association type.
  3. A metadata type.
  4. An augmentation type.

  This rule establishes the classes of NIEM complex types. It is a limited set, and each class has distinct semantics.

  12.1.2. Objects

  The categories of objects are covered by the following sections:

  • Section 12.1.2.1, General object types
  • Section 12.1.2.2, Roles
  • Section 12.1.2.3, External adapter types
  • Section 12.1.2.4, Code types
  • Section 12.1.2.5, Proxy types
  12.1.2.1. General object types [Definition: ]

  In a NIEM-conformant schema, an object type is a complex type definition, an instance of which asserts the existence of an object. An object type represents some kind of object: a thing with its own lifespan that has some existence. The object may or may not be a physical object. It may be a conceptual object.

  12.1.2.1.1. Object types with complex content 12.1.2.1.1.1. An object type with complex content is derived from an object type [Rule 12-2] (REF, EXT) (Constraint)

    An object type with complex content MUST be derived from structures:Object type or from another object type.  

  12.1.2.2. Roles

  Indicate that a subset of role type could omit the RoleOf element, in which case an instance of the role type is just a regular object.

  NIEM differentiates between an object and a role of the object. The term role is used here to mean a function or part played by some object. The simplest way to represent a role of an object is to use an element. The following element definition models the role of a person who undergoes an assessment:

  Figure 12-1: An element definition that constitutes a role without the use of a role type

    A person who undergoes an assessment.  

  In many cases, there is a further need to represent characteristics and additional information associated with a role of an object. In such cases, the above element is insufficient. When a role must be modeled with additional information, a [role type] is called for.

  For example, when a person is a driver involved in an automotive crash, that person has a particular role in the crash, which is modeled by the element j:CrashDriver .

  Figure 12-2: Element j:CrashDriver , modeling the role of a driver in a crash

    A motor vehicle driver involved into a traffic accident.  

  There is more information associated with this role of the driver than just his identity as a person. Information associated with this role include the drivers license, contributing circumstances, distractions, and other properties. These characteristics are modeled as shown in the following figure. The role is modeled as a [role type] :

  Figure 12-3: Role type j:CrashDriverType , modeling a driver involved in a crash

    A data type for a motor vehicle driver involved in a traffic accident.              

  The term [role type] has a normative definition:

  [Definition: ]

  A role type is an [object type] that represents a particular function, purpose, usage, or role of one or more objects of its base type.

  A role type defines an object that carries information associated with an object playing a role. A role type is used instead of the base type (in this case, nc:PersonType ). The role type holds information that is specific to the role, but is not specific to the context or the base object (the object that plays the role). Developers of NIEM-conformant schemas should create and use role types whenever they have nonpersistent information specific to a base object's function. Such information generally expires when the base object is no longer playing the role. Information that is persistent to the base object probably does not belong in a role type.

  [Definition: ]

  A RoleOf element is an [element declaration schema component] that

  • is defined by a [conformant reference schema document] or a [conformant extension schema document] , and
  • has a that begins with RoleOf .

  A RoleOf element represents a base type for a [role type] .

  Figure 12-4: Declaration of RoleOf element nc:RoleOfPerson

    A person of whom the role object is a function.  

  Here is an example of the j:CrashPerson role type used in an instance:

  Figure 12-5: An XML instance of a role type

    A10 S16   1966-06-06  John Doe  

  Note that the value of the j:CrashPerson element was indicated above using a reference; it could have been shown as a content element, instead.

  12.1.2.2.1. RoleOf element type is an object type [Rule 12-3] (REF, EXT) (Constraint)

    The type definition of a RoleOf element SHALL be an object type.  

  Note that by [Rule 13-14], below, the element’s type must be from a conformant namespace.

  12.1.2.2.2. Only object types have RoleOf element [Rule 12-4] (REF, EXT) (Constraint)

    A complex type that includes a RoleOf element in its content model SHALL be an object type.  

  Note that [RoleOf element] and [object type] are defined terms.

  12.1.2.2.3. RoleOf element indicates the base types of a role type [Rule 12-5] (REF, EXT) (Interpretation)

  For every [element declaration schema component] that has a local name that begins with the string RoleOf SHALL represent a base type, of which the containing type represents a role.

  12.1.2.2.4. Instance of RoleOf element indicates a role object [Rule 12-6] (INS) (Interpretation)
  • The value of the parent element is a role object.
  • The value of the child element is a base object of the role object.

  An instance of a [RoleOf element] indicates the base object of a role. The prefix RoleOf on the element ensures that a role object may be distinguished from other objects and that its link to the base object is also distinguishable from the additional properties that are characteristics or other data of the role.

  NIEM does not require that there be only one [RoleOf element] within a single type, nor does it require that a particular role object have only a single occurrence of a [RoleOf element] . However, the use of multiple [RoleOf elements] may not make sense in all cases. Many exchanges may restrict [RoleOf elements] to a single occurrence within a type.

  12.1.2.3. External adapter types 12.1.2.3.1. External adapter type has complex content [Rule 12-7] (REF) (Constraint)

    An external adapter type definition must be a complex type definition with complex content.  

  12.1.2.3.2. External adapter type uses extension [Rule 12-8] (REF) (Constraint)

    An external adapter type definition must be use the extension derivation method.  

  12.1.2.3.3. External adapter type extends structures:ObjectType [Rule 12-9] (REF) (Constraint)

    An external adapter type definition MUST extend structures:ObjectType.  

  12.1.2.3.4. External adapter types use sequence [Rule 12-10] (REF) (Constraint)

    An external adapter type must use sequence as its top-level compositor.  

  12.1.2.4. Code types [Definition: ]

  A code type is a NIEM object type with a content model that is constrained by one or more enumeration facets.

  These types represent lists of values, each of which has a known meaning beyond the text representation. These values may be meaningful text or may be a string of alphanumeric identifiers that represent abbreviations for literals.

  12.1.2.4.1. The name of a code type ends in CodeType [Rule 12-11] (REF, EXT) (Constraint)

      A complex type with a [base type] of a code type or code simple type MUST have a name that ends in 'CodeType'.  

  Using the qualifier Code (e.g. CodeType , CodeSimpleType ) immediately identifies a type as representing a fixed list of codes. These types may be handled in specific ways, as lists of codes are expected to have their own lifecycles, including versions and periodic updates. Codes may also have responsible authorities behind them who provide concrete semantic bindings for the code values.

  12.1.2.5. Proxy types 12.1.3. Associations 12.1.4. Augmentations
  • Section 12.1.4.1, Augmentable types
  • Section 12.1.4.2, Augmentation point element declarations
  • Section 12.1.4.3, Augmentation point element use
  • Section 12.1.4.4, Augmentation types
  • Section 12.1.4.5, Augmentation element declarations

  Builders of domains and extensions to NIEM distribution schemas need to be able to define extensions to types. However, extension of types by multiple domain schemas and extension schemas proves problematic, as it results in multiple extensions of a single type. XML Schema does not provide for multiple types of an instance;consequently, such a method results in duplication of base type content and a need to resolve same-as relationships between the instances of the various derived types.

  Instead, it is preferable for domains and extensions to provide augmentations. These are reusable types and elements of those types, which may be added to an object class, in a single extended type, by the author of a NIEM-conformant schema. This avoids the problem of multiple extended types but allows domains and extensions to define reusable extensions.

  Augmentation types such as j:PersonAugmentationType , where j is the prefix for the NIEM Justice domain, http://release.niem.gov/niem/domains/jxdm/5.0/ , exist to extend NIEM Core types such as nc:PersonType without creating a new specialized object within the model. Augmentation types are never applied within the model to the types they are designed to augment. Doing so would restrict reusing and combining these augmentations.

  Instead, augmentation should be applied within IEPDs. So in an IEPD (NOT within NIEM), base nc:PersonType may be extended, for example, as my-iepd:PersonType by adding elements a:PersonAugmentation and b:PersonAugmentation . As a result, my-iepd:PersonType will contain all the properties in nc:PersonType plus the properties in both of the elements a:PersonAugmentation and b:PersonAugmentation , which, in turn, each contain their respective sets of subelements.

  All NIEM augmentation types extend the abstract type structures:AugmentationType . Therefore, all augmentation types automatically contain the attributes structures:id and structures:metadata for referencing and metadata, respectively. NIEM also provides the abstract element structures:Augmentation (of type structures:AugmentationType ) as the common substitution group head for all augmentation elements. An augmentation element placed into this substitution group can be used in an instance wherever structures:Augmentation occurs in the corresponding IEPD schema. The user must follow NIEM naming conventions for augmentation component names and must place new augmentation elements into the structures:Augmentation substitution group. Further, if an augmentation element cannot be applied to all types in the model, then the user must document those types that the new augmentation element can be applied to using the appinfo:AppliesTo element.

  [Definition: ]

  An augmentation of a NIEM-conformant object type is a block of additional data added to an object type to carry additional data beyond that of the original object definition.

  [Rule 12-12] (REF, EXT)

  An augmentation type:

  1. SHALL be transitively derived from structures:AugmentationType .
  2. SHALL contain elements that represent properties to be applied to a base type.

  Rationale

  A base type is the type to which an augmentation is to be applied. An augmentation may be applied to any number of types. Base types are assigned by augmentation elements.

  [Rule 12-13] (REF, EXT)

  Within the schema, an augmentation element definition:

  1. SHALL have a type that is an augmentation type.
  2. SHALL use the substitutionGroup attribute such that it is transitively substitutable for the element structures:Augmentation .

  An element that is not an augmentation element SHALL NOT meet either of the above criteria.

  Rationale

  An augmentation is trivially identifiable as such. The use of the common structures:Augmentation element allows message builders to optionally delay specifying augmentations to be applied to a type until runtime.

  [Rule 12-14] (REF, EXT)

  Within the schema, an element definition for an augmentation element MAY contain one or more instances of the element appinfo:AppliesTo as application information to specify types to which the augmentation element applies.

  [Rule 12-15] (REF, EXT)

  Within the schema, an element definition for an augmentation element that does not contain any instances of the element appinfo:AppliesTo MAY be applied to any object or association type.

  Rationale

  These rules allow schema builders to establish applicability for augmentations. An augmentation may be applicable to specific types.

  Users who wish to apply an augmentation type to a given object type may do so by creating a new augmentation element, applicable to the object type.

  12.1.4.1. Augmentable types [Definition: ]

  An augmentable type is any [complex type definition] that meets all of these criteria:

  • It is defined by either a [conformant reference schema document] or by an [conformant extension schema document] .
  • It is either:
    • an [association type] , or
    • an [object type] that has complex content and is not an external adapter type.
    12.1.4.1.1. Augmentable type has augmentation point [Rule 12-16] (REF) (Constraint)

       An augmentable type MUST contain exactly one reference its augmentation point element.  

    12.1.4.2. Augmentation point element declarations 12.1.4.2.1. An augmentation point corresponds to an augmentable type [Rule 12-17] (REF, EXT) (Constraint)

       A schema document defining an augmentation point element MUST also define a corresponding [augmentable type].  

    12.1.4.2.2. An augmentation point has no type [Rule 12-18] (REF, EXT) (Constraint)

      An augmentation point element MUST have no type.  

    There is no rule requiring that the augmentation element is abstract, as that is implied by the lack of @type.

    12.1.4.2.3. An augmentation point has no substitution group [Rule 12-19] (REF, EXT) (Constraint)

      An augmentation point element MUST have no substitution group.  

    12.1.4.3. Augmentation point element use 12.1.4.3.1. Augmentation element may only be referenced by its type [Rule 12-20] (REF, EXT) (Constraint)

      An augmentation element MUST only be referenced by its corresponding type.   

    12.1.4.3.2. Augmentation reference is optional [Rule 12-21] (REF) (Constraint)

      An augmentation element particle MUST have attribute minOccurs equal to 0.  

    12.1.4.3.3. Augmentation reference is unbounded [Rule 12-22] (REF) (Constraint)

      An augmentation element particle MUST have attribute maxOccurs set to unbounded.  

    12.1.4.3.4. Augmentation reference must be last particle [Rule 12-23] (REF, EXT) (Constraint)

      An augmentation element particle MUST be the last element atom in its content model.  

    12.1.4.4. Augmentation types [Definition: ]

    An augmentation type is a complex type that provides a reusable block of data that may be added to object types or association types.

    12.1.4.4.1. Augmentation type name ends in AugmentationType [Rule 12-24] (REF, EXT) (Constraint)

    A [schema component] has a name that ends in AugmentationType if and only if it is a [complex type definition] that defines an [augmentation type] .

    12.1.4.4.2. Augmentation type derived from augmentation type [Rule 12-25] (REF, EXT) (Constraint)

      The [base type definition] of an [augmentation type] MUST be either structures:AugmentationType or an [augmentation type].  

    12.1.4.4.3. Augmentation types are derived from augmentation types [Rule 12-26] (REF, EXT) (Constraint)

        A type MUST have a augmentation type name if an only if it is derived from a augmentation type.  

    Using the qualifier Augmentation immediately identifies a type as representing an augmentation.

    12.1.4.5. Augmentation element declarations 12.1.4.5.1. Augmentation element is an element of an augmentation type [Rule 12-27] (REF, EXT) (Constraint)

      An element MUST have a name that ends in 'Augmentation' if and only if it has a type that is a augmentation type.  

    Using the qualifier Augmentation immediately identifies an element as representing an augmentation.

    12.2. Naming rules

    This section outlines the rules used to create names for NIEM data components previously discussed in this document. Data component names must be understood easily both by humans and by machine processes. These rules improve name consistency by restricting characters, terms, and syntax that could otherwise allow too much variety and potential ambiguity. These rules also improve readability of names for humans, facilitate parsing of individual terms that compose names, and support various automated tasks associated with dictionary and controlled vocabulary maintenance.

    12.2.1. Extension of XSD namespace simple types [Rule 12-28] (REF, EXT)

    Within the schema, a complex type that is a direct extension of a simple type from the XML Schema namespace simple type MAY use the same local name as the simple type if and only if the extension adds no content other than the attribute group structures:SimpleObjectAttributeGroup .

    Rationale

    It is useful to build complex type bases for further extension. The NIEM distribution proxy schema xsd.xsd provides complex type bases for some of the simple types in the XML Schema namespace. However, the complex types in this proxy schema reuse the local names of the simple types they extend, even though the simple type names may not be NIEM-conformant. Requiring name changes for those NIEM-provided complex type bases would work against user understanding, for those already familiar with the names of the XML Schema namespace simple types being extended.

    12.2.2. Usage of English [Rule 12-29] (REF, EXT)

    The name of any XML Schema component defined by the schema SHALL be composed of words from the English language, using the prevalent U.S. spelling, as provided by [OED].

    Rationale

    The English language has many spelling variations for the same word. For example, American English program has a corresponding British spelling programme. This variation has the potential to cause interoperability problems when XML components are exchanged because of the different names used by the same elements. Providing users with a dictionary standard for spelling will mitigate this potential interoperability issue.

    12.2.3. Characters in names [Rule 12-30] (REF, EXT)

    The name of any XML Schema component defined by the schema SHALL contain only the following characters:

    • Upper-case letters (' A '-' Z ').
    • Lower-case letters (' a '-' z ').
    • Digits (' 0 '-' 9 ').
    • Hyphen (' - ').

    Other characters, such as the underscore ( _ ) character and the period ( . ) character SHALL NOT appear in component names in NIEM-conformant schemas.

    [Rule 12-31] (REF, EXT)

    The hyphen character ( - ) MAY appear in component names only when used as a separator between parts of a single word, phrase, or value, which would otherwise be incomprehensible without the use of a separator.

    Rationale

    Names of standards and specifications, in particular, tend to consist of series of discrete numbers. Such names require some explicit separator to keep the values from running together. The separator used within NIEM is the hyphen.

    Names of NIEM components follow the rules of XML Schema, by [Rule 5-3]. NIEM components also must follow the rules specified for each type of XML Schema component.

    12.2.4. Character case [Rule 12-32] (REF, EXT)

    Within the schema, any attribute declaration SHALL have a name that begins with a lower-case letter (' a '-' z ').

    [Rule 12-33] (REF, EXT)

    Within the schema, any XML Schema component other than an attribute declaration SHALL have a name that begins with an upper-case letter (' A '-' Z ').

    Camel case is the practice of writing compound words or phrases in which the words are joined without spaces and are capitalized within the compound words. [Wikipedia]

    [Rule 12-34] (REF, EXT)

    The name of any XML Schema component defined by the schema SHALL use the camel case formatting convention.

    Rationale

    The foregoing rules establish lowerCamelCase for all NIEM components that are XML attributes and UpperCamelCase for all NIEM components that are types, elements, or groups.

    12.2.5. Use of acronyms and abbreviations

    Acronyms and abbreviations have the ability to improve readability and comprehensibility of large, complex, or frequently used terms. They also obscure meaning and impair understanding when their definitions are not clear or when they are used injudiciously. They should be used with great care. Acronyms and abbreviations that are used must be documented and used consistently.

    [Rule 12-35] (REF, EXT)

    The schema MUST consistently use approved acronyms, abbreviations, and word truncations within defined names. The approved shortened forms are defined in Table 12-1, Abbreviations used in NIEM core names.

    remove this table

    Table 12-1: Abbreviations used in NIEM core names

    Abbreviation	Full Meaning
    ANSI	American National Standards Institute
    CMV	Commercial Motor Vehicle
    DEA	Drug Enforcement Agency
    DNA	Deoxyribonucleic Acid
    FGI	Foreign Government Information
    FIPS	Federal Information Processing Standard
    IC	Intelligence Community
    ID	Identifier
    IP	Internet Protocol
    ISO	International Standards Organization
    LIS	NCIC code list for license state
    LSTA	NCIC code list for state/country index
    MCO	Manufacturer’s Certificate of Origin
    MGRS	Military Grid Reference System
    MSRP	Manufacturer’s Suggested Retail Price
    NANP	North American Numbering Plan
    NCIC	National Crime Information Center
    NCTC	National Counter Terrorist Center
    NIBRS	National Incident Based Reporting System
    NLETS	The International Justice & Public Safety Information Sharing Network (formerly known as the National Law Enforcement Teletype System)
    ORI	Organization Identifier (Orion)
    RES	NCIC code list for registration state for boat registrations
    RF	Radio Frequency
    SIM	Subscriber Identity Module
    SSN	Social security number
    TYP	NCIC code list for gun type
    TYPO	NCIC code list for ORI type
    URI	Uniform Resource Identifier
    US	United States
    UTM	Universal Transverse Mercator
    VIN	Vehicle Identification Number
    VINA	Vehicle Identification Number Analysis

    Rationale

    Consistent, controlled, and documented abridged terms that are used frequently and/or tend to be lengthy can support readability, clarity, and reduction of name length.

    12.2.6. Word forms [Rule 12-36] (REF, EXT)

    A noun used as a term in the name of an XML Schema component MUST be in singular form unless the concept itself is plural.

    [Rule 12-37] (REF, EXT)

    A verb used as a term in the name of an XML Schema component MUST be used in the present tense unless the concept itself is past tense.

    [Rule 12-38] (REF, EXT)

    Articles, conjunctions, and prepositions SHALL NOT be used in NIEM component names except where they are required for clarity or by standard convention.

    Rationale

    Articles (e.g., a, an, the), conjunctions (e.g., and, or, but), and prepositions (e.g., at, by, for, from, in, of, to) are all disallowed in NIEM component names, unless they are required. For example, PowerOfAttorneyCode requires the preposition. These rules constrain slight variations in word forms and types to improve consistency and reduce potentially ambiguous or confusing component names.

    12.2.7. Name generation

    Elements in NIEM-conformant schemas are given names that follow a specific pattern. This pattern comes from [ISO 11179-5].

    [Rule 12-39] (REF, EXT)

    Except as specified elsewhere in this document, any element or attribute defined within the schema SHALL have a name that takes the form:

    • Object-class qualifier terms (0 or more).
    • An object class term (1).
    • Property qualifier terms (0 or more).
    • A property term (1).
    • Representation qualifier terms (0 or more).
    • A representation term (1).

    Rationale

    Consistent naming rules are helpful for users who wish to understand components with which they are unfamiliar, as well as for users to find components with known semantics. This rule establishes the basic structure for an element or attribute name, in line with the rules for names under [ISO 11179-5]. Note that many elements with complex type should not have a representation term.

    12.2.8. Object-class term

    The NIEM adopts an object-oriented approach to representation of data. Object classes represent what [ISO 11179-5] refers to as things of interest in a universe of discourse that may be found in a model of that universe. An object class or object term is a word that represents a class of real-world entities or concepts. An object-class term describes the applicable context for a NIEM component.

    [Rule 12-40] (REF, EXT)

    The object-class term of a NIEM component SHALL consist of a term identifying a category of concrete concepts or entities.

    Rationale

    The object-class term indicates the object category that this data component describes or represents. This term provides valuable context and narrows the scope of the component to an actual class of things or concepts.

    Example

    Concept term: Activity

    Entity term: Vehicle

    12.2.9. Property term

    Objects or concepts are usually described in terms of their characteristic properties, data attributes, or constituent subparts. Most objects can be described by several characteristics. Therefore, a property term in the name of a data component represents a characteristic or subpartof an object class and generally describes the essence of that data component.

    [Rule 12-41] (REF, EXT)

    A property term SHALL describe or represent a characteristic or subpart of an entity or concept.

    Rationale

    The property term describes the central meaning of the data component.

    12.2.10. Qualifier terms

    Qualifier terms modify object, property, representation, or other qualifier terms to increase semantic precision and reduce ambiguity. Qualifier terms may precede or succeed the terms they modify. The goal for the placement of qualifier terms is to generally follow the rules of ordinary English while maintaining clarity.

    [Rule 12-42] (REF, EXT)

    Multiple qualifier terms MAY be used within a component name as necessary to ensure clarity and uniqueness within its namespace and usage context.

    [Rule 12-43] (REF, EXT)

    The number of qualifier terms SHOULD be limited to the absolute minimum required to make the component name unique and understandable.

    [Rule 12-44] (REF, EXT)

    The order of qualifiers SHALL NOT be used to differentiate names.

    Rationale

    Very large vocabularies may have many similar and closely related properties and concepts. The use of object, property, and representation terms alone is often not sufficient to construct meaningful names that can uniquely distinguish such components. Qualifier terms provide additional context to resolve these subtleties. However, swapping the order of qualifiers rarely (if ever) changes meaning; qualifier ordering is no substitute for meaningful terms.

    12.2.11. Representation terms

    The representation terms for a component name serve several purposes in NIEM:

    1. It can indicate the style of component. For example, types are clearly labeled with the representation term Type .
    2. It helps prevent name conflicts and confusion. For example, elements and types may not be given the same name.
    3. It indicates the nature of the value carried by element. Labeling elements and attributes with a notional indicator of the content eases discovery and comprehension.
    [Rule 12-45] (REF, EXT)

    If any word in the representation term is redundant with any word in the property term, one occurrence SHOULD be deleted.

    Rationale

    This rule, carried over from 11179, is designed to prevent repeating terms unnecessarily within component names. For example, this rule allows designers to avoid naming an element PersonFirstNameName.

    The valid value set of a data element or value domain is described by the representation term. NIEM uses a standard set of representation terms in the representation portion of a NIEM-conformant component name. Table 13-1, Representation terms, below, lists the primary representation terms and a definition for the concept associated with the use of that term. The table also lists secondary representation terms that may represent more specific uses of the concept associated with the primary representation term.

    [Rule 12-46] (REF, EXT)

    Within the schema, the name of an element declaration that is of simple content MUST use a representation term found in Table 13-1, Representation terms.

    [Rule 12-47] (REF, EXT)

    Within the schema, the name of an element declaration that is of complex content, and that corresponds to a concept listed in Table 13-1, Representation terms, MUST use a representation term from that table.

    [Rule 12-48] (REF, EXT)

    Within the schema, the name of an element declaration that is of complex content and that does not correspond to a concept listed in Table 13-1, Representation terms MUST NOT use a representation term.

    Rationale

    An element that represents a value listed in the table should have a representation term. It should do so even if its type is complex with multiple parts. For example, a type with multiple fields may represent a sound binary, a date, or a name.

    13. NIEM XML Schema modeling rules

    This section focuses on building NIEM data models using XML schema. Whereas Section 11, Profile of XML Schema, above, addressed shrinking the XML Schema definition language to a smaller set of features, this section constructs new NIEM-specific features to address modeling and interoperability problems. This includes naming rules, categories of types, and augmentations.

    13.1. Type definition components 13.1.1. Name of type ends in Type [Rule 13-1] (REF, EXT) (Constraint)

      The name of a proxy type does not end in "Type".  A type definition schema component that does not define a proxy type MUST have a name that ends in "Type".  

    Use of the representation term Type immediately identifies XML types in a NIEM-conformant schema and prevents naming collisions with corresponding XML elements and attributes. The exception for proxy types ensures that simple NIEM-compatible uses of base XML Schema types are familiar to people with XML Schema experience.

    Note that the first sch:rule and subsequent sch:report serve to provide an exception to the rule for proxy types. It does not establish a constraint on the data.

    13.1.2. Name of type is in upper camel case

    Revise rule name to identify the exception for proxy types.

    [Rule 13-2] (REF, EXT) (Constraint)

      The name of a proxy type is not upper camel case.  A type definition schema component that does not define a proxy type MUST be in upper camel case.  

    Note that the first sch:rule and q subsequent sch:report serve to provide an exception to the rule for proxy types. It does not establish a constraint on the data.

    13.1.3. Type definition hierarchy 13.1.3.1. Base type definition defined by conformant schema [Rule 13-3] (REF, EXT) (Constraint)

       The [base type definition] of a [type definition] MUST have the target namespace or the XML Schema namespace or a namespace that is imported as conformant.  

    13.1.4. Simple type definition 13.1.4.1. Name of simple type ends in SimpleType [Rule 13-4] (REF, EXT) (Constraint)

      A simple type definition schema component MUST have a name that ends in "SimpleType".  

    Specific uses of type definitions have similar syntax but very different effects on data definitions. Schemas that clearly identify complex and simple type definitions are easier to understand without tool support. This rule ensures that names of simple types end in SimpleType .

    13.1.4.2. Name of simple type is upper camel case [Rule 13-5] (REF, EXT) (Constraint)

      The name of a simple type definition schema component MUST be upper camel case.  

    13.1.4.3. Derivation by list 13.1.4.3.1. List item type defined by conformant schemas [Rule 13-6] (REF, EXT) (Constraint)

       The item type of a list simple type definition MUST have a target namespace equal to the target namespace of the XML Schema document within which it is defined, or a namespace that is imported as conformant by the schema document within which it is defined.  

    13.1.4.4. Derivation by union 13.1.4.4.1. Union member types defined by conformant schemas [Rule 13-7] (REF, EXT) (Constraint)

      Every member type of a union simple type definition MUST have a target namespace that is equal to either the target namespace of the XML Schema document within which it is defined or a namespace that is imported as conformant by the schema document within which it is defined.  

    13.1.4.5. Code simple types [Definition: ]

    A code simple type is a simple type definition schema component that is constrained by one or more enumeration facets.

    These types represent lists of values, each of which has a known meaning beyond the text representation. These values may be meaningful text or may be a string of alphanumeric identifiers that represent abbreviations for literals.

    13.1.4.5.1. Name of a code simple type has standard suffix [Rule 13-8] (REF, EXT) (Constraint)

      A simple type definition schema component that has an enumeration facet or that is derived from a code type MUST have a name that ends in "CodeSimpleType".  

    13.1.4.5.2. Code simple type has enumerations [Rule 13-9] (REF, EXT) (Constraint)

      A code simple type MUST be derived from a code simple type or have an enumeration facet.  

    Using the qualifier Code (e.g. CodeType , CodeSimpleType ) immediately identifies a type as representing a fixed list of codes. These types may be handled in specific ways, as lists of codes are expected to have their own lifecycles, including versions and periodic updates. Codes may also have responsible authorities behind them who provide concrete semantic bindings for the code values.

    13.1.5. Complex types 13.1.5.1. Association types 13.1.5.1.1. Association types are derived from association types [Rule 13-10] (REF, EXT) (Constraint)

        A type MUST have a association type name if an only if it is derived from a association type.  

    Using the qualifier Association immediately identifies a type as representing an association.

    13.1.5.2. Metadata types 13.1.5.2.1. Metadata types are derived from metadata types [Rule 13-11] (REF, EXT) (Constraint)

        A type MUST have a metadata type name if an only if it is derived from a metadata type.  

    Using the qualifier Metadata immediately identifies a type as representing metadata.

    13.2. Declaration components 13.2.1. Element declarations 13.2.1.1. Element name is upper camel case [Rule 13-12] (REF, EXT) (Constraint)

      The name of an element declaration schema component MUST be upper camel case.  

    13.2.1.2. Element type does not have a simple type name [Rule 13-13] (REF, EXT) (Constraint)

      The of an [element declaration] MUST NOT have a that ends in 'SimpleType'.  

    13.2.1.3. Element type is from conformant namespace [Rule 13-14] (REF, EXT) (Constraint)

      The of an MUST have a that is the target namesapce, or one that is imported as conformant.  

    13.2.1.4. Name of element that ends in "Abstract" must be abstract [Rule 13-15] (REF, EXT) (Constraint)

    is there more normative terminology in the rule text here?

      An element with a name that ends in 'Abstract' MUST be abstract.  

    13.2.1.5. Name of element that ends in "Representation" must be abstract [Rule 13-16] (REF, EXT) (Constraint)

      An element with a name that ends in 'Representation' MUST be abstract.  

    13.2.1.6. Object element declarations Table 13-1: Representation terms

    Primary Representation Term	Secondary Representation Term	Definition
    Amount	-	A number of monetary units specified in a currency where the unit of currency is explicit or implied.
    BinaryObject	-	A set of finite-length sequences of binary octets.
    Graphic	A diagram, graph, mathematical curves, or similar representation
    Picture	A visual representation of a person, object, or scene
    Sound	A representation for audio
    Video	A motion picture representation; may include audio encoded within
    Code	A character string (i.e.,letters, figures,and symbols) that for brevity, language independence, or precision represents a definitive value of an attribute.
    DateTime	A particular point in the progression of time together with relevant supplementary information.
    Date	A particular day, month, and year in the Gregorian calendar.
    Time	A particular point in the progression of time within an unspecified 24-hour day.
    Duration	An amount of time; the length of a time span.
    ID	A character string to identify and distinguish uniquely one instance of an object in an identification scheme from all other objects in the same scheme together with relevant supplementary information.
    URI	A string of characters used to identify (or name) a resource. The main purpose of this identifier is to enable interaction with representations of the resource over a network, typically the World Wide Web, using specific protocols. A URI is either a Uniform Resource Locator (URL) or a Uniform Resource Name (URN). The specific syntax for each is defined by [RFC 3986].
    Indicator	A list of two mutually exclusive Boolean values that express the only possible states of a property.
    Measure	A numeric value determined by measuring an object along with the specified unit of measure.
    Numeric	Numeric information that is assigned or is determined by calculation, counting, or sequencing. It does not require a unit of quantity or unit of measure.
    Value	A result of a calculation.
    Rate	A representation of a ratio where the two units are not included.
    Percent	A representation of a ratio in which the two units are the same.
    Quantity	A counted number of nonmonetary units possibly including fractions.
    Text	-	A character string (i.e., a finite sequence of characters) generally in the form of words of a language.
    Name	A word or phrase that constitutes the distinctive designation of a person, place, thing, or concept.
    List	A sequence of values. This representation term is used in tandem with another of the listed representation terms.

    13.2.1.6.1. Elements with simple content use representation term [Rule 13-17] (REF, EXT, SET) (Constraint)

        the name of an element declaration that is of simple content MUST use a representation term.  

    13.2.1.7. Association element declarations 13.2.1.7.1. Association element is an element of an association type [Rule 13-18] (REF, EXT) (Constraint)

      An element MUST have a name that ends in 'Association' if and only if it has a type that is a association type.  

    Using the qualifier Association immediately identifies an element as representing an association.

    13.2.1.8. Metadata element declarations [Definition: ]

    Within a NIEM-conformant schema, a metadata element is an element with a type that is a metadata type.

    There are limitations on the meaning of a metadata element in an instance; it does not establish existence of an object, nor is it a property of its containing object.

    13.2.1.8.1. Metadata element is an element of a metadata type [Rule 13-19] (REF, EXT) (Constraint)

      An element MUST have a name that ends in 'Metadata' if and only if it has a type that is a metadata type.  

    Using the qualifier Metadata immediately identifies an element as representing metadata.

    13.2.2. Element substitution group 13.2.2.1. Element substitution group defined by conformant schemas [Rule 13-20] (REF, EXT) (Constraint)

       An element substitution group MUST have either the target namespace or a namespace that is imported as conformant.  

    13.2.3. Attribute declaration 13.2.3.1. Attribute type defined by conformant schemas [Rule 13-21] (REF, EXT) (Constraint)

       The type of an attribute declaration MUST have the target namespace or the XML Schema namespace or a namespace that is imported as conformant.  

    13.2.3.2. Attribute name uses representation term [Rule 13-22] (REF, EXT) (Constraint)

      An attribute name MUST end with a representation term.  

    13.2.4. Notation declaration 13.3. Model group components 13.3.1. Model group 13.3.2. Particle 13.3.2.1. Element use 13.3.2.1.1. Element ref in external type defined by external schemas [Rule 13-23] (REF, EXT) (Constraint)

       An element reference that appears within an external adapter type MUST have a target namespace that is imported as external.  

    13.3.2.1.2. Element reference defined by conformant schemas [Rule 13-24] (REF, EXT) (Constraint)

       An element reference MUST be to a component that has a namespace that is either the target namespace of the [schema document] in which it appears, or which is imported as conformant by that [schema document].  

    13.3.3. Attribute use 13.3.4. Wildcard 13.4. Annotation components 13.4.1. Data definition follows 11179-4 requirements [Rule 13-25] (REF, EXT) (Constraint)

    Each [data definition] SHALL conform to the requirements for data definitions provided by [ISO 11179-4] §5.2.

    13.4.2. Data definition follows 11179-4 recommendations [Rule 13-26] (REF, EXT) (Constraint)

    Each [data definition] SHOULD conform to the recommendations for data definitions provided by [ISO 11179-4] §5.3.

    13.5. Schema assembly 13.5.1. Reference schemas import reference schemas. [Rule 13-27] (SET) (Constraint)

      A namespace imported as conformant from a reference schema document MUST identify a reference schema document.  

    13.5.2. Special namespaces are imported as conformant 13.5.2.1. Structures imported as conformant [Rule 13-28] (REF, EXT) (Constraint)

      The structures namespace MUST be imported as conformant.   

    13.5.2.2. Schema for XML imported as conformant [Rule 13-29] (REF, EXT) (Constraint)

      The namespace for XML MUST be imported as conformant.   

    13.5.2.3. Schema for IC-ISM imported as conformant [Rule 13-30] (REF, EXT) (Constraint)

      The namespace for IC-ISM MUST be imported as conformant.   

    13.5.2.4. Schema for IC-NTK imported as conformant [Rule 13-31] (REF, EXT) (Constraint)

      The namespace for IC-NTK MUST be imported as conformant.   

    13.5.3. Each namespace may have only a single root schema in a schema set. [Rule 13-32] (SET) (Constraint)

      A namespace may appear as a root schema in a schema set only once.  

    13.6. Schema assembly 13.6.1. Consistently marked namespace imports

    XML Schemas allows multiple xs:import elements for the same namespace, which allows for multiple sets of annotations and schema locations.

    [Rule 13-33] (REF, EXT) (Constraint)

         All xs:import elements that have the same namespace MUST have the same conformance marking via appinfo:conformantIndicator.  

    14. XML instance document rules

    This specification attempts to restrict XML instance data as little as possible while still maintaining interoperability. Section 2.6, NIEM-Conformant XML Documents and Elements, defines terminology for NIEM-conformance and XML documents.

    The NIEM does not require a specific encoding or specific requirements for the XML prologue, except as specified by [XML].

    14.1. Instance validation [Rule 14-1] (INS)

    The XML document MUST be schema-valid, assessed with reference to the schema composed of the reference schemas, extension schemas, exchange schemas, utility schemas, and external schemas for the relevant namespaces.

    Rationale

    The schemas that define the exchange must be authoritative. Each is the reference schema, extension schema, or exchange schema for the namespace it defines. Application developers may use other schemas for various purposes, but for the purposes of determining conformance, the authoritative schemas are relevant.

    This rule should not be construed to mean that XML validation must be performed on all XML instances as they are served or consumed; only that the XML instances validate if XML validation is performed. The XML Schema component definitions specify XML documents and element information items, and the instances should follow the rules given by the schemas, even when validation is not performed.

    NIEM embraces the use of XML Schema instance attributes, including xsi:type , xsi:nil , and xsi:schemaLocation , as specified by [XML Schema Structures].

    14.2. Instance meaning [Rule 14-2] (INS)

    Within the instance, the meaning of an element with no content is that additional properties are not asserted. There SHALL NOT be additional meaning interpreted for an element with no content.

    Rationale

    Elements without content only show a lack of asserted information. That is, all that is asserted is what is explicitly stated, through a combination of XML instance data and itsschema. Data that is not present makes no claims. It may be absent due to lack of availability, lack of knowledge, or deliberate withholding of information. These cases should be modeled explicitly, if they are required.

    14.3. Component representation

    NIEM uses element containment for the majority of its data representation needs;that is, an element containing another element. In general, one object (the content of the outer element) has a relationship (defined by the name of the inner element) to another object (the content of the inner element).

    Figure 14-1: Example of element containment

    This use of the element containment method has limitations. Specifically, recursive and symmetric relationships (direct or transitive) create difficulties, such as repetition of data and resolution of duplicates.

    To avoid these problems, NIEM allows references between elements. In this way, one object (the content of one element) has a relationship (defined by the name of the inner element) to another object (the content of an element referenced by an attribute of the inner element).

    Figure 14-2: Example of element reference [Rule 14-3] (INS)

    Within an element instance, there SHALL NOT be any difference in meaning between a property asserted via element containment and a property asserted by element reference, except as explicitly described by the semantics of the elements involved.

    Rationale

    There is no difference in meaning between relationships established by containment and those established by reference. They are simply two mechanisms for expressingconnections between objects. Neither mechanism implies that properties are intrinsic or extrinsic. Such characteristics must be explicitly stated in property definitions.

    Being of type xs:ID and xs:IDREF , validating schema parsers will perform certain checks on the values of structures:id and structures:ref . Specifically, no two IDs may have the same value. This includes structures:id and other IDs that may be used in an instance. Also, any value of structures:ref must also appear as the value of an ID.

    [Rule 14-4] (INS)

    Within an element instance, given that a reference element is restricted to a target type T, any attribute structures:ref MUST reference an element that has a type definition of type T or that is derived from type T.

    Rationale

    This rule says that the type of the object pointed to by a structures:ref attribute must be of a type specified by the reference element definition. The restriction of types is defined in the application information of the reference element definition by the use of the appinfo:ReferenceTarget attribute. The definition of reference is as given in [XML Infoset], in the description of attribute information items.

    14.4. Instance metadata

    NIEM provides the metadata mechanism for giving information about object assertions. An object may have an attribute that refers to one or more metadata objects. A structures:metadata attribute indicates that a data item has the given metadata. A structures:linkMetadata attribute asserts that the link (or relationship) established by an element has the given metadata.

    Figure 14-3: Example of metadata used in an instance

      John Doe  1945-12-01   Adam Barber   2005-04-26   0.25 

    This example shows a person named John Doe, born 12/1/1945. This data has several pieces of metadata on it:

    • Metadata m1 asserts Adam Barber gave the name.
    • Metadata m2 asserts the name and the birth date were reported on 4/26/2005.
    • Link metadata m3 asserts a 25% probability that the name goes with the person.

    This shows several characteristics of metadata:

    • Metadata objects may appear outside the data they describe.
    • Metadata objects may be reused.
    • Data may refer to more than one metadata object.
    • Metadata pertains to an object or simple content, while link metadata pertains to the relationship between objects.

    An instance would not be valid XML if the structures:metadata or structures:linkMetadata attributes contained references for which there were no defined IDs. The instance would not be NIEM-conformant if the references were not to IDs defined with the structures:id attribute.

    The definition of a metadata type may contain an appinfo:AppliesTo element, which indicates the type to which the metadata applies. For example:

    Figure 14-4: A metadata type that describes applicability using appinfo:AppliesTo

    Application of metadata to a type to which it is not applicable is not NIEM-conformant. A metadata type may contain multiple appinfo:AppliesTo elements, in which case it may apply to an instance of any of the listed types. If a metadata type contains no appinfo:AppliesTo elements, then it may apply to any type. This is the case for nc:MetadataType in NIEM 2.0.

    [Rule 14-5] (INS)

    Within an element instance, when an object O links to a metadata object via an attribute structures:metadata , the information in the metadata object SHALL be applied to the object O.

    [Rule 14-6] (INS)

    Within an element instance, when an object O1 contains an element E, with content object O2 or with a reference to object O2, and O2 links to a metadata object via an attribute structures:linkMetadata , the information in the metadata object SHALL be applied to the relationship E between O1 and O2.

    Rationale

    These two rules define the meaning of metadata:

    • structures:metadata applies metadata to an object.
    • structures:linkMetadata applies metadata to a relationship between two objects.
    [Rule 14-7] (INS)

    Given that each IDREF in the value of an attribute structures:metadata must match the value of an ID attribute on some element in the XML document, that ID attribute MUST be an occurrence of the attribute structures:id .

    [Rule 14-8] (INS)

    Each element that an attribute structures:metadata references MUST have a type definition that is derived from structures:MetadataType .

    [Rule 14-9] (INS)

    Given that each IDREF in the value of an attribute structures:linkMetadata must match the value of an ID attribute on some element in the XML document, that ID attribute MUST be an occurrence of the attribute structures:id .

    [Rule 14-10] (INS)

    Each element that an attribute structures:linkMetadata references MUST have a type definition that is derived from structures:MetadataType.

    Rationale

    All structures:metadata and structures:linkMetadata attributes must refer to metadata objects, and the reference to that object must be established using the structures:id attribute, to facilitate processing of XML documents.

    [Rule 14-11] (INS)

    Given that an element information item E has a type definition of some type T, each metadata type that is the type definition of an element information item referenced by an attribute structures:metadata or structures:linkMetadata on element E MUST be applicable to T.

    Rationale

    The applicability is determined by appinfo:AppliesTo application information of the metadata type definition. The instances must correspond to the types specified by the metadata type definition.

    [Definition: ]

    An XML instance document is an [XML document] that is assessed as [valid] against an [XML Schema] .

    [Definition: ]

    The term valid is as defined by [XML Schema Structures] §2.1, Overview of XML Schema , which states:

    [Definition:] the word valid and its derivatives are used to refer to clause 1 above, the determination of local schema-validity.

    The referenced clause 1 is a part of a description of schema-validity:

    1. Determining local schema-validity, that is whether an element or attribute information item satisfies the constraints embodied in the relevant components of an XML Schema;
    2. Synthesizing an overall validation outcome for the item, combining local schema-validity with the results of schema-validity assessments of its descendants, if any, and adding appropriate augmentations to the infoset to record this outcome.
    14.5. Attribute structures:ref references structures:id [Rule 14-12] (INS) (Constraint)

       The value of an attribute structures:ref MUST appear as the value of an attribute structures:id in the [XML instance document].  

    This states that in NIEM-conformant content, structures:ref attributes must refer to structures:id attributes. By [XML] §3.3.1, an IDREF is required to reference an ID. This rule ensures that the target of a reference is a NIEM ID for easier processing of XML documents.

    14.6. Attribute structures:metadata references a metadata element [Rule 14-13] (INS) (Constraint)

      Each item in the value of an attribute structures:metadata MUST appear as the value of an attribute structures:id with an owner element that is a metadata element.  

    Note that this will NOT catch a scenario in which the element with a name ending in Metadata is an external element; additional tests would be required to catch that.

    14.7. Attribute structures:relationshipMetadata references a metadata element [Rule 14-14] (INS) (Constraint)

      Each item in the value of an attribute structures:relationshipMetadata MUST appear as the value of an attribute structures:id with an owner element that is a metadata element.  

    Note that this will NOT catch a scenario in which the element with a name ending in Metadata is an external element; additional tests would be required to catch that.

    15. Not yet integrated 15.1. Use of application information 15.1.1. Use of the appinfo namespace 15.1.1.1. Deprecated annotates schema component [Rule 15-1] (REF, EXT) (Constraint)

      The attribute appinfo:deprecated MUST be owned by an element with a namespace name xs.  

    15.1.1.2. External import indicator annotates import [Rule 15-2] (REF, EXT) (Constraint)

      The attribute externalImportIndicator MUST be owned by an element xs:import.  

    15.1.1.3. External adapter type indicator annotates complex type [Rule 15-3] (REF) (Constraint)

      The attribute appinfo:externalAdapterTypeIndicator MUST be owned by an element xs:complexType.  

    15.1.1.4. Applies to types annotation 15.1.1.4.1. Applies to types annotates metadata element [Rule 15-4] (REF, EXT) (Constraint)

      The attribute appinfo:appliesToTypes MUST be owned by a metadata element.  

    15.1.1.4.2. Applies to types indicates elements [Rule 15-5] (SET) (Constraint)

      Every item in @appinfo:appliesToTypes MUST resolve to a type.  

    15.1.1.5. Applies to elements annotation 15.1.1.5.1. Applies to elements annotates metadata element [Rule 15-6] (REF, EXT) (Constraint)

      The attribute appinfo:appliesToElements MUST be owned by a metadata element.  

    15.1.1.5.2. Applies to elements indicates elements [Rule 15-7] (SET) (Constraint)

      Every item in @appinfo:appliesToElements must resolve to an element.  

    15.1.2. Use of the local terminology namespace 15.1.2.1. LocalTerm annotates schema [Rule 15-8] (REF, EXT) (Constraint)

      The element LocalTerm MUST be application information an an element xs:schema.  

    15.1.2.2. LocalTerm has literal or definition [Rule 15-9] (REF, EXT) (Constraint)

      The element LocalTerm MUST have a literal or definition.  

    15.2. XML Schema design rules 15.2.1. Namespace imports 15.2.1.1. Including XML content from other namespaces

    Within an XML Schema document, there are several mechanisms to include XML content that is not from the XML or XML Schema namespaces. Those mechanisms are:

    1. Carrying attributes from other than the XML or XML Schema namespaces on an element in the XML Schema namespace. By the rules of XML Schema, any element may have attributes that are from other namespaces. These attributes do not participate in validation but may carry information useful to tools that process schemas.
    2. Adding content to the elements xs:appinfo and xs:documentation . XML Schema allows arbitrary XML content to be included within annotations. Such XML does not participate in validation but may communicate useful information to schema readers or processors.

    NIEM requires all such XML content to be schema-valid. That is, it must have a schema, and it must validate against that schema. The schemas must be introduced via xs:import elements within the schema in which the content is used. This is for two reasons:

    1. Some tools require imports of namespaces used within schemas and validate against those schemas.
    2. The definition and the validity of content within schemas should be clear.
    [Rule 15-10] (REF, EXT) (Constraint)

    Rationale

    XML Schema does not address the schema-validity of content used for annotations or attributes on schema components. This rule ensures that content used in such a manner is schema-valid. This encourages interoperable data definitions and schema documents.

    15.2.2. Additional definitions and declarations

    XML Schema provides a variety of ways to declare and define elements and attributes.

    15.2.2.1. Element declarations

    Within NIEM-conformant schemas, elements may be declared as abstract. Element declarations must be at the toplevel, as rules in other sections prohibit the use of local elements. Elements may be defined without a type, but any element declaration that has no type must be declared abstract by [Rule 6-9], which forbids anonymous type definitions.

    Within an element declaration, the attributes fixed , nillable , and substitutionGroup may be used as per the XML Schema specification. The attribute form is irrelevant to NIEM, as NIEM-conformant schemas may not contain local element definitions by [Rule 6-14].

    Element uses (element declarations acting as particles) must reference top-level named elements. In an element use, NIEM allows any values for the XML Schema properties max occurs and min occurs.

    Based on a variety of user requirements, all elements in the NIEM 2.0 schemas are defined to allow a nil value. For example, the following XML instances are permitted in NIEM-conformant instances:

    Nil value allowance or restriction is only significant to elements of nontextual types (e.g., dates and numeric values) and elements of text types that have restricted value space (e.g., code). This is because an unrestricted text typed element always contains the empty string ( ) in its value space. However, for numeric values and restricted text type elements, NIEM allows users to tighten constraints as required in IEPDs by resetting nillable= false .

    15.2.2.2. Attribute declarations

    Attribute declarations must be declared with a type by [Rule 6-10], which forbids anonymous type definitions for attributes.

    Within an attribute declaration, the attribute fixed may be used as per the XML Schema specification. Within an attribute declaration, the attribute form is irrelevant to NIEM, as NIEM-conformant schemas may not contain local attribute declarations.

    Attribute uses (attribute declarations acting as particles) must be uses of top-level named attributes. NIEM-conformant schemas may not define local named attributes within type definitions. Within an attribute use, the attributes fixed and use may be used as per the XML Schema specification.

    15.3. Modeling rules

    NIEM provides a framework for modeling concepts and relationships as XML artifacts. The data model is implemented via XML Schema. However, XML Schema does not provide sufficient structure and constraint to enable translating from a conceptual model to a schema and then to instances of the concepts. NIEM provides additional support for modeling concepts as schemas and provides rules for creating and connecting data that realizes those concepts.

    Underlying the NIEM data model are two namespaces: the structures namespace and the [appinfo namespace] . These two namespaces provide schema components that serve two functions:

    1. They provide support for connecting structural definitions to concepts.
    2. They provide base components from which to derive structural definitions.

    These namespaces are distributed with the NIEM data model content but are not themselves considered to be content of the data model. They are, instead, part of the structure on which the data model is built.

    15.3.1. xs:schema document element restrictions [Rule 15-11] (REF, EXT)

    Two XML Schema documents SHALL have the same value for attribute targetNamespace carried by the element xs:schema , if and only if they represent the same set of components.

    [Rule 15-12] (REF, EXT)

    Two XML Schema documents SHALL have the same value for attribute targetNamespace carried by the element xs:schema , and different values for attribute version carried by the element xs:schema if and only if they are different views of the same set of components.

    Rationale

    These rules embody the basic philosophy behind NIEM’s use of namespaced components: A component is uniquely identified by its class (e.g. element, attribute, type), its namespace (a URI), and its local name (an unqualified string). Any two matching component identifiers refer to the same component, even if the versions of the schemas containing each are different.

    15.3.2. Annotations

    NIEM-conformant schemas define data models for the purpose of information exchange. A major part of defining data models is the proper definition of the contents of the model. What does a component mean, and what might it contain? How should it be used? NIEM- conformant schemas contain the invariant part of the definitions for the data model. The set of definitions includes:

    1. A text definition of each component. This describes what the component means. The term used in this specification for such a text definition is data definition.
    2. The structural definition of each component. This is made up of XML Schema component definitions, along with certain application information ( appinfo ).

    When possible, meaning is expressed via XML Schema mechanisms: type derivation, element substitution, specific types and structures, as well as names that are trivially parseable. Beyond that, NIEM-specific syntax must be used, as discussed in this section.

    15.3.2.1. Human-readable documentation

    Note that [Rule 5-4] applies [ISO 11179-4] definition rules to documented components.

    [Rule 15-13] (REF, EXT) (Constraint)

    Words or synonyms for the words within a data element definition SHALL NOT be reused as terms in the corresponding component name if those words dilute the semantics and understanding of, or impart ambiguity to, the entity or concept that the component represents.

    [Rule 15-14] (REF, EXT) (Constraint)

    An object class SHALL have one and only one associated semantic meaning (i.e., a single word sense) as described in the definition of the component that represents that object class.

    [Rule 15-15] (REF, EXT) (Constraint)

    An object class SHALL NOT be redefined within the definitions of the components that represent properties or subparts of that entity or class.

    Rationale

    Data definitions should be concise, precise, and unambiguous without embedding additional definitions of data elements that have already been defined once elsewhere (such as object classes). [ISO 11179-4] says that definitions should not be nested inside other definitions. Furthermore, a data dictionary is not a language dictionary. It is acceptable to reuse terms (object class, property term, and qualifier terms) from a component name within its corresponding definition to enhance clarity, as long as the requirements and recommendations of [ISO 11179-4] are not violated. This further enhances brevity and precision.

    [Rule 15-16] (REF, EXT) (Constraint)

    A data definition SHALL NOT contain explicit representational or data typing information such as number characters, type of characters, etc., unless the very nature of the component can be described only by such information.

    Rationale

    A component definition is intended to describe semantic meaning only, not representation or structure. How a component with simple content is represented is indicated through the representation term and further refined through constraints.

    Figure 15-1: A definition that describes mathematical representation

       A value that specifies a minute of a degree. The value comes from a restricted range of 0 (inclusive) to 60 (exclusive).  

    In Figure 7-1, above, the component definition contains representational information because the component is mathematical and therefore requires such. In Figure 7-2, below, the definition is incorrect and states unnecessary representational information about the data element. nc:PersonSSNIdentification is not a social security number (SSN); it is a complex element (type nc:IdentificationType ) that contains a SSN identifier as well as other properties that describe a person’s SSN identifier (such as issue date, issue authority, etc.). The phrase 9-digit is incorrect and unnecessary because it applies only to the SSN identifier and should be applied as a length or pattern constraint on the identifier only.

    Figure 15-2: A definition that describes syntactic representation

       A social security number that references a person; a 9-digit numeric identifier assigned to a living person by the United States Social Security Administration.  

    [Rule 15-17] (REF, EXT) (Constraint)

    A component definition SHALL begin with a standard opening phrase that depends on the class of the component per Table 15-1, Standard opening phrases.

    Table 15-1: Standard opening phrases

    Component class	Definition opening phrase
    Abstract element	A data concept for a…
    Association element	A relationship…
    Association type	A data type for a relationship…
    Augmentation element	Supplements…
    Augmentation type	A data type that supplements…
    Metadata element	Either Metadata about… or Information that further qualifies…
    Metadata type	A data type for metadata about… or A data type for information that further qualifies…
    Element with a date representation term	A date…
    Element with a quantity representation term	A (optional adjective) count/number of…
    Element with an image representation term	A(n) (optional adjective) image/picture/photograph of…
    Element with an indicator representation term	True if…; false otherwise/if…
    Element with an identification representation term	A(n) (optional adjective) identification…
    Element with an ID representation term	An identifier…
    Element with a status representation term	A(n) (optional adjective) status/state of…
    Element with a name representation term	A name of…
    Element with a category text representation term	A kind of…
    Element with a description text representation term	A description of…
    Other element	A(n)…
    Other type	A data type for a(n)…

    Rationale

    A standard opening phrase based on component class helps to ensure consistent definitions that appropriate for the type of component item being defined. These opening phrases also provide a cue that facilitates recognition of the particular kind of component.

    15.3.2.2. Machine-readable annotations

    XML Schema provides application information schema components to provide for automatic processing and machine-readable content for schemas. NIEM utilizes application information to convey information that is outside schema definition and outside human-readable text definitions. NIEM uses application information to convey high-level data model concepts and additional syntax to support the NIEM conceptual model and validation of NIEM-conformant XML instances.

    NIEM defines a single namespace that holds components for use in NIEM-conformant schema application information. This namespace is referred to as the [appinfo namespace] .

    [Definition: ]

    An information item within a schema is defined to be a machine-readable annotation when all of the following are true:

    • It is one of the following:
      • It is an element information item that is a child of an xsd:appinfo element.
      • It is an attribute information item that satisfies the "" clause within the declaration of an XML Schema element.
      [Definition: ]

      The appinfo namespace is the namespace represented by the URI http://release.niem.gov/niem/appinfo/3.0/ .

      The [appinfo namespace] defines elements which provide additional semantics and syntactic guidelines for components built by NIEM-conformant schemas.

      [Rule 15-18] (REF, EXT) (Constraint)

      The schema SHALL import the [appinfo namespace] .

      Rationale

      For uniformity, all NIEM-conformant schemas must import the [appinfo namespace] .

      [Definition: ]

      A component is said to have application information of some element E when the root element that defines the component has an immediate child element xs:annotation , which has an immediate child element xs:appinfo , which has as an immediate child the element E.

      If a component is described as having application information, this means that the application information elements under consideration are children of the element which defines the component.

      The majority of uses of application information from the [appinfo namespace] are described in the modeling rules for the specific component.

      15.3.2.2.1. Deprecation

      The appinfo schema provides a construct for indicating that a construct is deprecated. A deprecated component is one whose use is not recommended. A deprecated component is kept in a schema for support of older versions but should not be used in new efforts. A deprecated component will be removed, replaced, or renamed in a later edition of a schema.

      [Definition: ]

      In a particular NIEM-conformant namespace, a deprecated component is one whose use is not recommended, yet which is maintained in the schema for compatibility with previous versions of the namespace.

      15.3.2.2.1.1. Components marked as deprecated are deprecated components [Rule 15-19] (REF, EXT) (Interpretation)

      A [schema component] that has a [machine-readable annotation] of appinfo:deprecated with a value of true SHALL be a [deprecated component] .

      Deprecation can allow version management to be more consistent; versions of schema may be incrementally improved without introducing validation problems and incompatibility. As XML Schema lacks a deprecation mechanism, NIEM defines such a mechanism.

      15.3.2.2.2. Indicating conformance

      The element appinfo:ConformantIndicator is used for two purposes:

      1. To indicate that a schema is conformant or that it represents a conformant namespace.
      2. To indicate that an imported schema is not conformant or represents a nonconformant namespace.

      The specific rules concerning this element appear in Section 7.1, xs:schema Document Element Restrictions, and Section 7.7, Using External Schemas.

      15.3.3. Simple type definitions

      NIEM places very few restrictions on the definition of simple types in conformant schemas. The use of lists should be reserved for cases where the data is fairly uniform.

      [Rule 15-20] (REF, EXT)

      Within the schema, a simple type definition that uses xs:list SHOULD NOT be defined if any member of the list requires a property or metadata that is different than other members of the list. All members of the list SHOULD have the same metadata, and should be related via the same properties.

      Rationale

      The members of a list are not individually addressable by NIEM metadata techniques. The members are also not individually addressable by properties; a property has a value of all the members of the list. NIEM provides no method for individually addressing a member of a list. If an individual member of a list needs to be marked up in a manner different than other members of the list, the use of individual elements may be preferred to the definition of a list simple type.

      15.3.4. Complex type definitions [Rule 15-21] (REF, EXT)

      Within the schema, an element MUST NOT be introduced more than once into the direct content of a type definition. This applies to content acquired through extension of base types. This does not apply to a base element or derived element to one previously existing in the type definition.

      Rationale

      This rule ensures that sequences of elements are simple sequences. A type should not define, for example, a sequence of elements A, B, then A again. Definitions should define, instead, what elements may be included, and their cardinality. Specific orders should be expressed in instances, when necessary, by the use of the attribute structures:sequenceID .

      15.3.4.1. Object types [Rule 15-22] (REF, EXT)

      Within the schema, an object type SHALL be a complex type definition that either constitutes a NIEM-conformant component or for which there exists a NIEM-conformant component of one of the following forms:

      1. Has simple content, is based on a simple type, and contains the attribute group structures:SimpleObjectAttributeGroup , and has application information appinfo:Base of structures:Object .
      2. Has complex content, and is based on complex type structures:ComplexObjectType , and has application information appinfo:Base of structures:Object .
      3. Is a complex type that is derived from an object type, which is defined according to this rule.

      Rationale

      Object types are at the core of NIEM. They are built in a uniform way, from a simple design pattern: they take one of the two root forms outlined above, or they are built from other object types, depending on whether they are of simple or complex content.

      15.3.4.2. Association types

      Within NIEM, an association is a specific relationship between objects. Associations are used when a simple NIEM property is insufficient to model the relationship clearly and when properties of the relationship exist that are not attributable to the objects being related.

      Here is an example of an association in an XML instance:

      Figure 15-3: An association in an instance

           John Doe    Jane Doe  

      This example shows an association between a guardian and a dependent. This relationship is defined by the element nc:GuardianAssociation , whose structure is defined by the type nc:GuardianAssociationType . The type defines what an association relates, but the element defines the actual meaning of the association.

      An example of an association type defined by an XML Schema document follows.

      Note that the NIEM Core schema in NIEM 2.0 defines a type nc:AssociationType , which acts as the base type for all other association types defined within NIEM Core. This is a convention adopted by the NIEM Core namespace but is not a requirement of the NDR. Implementers of NIEM-conformant schemas are not required to base association types on nc:AssociationType .

      Figure 15-4: A definition of an association type

      This schema fragment shows the definition of a generic AssociationType , which contains a begin and end date. It then defines a specific association type, which contains the structure required to express guardianship. This is followed by the definition of an element that expresses the semantics of the guardian relationship.

      [Definition: ]

      In a NIEM-conformant schema, an association type is a type that establishes a relationship between objects, along with the properties of that relationship. An association type provides a structure that does not establish existence of an object but instead specifies relationships between objects.

      [Definition: ]

      In a NIEM-conformant schema, an association is an element whose type is an association type.

      [Rule 15-23] (REF, EXT)

      Within the schema, an association type SHALL be a complex type definition that either constitutes a NIEM-conformant component or for which there exists a NIEM-conformant component definition. The NIEM-conformant component definition SHALL have one of the following forms:

      1. Has complex content, is based on the complex type structures:ComplexObjectType , and has application information appinfo:Base of structures:Association .
      2. Is a complex type that is derived from an association type, which is defined according to this rule.

      Rationale

      Associations within reference schemas, extensions schemas, and exchange schemas are easily identifiable as such and have a commonly defined base type. For subset schemas, the NIEM-conformant definition may be located in a primary schema and then identified.

      [Rule 15-24] (REF, EXT)

      Given that an association type defines a relationship between a set of participants, within an association type definition, any element that represents a participant SHALL be a reference element.

      Rationale

      Associations are intended to relate objects defined elsewhere. They are not intended to carry content of participant objects.

      15.3.4.3. Metadata types

      Within NIEM, metadata is defined as data about data. This may include information such as the security of a piece of data or the source of the data. These pieces of metadata may be composed into a metadata type. The types of data to which metadata may be applied may be constrained.

      [Definition: ]

      A metadata type describes data about data, that is, information that is not descriptive of objects and their relationships, but is descriptive of the data itself. It is useful to provide a general mechanism for data about data. This provides required flexibility to precisely represent information.

      [Rule 15-25] (REF, EXT)

      Within the schema, a metadata type SHALL contain elements appropriate for a specific class of data about data.

      [Rule 15-26] (REF, EXT)

      Within the schema, a metadata type and only a metadata type SHALL be derived directly from structures:MetadataType .

      Rationale

      A metadata type establishes a specific, named aggregation of data about data. Any type derived from structures:MetadataType is a metadata type. Metadata types should not be derived from other metadata types. Such metadata types should be used asis and additional metadata types defined for additional content.

      [Rule 15-27] (REF, EXT)

      Within the schema, a metadata type MAY have application information appinfo:AppliesTo , indicating the NIEM-conformant object, association, or external adapter types to which the metadata applies.

      [Rule 15-28] (REF, EXT)

      Within the schema, a metadata type that does not have application information appinfo:AppliesTo MAY be applied to any object type, association type, or external adapter type.

      Rationale

      Metadata may be constrained to be applicable to only specific types, or it may be defined to be applicable to any type. The source of a piece of data and the security classification of a piece of data are examples of metadata that may be considered globally applicable.

      15.3.5. Component usage [Rule 15-29] (REF, EXT)

      Any type definition referenced by a component within the schema MUST be from one of the following:

      1. The schema being defined.
      2. A namespace imported as NIEM-conformant.
      3. The XML Schema namespace.
      4. The structures namespace.

      Rationale

      NIEM-conformant schemas are based on other NIEM-conformant schemas and the supporting namespaces. This simplifies processing and understanding of data.

      [Rule 15-30] (REF, EXT)

      Any element declaration referenced by a component within the schema MUST be from one of the following:

      1. The schema being defined.
      2. A namespace imported as NIEM-conformant.
      3. The structures namespace.
      4. An external namespace, in accordance with the rules for external schemas as specified by this specification.
      [Rule 15-31] (REF, EXT)

      Any attribute declaration referenced by a component within the schema MUST be from one of the following:

      1. The schema being defined.
      2. A namespace imported as NIEM-conformant.
      3. The structures namespace.
      4. The XML namespace.
      5. An external namespace, in accordance with the rules for external schemas as specified by this specification.

      Rationale

      NIEM-conformant schemas are based on other NIEM-conformant schemas. All attributes and elements must be from NIEM-conformant schemas, the structures namespace, the XML namespace, or an external namespace. This applies to elements referenced for substitution groups as well. It does not apply to content of the schema (e.g., within annotations) or to the XML Schema declarations themselves. It applies only to attributes and elements referenced by the XML Schema components.

      15.3.6. NIEM structural facilities

      NIEM provides the structures schema that contains base types for types defined in NIEM- conformant schemas. It provides base elements to act as heads for substitution groups. It also provides attributes that provide facilities not otherwise provided by XML Schema. These structures should be used to augment XML data. The structures provided are not meant to replace fundamental XML organization methods; they are intended to assist them.

      [Definition: ]

      The structures namespace is the namespace represented by the URI http://niem.gov/niem/structures/2.0 .

      The structures namespace is a single namespace, separate from namespaces that define NIEM-conformant data. This document refers to this content via the prefix structures .

      [Rule 15-32] (REF, EXT)

      The schema MUST import the NIEM structures namespace.

      Rationale

      For uniformity, all NIEM-conformant schemas must import the structures namespace.

      [Rule 15-33] (REF, EXT, INS)

      The schema or instance MUST use content within the NIEM structures namespace as specified in this document and ONLY as specified by this document.

      Rationale

      This rule further enforces uniformity and consistency by mandating use of the NIEM structures namespace as is, without modification. Users are not allowed to insert types, attributes, etc. that are not specified by this document (the NDR).

      15.3.6.1. Reference elements

      In XML instances, relationships between data objects are expressed as XML elements:

      1. Data objects are expressed as XML elements.
      2. XML elements contain attributes and other elements.

      In this way, there is generally some implicit relationship between the outer element (the containing element, also known as the parent element) and the inner elements (the contained elements, also known as the child elements). Such expression of relationships is said to be by containment.

      Expression of all relationships via element containment is not always possible. Situations that cause problems include:

      • Circular relationships. For example, suppose that object 1 has a relationship to object 2 and object 2 has a relationship to object 1. Expressed via containment, this relationship would result in infinite recursive descent.
      • Repeated relationships. For example, suppose object 1 has a relationship to object 2 and object 3 has a relationship to object 2. Expressed via containment, this would result in a duplicate of object 2.

      A method that solves this problem is the use of references. In a C or assembler, a pointer would be used. In C++, a reference might be used. In Java, a reference value might be used. The method defined by the XML standard is the use of ID and IDREF. An IDREF refers to an ID. NIEM uses this method and assigns to it specific semantics.

      [Definition: ]

      A reference element is an element that refers to its value by a reference attribute instead of carrying it as content.

      [Rule 15-34] (REF, EXT)

      Within the schema, a reference element and only a reference element SHALL be defined to be of type structures:ReferenceType .

      Rationale

      Reference elements must be of the reference type, and elements of the reference type must be reference elements. This rule ensures that users always create reference elements using structures:ReferenceType and cannot use structures:ReferenceType for any other purpose.

      [Rule 15-35] (REF, EXT)

      Within the schema, a complex type SHALL NOT be defined such that an instance of that type owns the attribute structures:ref .

      Rationale

      The use of references is limited to reference elements. This constrains the semantics and syntax of references within NIEM instances. Only structures:ReferenceType may use structures:ref , which is the only means for referencing within NIEM-conformant instances.

      [Rule 15-36] (REF, EXT)

      Within the schema, any two elements of the form

      where the string value of NCName is the same in both forms, SHALL be defined to have identical semantics. NIEM recognizes no difference in meaning between a reference element and an element that is not a reference element.

      Rationale

      NIEM-conformant data instances may use concrete data elements and reference elements as needed, to represent the meaning of the fundamental data. There is no difference in meaning between reference and concrete data representations. The two different methods are available for ease of representation. No difference in meaning should be implied by the use of one method or the other.

      Assertions that indicate included data is intrinsic, while referenced data is extrinsic, are not valid and are not applicable to NIEM-conformant data instances and data definitions.

      [Rule 15-37] (REF, EXT)

      Within the schema, if both elements NCName and NCNameReference exist, then the appinfo:ReferenceTarget of any NCNameReference element MUST be the type of the element NCName.

      Rationale

      By [Rule 7-59], any such pair of elements, NCName and NCNameReference , will have identical semantics. This rule ensures that an NCNameReference element is documented to refer to the appropriate type (the type of the corresponding NCName element) and no other.

      The NIEM structures schema defines structures:ReferenceType to require the use of an attribute structures:ref , which is of type xs:IDREF as specified by [XML Schema Structures]. According to the rules of XML, such an attribute must contain a value that is represented by an attribute of type xs:ID . In NIEM-conformant instance, the targets of IDREFs are expected to be values of the attribute structures:id .

      The NIEM structures schema defines structures:ReferenceType such that it is unavailable as a base for extension or restriction.

      The NIEM structures schema defines structures:ReferenceType such that it has an optional attribute structures:id . This may be used to describe additional metadata or information about the relationship described by an element of type structures:ReferenceType .

      Within a NIEM-conformant instance, the element referenced by an attribute structures:ref must be of a type valid for the object of the fundamental element of the reference element. The attribute structures:ref is discussed in more detail in Section 8.3.

      15.3.7. Using external schemas

      There are a variety of commonly used standards that are represented in XML Schema. Such schemas are generally not NIEM-conformant. NIEM-conformant schemas may reference components defined by these external schemas. NIEM-conformant components may be constructed from schema components that are not NIEM-conformant.

      [Definition: ]

      An external schema is any schema that is not a supporting schema and that is not NIEM-conformant.

      Note that the supporting schemas structures and appinfo are nonconformant because they define the fundamental framework on which NIEM is built. However, they are not considered external schemas because of their supporting nature and are thus excluded from this definition.

      NIEM-conformant schemas may work with external schemas by creating external adapter types.

      A single method is used to integrate external components into NIEM-conformant schemas: NIEM-conformant types are constructed from the external components.

      Figure 15-5: Use of external components to create a NIEM-conformant type

      Components defined by external schemas are called external components. A NIEM-conformant type may use external components in a specific way: to construct a NIEM-conformant type from external components. The goal in this method is to preserve as a single unit a set of data that embodies a single concept from an external standard.

      For example, a NIEM-conformant type may be created to represent a bibliographic reference from an external standard. Such an object may be composed of multiple elements and types from the external standard. These pieces are put together to form a single NIEM-conformant type. For example, an element representing an author, a book, and a publisher may be included in a single bibliographic entry.

      A NIEM-conformant type built from these components may be used as any other NIEM- conformant type. That is, elements may be constructed from such a type, and those elements are fully NIEM-conformant.

      To construct such a component, a NIEM-conformant schema must first import an external schema.

      [Rule 15-38] (REF, EXT)

      Within the schema, an element xs:import that imports a namespace defined by an external schema MUST have the application information appinfo:ConformantIndicator , with a value of false .

      Rationale

      Knowledge of the conformance of an imported schema allows processors to understand the semantics of referenced components, without additional processing. Namespaces imported into NIEM-conformant schemas are assumed to be conformant unless otherwise indicated.

      [Rule 15-39] (REF, EXT)

      Within the schema, an element xs:import that imports a namespace defined by an external schema MUST be a documented component.

      Rationale

      A NIEM-conformant schema has well-known documentation points. Therefore, a schema that imports a NIEM-conformant namespace need not provide additional documentation. However, when an external schema is imported, appropriate documentation must be provided at the point of import because documentation associated with external schemas is undefined and variable. In this particular case, documentation of external schemas is required at their point of use in NIEM.

      [Definition: ]

      An adapter type is a NIEM-conformant type that adapts external components for use within NIEM. An adapter type creates a new class of object that embodies a single concept composed of external components. A NIEM-conformant schema defines an adapter type.

      [Rule 15-40] (REF, EXT)

      Within the schema, an adapter type MUST have application information appinfo:ExternalAdapterTypeIndicator with a value of true . A type that is not an adapter type SHALL NOT contain that indicator.

      Rationale

      This rule flags as external adapters those types that may contain external content. This allows for easier processing.

      [Rule 15-41] (REF, EXT)

      Within the schema, an adapter type MUST be an immediate extension of type structures:ComplexObjectType .

      Rationale

      The adapter type must contain the content defined for any NIEM component. The type structures:ComplexObjectType provides such content.

      [Rule 15-42] (REF, EXT)

      Within the schema, an adapter type MUST be composed of only elements and attributes from an external standard.

      Rationale

      An adapter type should contain the information from an external standard to express a complete concept. This expression should be composed of content entirely from an external schema. Most likely, the external schema will be based on an external standard with its own legacy support.

      In the case of an external expression that is in the form of model groups, attribute groups, or types, additional elements and type components may be created in an external schema, and the adapter type may use those components.

      [Rule 15-43] (REF, EXT)

      Within the schema, an element reference used in an adapter type definition MUST be a documented component.

      [Rule 15-44] (REF, EXT)

      Within the schema, an attribute reference used in an adapter type definition MUST be a documented component.

      Rationale

      In normal (conformant) type definition, a reference to an attribute or element is a reference to a documented component. Within an adapter type, the references to the attributes and elements being adapted are references to undocumented components. These components must be documented to provide comprehensibility and interoperability. Since documentation made available by nonconformant schemas is undefined and variable, documentation of these components is required at their point of use, within the conformant schema.

      [Rule 15-45] (REF, EXT)

      Within the schema, an adapter type MUST NOT be extended or restricted.

      Rationale

      Adapter types are meant to stand alone; each type expresses a single concept from an external schema, and adapter types are maintained in separate schemas that only contain adapter types. In this way, processors may easily switch modes, processing NIEM-conformant content in one way, and external content in another.

      15.3.8. Container elements

      All NIEM properties establish a relationship between the object holding the property and the value of the property. For example, an activity object of type nc:ActivityType may have an element nc:ActivityDescriptionText . This element will be of type nc:TextType and represents a NIEM property owned by that activity object. An occurrence of this element within an activity object establishes a relationship between the activity object and the text: the text is the description of the activity.

      In a NIEM-conformant instance, an element establishes a relationship between the object that contains it and the element’s value. This relationship between the object and the element may be semantically strong, such as the text description of an activity in the previous example, or it may be semantically weak, with its exact meaning left unstated. In NIEM, the contained element involved in a weakly defined semantic relationship is commonly referred to as a container element.

      A container element establishes a weakly defined relationship with its containing element. For example, an object of type nc:ItemDispositionType may have a container element nc:Item of type nc:ItemType . The container element nc:Item does not establish what relationship exists between the object of nc:ItemDispositionType and itself. There could be any of a number of possible semantics between an object and the value of a container element. It could be a contained object, a subpart, a characteristic, or some other relationship. The appearance of this container element inside the nc:ItemDispositionType merely establishes that the disposition has an item.

      The name of the container element is usually based on the NIEM type that defines it: nc:PersonType uses a container element nc:Person , while nc:ActivityType uses a container element nc:Activity . The concept of an element as a container element is a notional one.

      There are no formalized rules addressing what makes up a container element. A container element is vaguely defined and carries very little semantics about its context and its contents. Accordingly, there is no formal definition of container elements in NIEM: There are no specific artifacts that define a container element; there are no appinfo or other labels for container elements.

      The appearance of a container element within a NIEM type carries no additional semantics about the relationship between the property and the containing type. The use of container elements indicates only that there is a relationship;it does not provide any semantics for interpreting that relationship.

      For example, a NIEM container element nc:Person would be associated with the NIEM type nc:PersonType . The use of the NIEM container element nc:Person in a containing NIEM type indicates that a person has some association with the instances of the containing NIEM type. But because the nc:Person container element is used, there is no additional meaning about the association of the person and the instance containing it. While there is a person associated with the instance, nothing is known about the relationship except its existence.

      The use of the Person container element is in contrast to a NIEM property named nc:AssessmentPerson , also of NIEM type nc:PersonType . When the NIEM property nc:AssessmentPerson is contained within an instance of a NIEM type, it is clear that the person referenced by this property was responsible for an assessment of some type, relevant to the exchange being modeled. The more descriptive name, nc:AssessmentPerson , gives more information about the relationship of the person with the containing instance, as compared with the semantic-free implications associated with the use of the nc:Person container element.

      When a NIEM-conformant schema requires a new container element, it may define a new element with a concrete type and a general name, with general semantics. Any schema may define a container element when it requires one. NIEM-conformant schemas may also create reference elements with general semantics. For example, an element nc:PersonReference will carry the same general, container-like meaning as an element nc:Person .

      Appendix A. References

      [ClarkNS] : Clark, J. XML Namespaces , 4 February 1999. Available from http://www.jclark.com/xml/xmlns.htm.

      [CTAS] : NIEM Conformance Targets Attribute Specification, Version 3.0 , 1 August 2012.

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

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

      [N-ary] : Defining N-ary Relations on the Semantic Web , W3C Working Group Note, 12 April 2006. Available from http://www.w3.org/TR/2006/NOTE-swbp-n-aryRelations-20060412/.

      Use case 3 is described at #useCase3.

      [OED] : Oxford English Dictionary, Third Edition , Oxford University Press, November 2010. http://dictionary.oed.com/.

      [RDF Primer] : RDF Primer , W3C Recommendation, 10 February 2004. Available from http://www.w3.org/TR/2004/REC-rdf-primer-20040210/.

      Basic concepts are covered at #basicconcepts.

      [RDF Semantics] : RDF Semantics , W3C Recommendation, 10 February 2004. Available from http://www.w3.org/TR/2004/REC-rdf-mt-20040210/.

      The meaning of RDF assertions is described at #interp.

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

      [RFC 3986] : Berners-Lee, T., et al. Uniform Resource Identifier (URI): Generic Syntax , Request for Comments 3986, January 2005. Available from http://www.ietf.org/rfc/rfc3986.txt.

      [Wikipedia] : Wikipedia . Available from http://en.wikipedia.org/.

      [XML] : Extensible Markup Language (XML) 1.0 (Fourth Edition) , W3C Recommendation, 16 August 2006. Available from http://www.w3.org/TR/2008/REC-xml-20081126/.

      [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/.

      [XML Namespaes] : Namespaces in XML 1.0 (Third Edition) , W3C Recommendation, 8 December 2009. Available from http://www.w3.org/TR/2009/REC-xml-names-20091208/.

      NCName is described at #NT-NCName.

      [XML Namespaces Errata] : Namespaces in XML Errata , 6 December 2002. Available from http://www.w3.org/XML/xml-names-19990114-errata.

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

      Prohibition on direct use of simple type xs:NOTATION is at #enumeration-required-notation.

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

      Annotations are described at #Annotation_details.

      XML schema is defined at #key-schema.

      XML Schema definition language is described at #abstract.

      schema document is defined at #key-schemaDoc.

      valid is defined at #key-vn.

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

      [XPath 2] : Berglund, Anders, Scott Boag, Don Chamberlin, Mary F. Fernández, Michael Kay, Jonathan Robie, and Jérôme Siméon. XML Path Language (XPath) 2.0 (Second Edition) , W3C Recommendation, 3 January 2011. http://www.w3.org/TR/2010/REC-xpath20-20101214/.

      Appendix B. Structures namespace

                            An augmentation point for ObjectType            An augmentation point for AssociationType             

      Appendix C. Appinfo namespace

         The appinfo schema provides support for high level data model concepts and additional syntax to support the NIEM conceptual model and validation of NIEM-conformant instances.   The Deprecated element provides a method for identifying schema components as being deprecated. A deprecated component is one that is provided, but the use of which is not recommended.        The appliesToTypes attribute appears on the element declaration of a metadata element. It indicates a set of types to which the metadata element may be applied. The metadata element will also be applicable to any type that is derived from a listed type.      The appliesToElements attribute appears on the element declaration of a metadata element. It indicates a set of elements to which the metadata element may be applied. The metadata element will also be applicable to any element that is in the substitution group of a listed element.      The externalAdapterTypeIndicator attribute indicates that a complex type is an external adapter type. An external adapter type is composed of elements and attributes from non-NIEM-conformant schemas.        The externalImportIndicator attribute is true if and only if a namespace identified via xs:import is expected to be non-conformant.