Elements

An element represents a concept. In an instance, it acts as a container that may carry either simple content (a value) or complex content (an object). In either case, an element can also carry attributes.

  • Core defines element nc:PersonGivenName. This element will carry simple content, for example, a value like “Jane”.
  • Core also defines element nc:Person. This element will carry complex content - a set of sub-elements representing properties like name, age, height, and employment information.

Modeling guidance

In addition to the general modeling rules and guidance provided for properties, the following applies specifically to elements:

Type must be complex

An elements with a type must have a complex type.

All complex types in NIEM eventually derive from structures:ObjectType or a similar type in the NIEM structures namespace. These types contain attributes that enable NIEM elements to reference to other elements, support linked data, define metadata, and provide security markup. As these features are not possible with simple types, an element is required to have a complex type.

Note: An abstract element may be defined without a type.

Nillable

Elements in a reference schema must allow a nil value. This is needed to support NIEM’s referencing mechanism.

XML

Instance example

<nc:Person>
  <nc:PersonName structures:id="a123">
    <nc:PersonGivenName>John</nc:PersonGivenName>
    <nc:PersonMiddleName nc:personNameInitialIndicator="true">Q</nc:PersonMiddleName>
    <nc:PersonSurName>Smith</nc:PersonSurName>
  </nc:PersonName>
</nc:Person>
  • nc:Person is an element that carries complex content.
  • nc:PersonName is an element that carries complex content and an attribute.
  • nc:PersonGivenName and nc:PersonSurName are elements that carry simple content (values).
  • nc:PersonMiddleName is an element that carries simple content (a value) and an attribute.

Schema example

Despite the variations, each of the elements above is defined the same way in a schema. The different representations are defined by the element’s type, not by the element itself.

<!-- Element with complex content -->
<xs:element name="Person" type="nc:PersonType" nillable="true">
  <xs:annotation>
    <xs:documentation>A human being.</xs:documentation>
  </xs:annotation>
</xs:element>

<!-- Element with simple content -->
<xs:element name="PersonMiddleName" type="nc:PersonNameTextType" nillable="true">
  <xs:annotation>
    <xs:documentation>A middle name of a person.</xs:documentation>
  </xs:annotation>
</xs:element>

Schema template

<xs:element name="NAME" type="TYPE" nillable="true">
  <xs:annotation>
    <xs:documentation>DEFINITION</xs:documentation>
  </xs:annotation>
</xs:element>

Schema restrictions

The following is a list of restrictions that the NIEM NDR defines relating to XML element declarations.

Prohibited types

  • xs:anySimpleType
  • xs:anyType

These types are not allowed to prevent elements acting as wildcards. Substitutions and augmentations should be used instead.

Prohibited attributes

The following attributes may not be used in the declaration of an element in an XML Schema:

  • block
  • final
  • default
  • fixed

NIEM is designed to be extensible and customizable, in order to support a wide-ranging variety of requirements. The block and final attributes above prevent further customization by subsequent schemas.

The default and fixed attributes can result in unexpected behavior. A validating parser may construct values for an element assigned a default or fixed value in its schema; a non-validating parser will not. Preventing these attributes ensures that the information in an instance is not altered, depending on which parser is used to process the data.

JSON

Instance example

{
  "nc:Person": {
    "nc:PersonName" : {
      "nc:PersonGivenName": "John",
      "nc:PersonSurName": "Smith"
    }
  }
}
  • nc:Person and nc:PersonName are elements that carry complex content.
  • nc:PersonGivenName and nc:PersonSurName are elements that carry simple content (values).

Schema example

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "additionalProperties": false,
  "properties": {
    "nc:Person": {
      "description": "A human being.",
      "oneOf": [
        {
          "$ref": "#/definitions/nc:PersonType"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/definitions/nc:PersonType"
          }
        }
      ]
    }
  }
}

Note that this is different from the corresponding XML Schema syntax. An XML type defines if a property that it contains appears once or multiple times. If a person has two middle names, then the element nc:PersonMiddleName may appear in the instance multiple times.

In NIEM JSON, the property declares itself to have either the expected type, or an array of objects of the expected type. Properties are keys in a JSON object - they can only appear once.

This syntax supports the simple case, where a property is defined to have only one of the given value ("nc:PersonMiddleName"). It also supports the case where a property has multiple values, and must be accessed as an array, like "nc:PersonMiddleName"[0], "nc:PersonMiddleName"[1], etc.

Exchange schemas may subset this to choose the actual representation that is needed, but reference schemas should make both options available.

Schema template

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "additionalProperties": false,
  "properties": {
    "NAME": {
      "description": "DEFINITION",
      "oneOf": [
        {
          "$ref": "#/definitions/TYPE"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/definitions/TYPE"
          }
        }
      ]
    }
  }
}

NDR references

NDR 5.0
Rule Applicability Title
NDR 9-36 REF, EXT Element declaration is top-level
NDR 9-37 REF, EXT Element declaration has data definition
NDR 9-38 REF, EXT Untyped element is abstract
NDR 9-39 REF, EXT Element of type xs:anySimpleType is abstract
NDR 9-40 REF, EXT Element type not in the XML Schema namespace
NDR 9-41 REF, EXT Element type not in the XML namespace
NDR 9-42 REF, EXT Element type is not simple type
NDR 9-43 REF No element disallowed substitutions
NDR 9-44 REF No element disallowed derivation
NDR 9-45 REF, EXT No element default value
NDR 9-46 REF, EXT No element fixed value
NDR 9-47 REF Element declaration is nillable
NDR 9-72 REF, EXT No use of xs:unique
NDR 9-73 REF, EXT No use of xs:key
NDR 9-74 REF, EXT No use of xs:keyref
NDR 10-19 REF, EXT Element of code type has code representation term
NDR 10-44 REF, EXT Schema component name composed of English words
NDR 10-45 REF, EXT Schema component name has xml:lang
NDR 10-46 REF, EXT Schema component names have only specific characters
NDR 10-47 REF, EXT Punctuation in component name is a separator
NDR 10-48 REF, EXT Names use camel case
NDR 10-50 REF, EXT Name of schema component other than attribute and proxy type begins with upper case letter
NDR 10-51 REF, EXT Names use common abbreviations
NDR 10-54 REF, EXT Singular form is preferred in name
NDR 10-55 REF, EXT Present tense is preferred in name
NDR 10-56 REF, EXT Name does not have nonessential words
NDR 10-57 REF, EXT Element or attribute name follows pattern
NDR 10-58 REF, EXT Object-class term identifies concrete category
NDR 10-59 REF, EXT Property term describes characteristic or subpart
NDR 10-60 REF, EXT Name may have multiple qualifier terms
NDR 10-61 REF, EXT Name has minimum necessary number of qualifier terms
NDR 10-62 REF, EXT Order of qualifiers is not significant
NDR 10-63 REF, EXT Redundant term in name is omitted
NDR 10-64 REF, EXT Element with simple content has representation term
NDR 10-65 REF, EXT Element with complex content has representation term when appropriate
NDR 10-66 REF, EXT Element with complex content has representation term only when appropriate
NDR 11-12 REF, EXT Element type does not have a simple type name
NDR 11-13 REF, EXT Element type is from conformant namespace
NDR 11-14 REF, EXT Name of element that ends in Abstract is abstract
NDR 11-15 REF, EXT Name of element declaration with simple content has representation term
NDR 11-16 SET Name of element declaration with simple content has representation term
NDR 11-17 REF, EXT Element substitution group defined by conformant schema
NDR 11-30 REF, EXT xs:documentation has xml:lang
NDR 12-10 INS Order of properties is expressed via structures:sequenceID
NDR 4.0
Rule Applicability Title
NDR 9-36 REF, EXT Element declaration is top-level
NDR 9-37 REF, EXT Element declaration has data definition
NDR 9-38 REF, EXT Untyped element is abstract
NDR 9-39 REF, EXT Element of type xs:anySimpleType is abstract
NDR 9-40 REF, EXT Element type not in the XML Schema namespace
NDR 9-41 REF, EXT Element type not in the XML namespace
NDR 9-42 REF, EXT Element type is not simple type
NDR 9-43 REF No element disallowed substitutions
NDR 9-44 REF No element disallowed derivation
NDR 9-45 REF, EXT No element default value
NDR 9-46 REF, EXT No element fixed value
NDR 9-47 REF Element declaration is nillable
NDR 9-72 REF, EXT No use of xs:unique
NDR 9-73 REF, EXT No use of xs:key
NDR 9-74 REF, EXT No use of xs:keyref
NDR 10-19 REF, EXT Element of code type has code representation term
NDR 10-44 REF, EXT Schema component name composed of English words
NDR 10-45 REF, EXT Schema component names have only specific characters
NDR 10-46 REF, EXT Punctuation in component name is a separator
NDR 10-47 REF, EXT Names use camel case
NDR 10-49 REF, EXT Name of schema component other than attribute and proxy type begins with upper case letter
NDR 10-50 REF, EXT Names use common abbreviations
NDR 10-53 REF, EXT Singular form is preferred in name
NDR 10-54 REF, EXT Present tense is preferred in name
NDR 10-55 REF, EXT Name does not have nonessential words
NDR 10-56 REF, EXT Element or attribute name follows pattern
NDR 10-57 REF, EXT Object-class term identifies concrete category
NDR 10-58 REF, EXT Property term describes characteristic or subpart
NDR 10-59 REF, EXT Name may have multiple qualifier terms
NDR 10-60 REF, EXT Name has minimum necessary number of qualifier terms
NDR 10-61 REF, EXT Order of qualifiers is not significant
NDR 10-62 REF, EXT Redundant term in name is omitted
NDR 10-63 REF, EXT Element with simple content has representation term
NDR 10-64 REF, EXT Element with complex content has representation term when appropriate
NDR 10-65 REF, EXT Element with complex content has representation term only when appropriate
NDR 11-11 REF, EXT Element type does not have a simple type name
NDR 11-12 REF, EXT Element type is from conformant namespace
NDR 11-13 REF, EXT Name of element that ends in Abstract is abstract
NDR 11-14 REF, EXT Name of element declaration with simple content has representation term
NDR 11-15 SET Name of element declaration with simple content has representation term
NDR 11-16 REF, EXT Element substitution group defined by conformant schema