Complex Types with Complex Content

A complex type with complex content (CCC) is a structure that represents an object and may contain elements and attributes.

A CCC type represents an object with properties, rather than a simple value.

Examples of CCC types in NIEM include the following:

  • nc:PersonType, which includes properties like name, birthday, and height.
  • nc:LocationType, which includes properties like an address and lat-long coordinates.
  • nc:ContactInformationType, which includes properties like a telephone number and an email address.

Modeling guidance

Representation term “Type”

The name of a type must end with the representation term Type.

Parent

CCC types may only extend other CCC types.

Default parent

For a type that is not metadata, an association, or an augmentation, the default parent type, if none other is provided, should be structures:ObjectType.

Sequence

In reference schemas, a CCC type’s elements must be represented as a sequence, rather than a choice.

Default cardinality

The default usage of properties in a type from a NIEM release should be optional and over-inclusive. In XML, this would be represented as minOccurs="0" and maxOccurs="0".

Individual information exchanges can and often should have very precise cardinality requirements. Because these vary across different use cases, and because cardinality restrictions can be tightened but not loosened in a subset, cardinality should be set as flexibly as possible in the release schemas.

XML

Instance example

<nc:PersonName>
  <nc:PersonGivenName>Jane/<nc:PersonGivenName>
  <nc:PersonMiddleName>Elizabeth</nc:PersonMiddleName>
  <nc:PersonSurName>Smith</nc:PersonSurName>
</nc:PersonName>

Schema example

The following shows an example of a subset of type nc:PersonNameType. It is a complex type with complex content (CCC) that contains elements and an attribute.

<xs:complexType name="PersonNameType">
  <xs:annotation>
    <xs:documentation>
      A data type for a combination of names and/or titles by which a person is known.
    </xs:documentation>
  </xs:annotation>
  <xs:complexContent>
    <xs:extension base="structures:ObjectType">
      <xs:sequence>
        <xs:element ref="nc:PersonGivenName" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element ref="nc:PersonMiddleName" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element ref="nc:PersonSurName" minOccurs="0" maxOccurs="unbounded"/>
      </xs:sequence>
      <xs:attribute ref="nc:personNameCommentText" use="optional"/>
    </xs:extension>
  </xs:complexContent>
</xs:complexType>

Schema template

This template shows the creation of a complex type with complex content. It specifies a parent type, two elements, and an attribute.

<xs:complexType name="NAME">
  <xs:annotation>
    <xs:documentation>A data type for ....</xs:documentation>
  </xs:annotation>
  <xs:complexContent>
    <xs:extension base="PARENT_TYPE">
      <xs:sequence>
        <xs:element ref="PROPERTY_1" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element ref="PROPERTY_2" minOccurs="0" maxOccurs="unbounded"/>
      </xs:sequence>
      <xs:attribute ref="ATTRIBUTE" use="optional"/>
    </xs:extension>
  </xs:complexContent>
</xs:complexType>
  • The cardinality on elements may be adjusted by changing the minOccurs and maxOccurs values. NIEM reference schemas tend to be very flexible, but cardinality should be adjusted in IEPDs to meet specific exchange requirements.
  • The cardinality on attributes may be adjusted by changing the use value from optional to required.

JSON

Instance example

The example below shows element nc:Vehicle, which has a CCC type. It contains an object with three properties.

Property nc:VehicleIdentification also has a CCC type, representing an identification object with one property of its own.

{
  "nc:Vehicle": {
    "nc:VehicleAxleQuantity": 2,
    "nc:VehicleIdentification": {
      "nc:IdentificationID": "AX54C62"
    },
    "nc:VehicleMSRPAmount": 25000
  }
}

Schema example

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "additionalProperties": false,
  "definitions": {
    "nc:VehicleType": {
      "description": "A data type for a conveyance designed to carry an operator, passengers and/or cargo, over land.",
      "allOf": [
        {
          "$ref": "#/definitions/nc:ConveyanceType"
        },
        {
          "type": "object",
          "properties": {
            "nc:VehicleAxleQuantity": {
              "$ref": "#/properties/nc:VehicleAxleQuantity"
            },
            "nc:VehicleIdentification": {
              "$ref": "#/properties/nc:VehicleIdentification"
            },
            "nc:VehicleMSRPAmount": {
              "$ref": "#/properties/nc:VehicleMSRPAmount"
            }
          }
        }
      ]
    }
}

In NIEM, nc:VehicleType extends nc:ConveyanceType. This is captured by the allOf syntax above, which creates a reference to the parent type, then defines the vehicle-specific properties below.

Schema template

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "additionalProperties": false,
  "definitions": {
    "NAME": {
      "description": "A data type for ...",
      "allOf": [
        {
          "$ref": "#/definitions/PARENT_TYPE"
        },
        {
          "type": "object",
          "properties": {
            "PROPERTY_1": {
              "$ref": "#/properties/PROPERTY_1"
            },
            "PROPERTY_2": {
              "$ref": "#/properties/PROPERTY_2"
            }
          }
        }
      ]
    }
}

Any attributes that a CCC type contains should be represented the same way as elements, i.e., as properties under the JSON Schema properties key.

NDR references

NDR 5.0
Rule Applicability Title
NDR 9-25 REF, EXT Complex type definition is top-level
NDR 9-26 REF, EXT Complex type has data definition
NDR 9-27 REF, EXT No mixed content on complex type
NDR 9-28 REF, EXT No mixed content on complex content
NDR 9-29 REF, EXT Complex type content is explicitly simple or complex
NDR 9-30 REF Complex content uses extension
NDR 9-31 REF, EXT Base type of complex type with complex content must have complex content
NDR 9-32 SET Base type of complex type with complex content must have complex content
NDR 9-34 REF No complex type disallowed substitutions
NDR 9-35 REF No complex type disallowed derivation
NDR 9-60 EXT Model group does not affect meaning
NDR 9-61 REF, EXT No xs:all
NDR 9-62 REF xs:sequence must be child of xs:extension
NDR 9-63 EXT xs:sequence must be child of xs:extension or xs:restriction
NDR 9-64 REF No xs:choice
NDR 9-65 EXT xs:choice must be child of xs:sequence
NDR 9-66 REF, EXT Sequence has minimum cardinality 1
NDR 9-67 REF, EXT Sequence has maximum cardinality 1
NDR 9-68 EXT Choice has minimum cardinality 1
NDR 9-69 EXT Choice has maximum cardinality 1
NDR 9-70 REF No use of xs:any
NDR 9-71 REF No use of xs:anyAttribute
NDR 10-1 REF, EXT Complex type has a category
NDR 10-2 REF, EXT Object type with complex content is derived from structures:ObjectType
NDR 10-23 REF Augmentable type has augmentation point element
NDR 10-24 REF, EXT Augmentable type has at most one augmentation point element
NDR 11-20 REF, EXT Element or attribute declaration introduced only once into a type
NDR 11-21 REF, EXT Element reference defined by conformant schema
NDR 11-22 REF, EXT Referenced attribute defined by conformant schemas
NDR 11-23 REF, EXT Schema uses only known attribute groups
NDR 11-46 REF, EXT Standard opening phrase for complex type data definition
NDR 4.0
Rule Applicability Title
NDR 9-25 REF, EXT Complex type definition is top-level
NDR 9-26 REF, EXT Complex type has data definition
NDR 9-27 REF, EXT No mixed content on complex type
NDR 9-28 REF, EXT No mixed content on complex content
NDR 9-29 REF, EXT Complex type content is explicitly simple or complex
NDR 9-30 REF Complex content uses extension
NDR 9-31 REF, EXT Base type of complex type with complex content must have complex content
NDR 9-32 SET Base type of complex type with complex content must have complex content
NDR 9-34 REF No complex type disallowed substitutions
NDR 9-35 REF No complex type disallowed derivation
NDR 9-60 EXT Model group does not affect meaning
NDR 9-61 REF, EXT No xs:all
NDR 9-62 REF xs:sequence must be child of xs:extension
NDR 9-63 EXT xs:sequence must be child of xs:extension or xs:restriction
NDR 9-64 REF No xs:choice
NDR 9-65 EXT xs:choice must be child of xs:sequence
NDR 9-66 REF, EXT Sequence has minimum cardinality 1
NDR 9-67 REF, EXT Sequence has maximum cardinality 1
NDR 9-68 EXT Choice has minimum cardinality 1
NDR 9-69 EXT Choice has maximum cardinality 1
NDR 9-70 REF No use of xs:any
NDR 9-71 REF No use of xs:anyAttribute
NDR 10-1 REF, EXT Complex type has a category
NDR 10-2 REF, EXT Object type with complex content is derived from structures:ObjectType
NDR 10-23 REF Augmentable type has augmentation point element
NDR 10-24 REF, EXT Augmentable type has at most one augmentation point element
NDR 11-19 REF, EXT Element or attribute declaration introduced only once into a type
NDR 11-20 REF, EXT Element reference defined by conformant schema
NDR 11-21 REF, EXT Referenced attribute defined by conformant schemas
NDR 11-22 REF, EXT Schema uses only known attribute groups
NDR 11-44 REF, EXT Standard opening phrase for complex type data definition