1. Home
  2. IEPD Starter Kit
  3. Reusable XML Snippets
  4. Role Pattern

Role Pattern

NIEM differentiates between an object and a role of an object. Role is used here to mean a non-exclusive function or part played by an object, and an object may have one or more roles.

NIEM uses XSD extension for cases of exclusive specialization. In NIEM Core, an aircraft is a special kind of conveyance, a vehicle is a special kind of conveyance, and a vessel is a special kind of conveyance. A conveyance would not function as one of those exclusively (generally speaking, the exceptions are not a common use case). A person, on the other hand, may act in several different roles based on context. One person may act as an enforcement official and as a witness (both defined in the Justice domain), and as a caregiver (defined in the CYFS domain) as well. Because these functions of a person are not exclusive, they are defined as roles rather than extensions.

Note that in order to preserve simplicity when possible, NIEM only creates role types when there are role-specifc properties to add. In the 3.1 release, the Justice domain has enforcement official-specific properties and witness-specific properties, so new role types are created for these. Alternately in the same release, the CYFS domain has a caregiver, but since they have no caregiver-specific properties to add, no new role type is created. Element cyfs:Caregiver reuses nc:Person directly for its data type.

Variable Replacement Table

Variable Description Usage NDR Reference
{$RoleOfName} The role-of element representing the object
Example - nc:RoleOfPerson		 Required; begins with "RoleOf"
Do not create new role-of element if existing one from NIEM can be used, such as nc:RoleOfPerson, nc:RoleOfOrganization, or nc:RoleOfItem		 RoleOf Element Definition
NDR Rule 10-5: RoleOf elements indicate the base types of a role type
{$RoleOfDataType} The object type
Example - nc:PersonType		 Required for new role-of element NDR Rule 10-3: RoleOf element type is an object type
{$RoleOfElementDefinition} Definition of the role-of element Required for new role-of element NDR Section 11.6.1: Human-readable documentation
{$RoleType} A non-exclusive function or part played by an object.
Example - j:EnforcementOfficialType		 Required
Do not create if there are no role-specific properties ({$ElementName}) to add		 Role Type Definition
NDR Rule 7-5: Component naming
NDR Section 10.8: Naming Rules
{$RoleTypeDefinition} Definition of the role Required NDR Section 11.6.1: Human-readable documentation
{$Parent} QName of the parent type "structures:ObjectType" or other NIEM type
Note that this cannot be the same as {$RoleOfDataType}.
For example, you would not want to extend nc:PersonType and contain nc:RoleOfPerson - person elements would be duplicated.		 Rule 10-2 Complex object types are derived from structures:ObjectType
{$ElementName} The QName of the element referenced Required
Repeat element ref line for each sub-property		  
{$Min} The minimum number of allowed element occurrences within the type    
{$Max} The maximum number of allowed element occurrences within the type    

Role-of Element and Role Type Declarations

<xs:element name="{$RoleOfName}" type="{$RoleOfDataType}" substitutionGroup="nc:RoleOf">
    <xs:annotation>
      <xs:documentation>A(n) {$RoleOfElementDefinition}</xs:documentation>
    </xs:annotation>
  </xs:element>

  <xs:complexType name="{$RoleType}">
    <xs:annotation>
      <xs:documentation>
        A data type for a property item used as {$RoleTypeDefinition}.
      </xs:documentation>
    </xs:annotation>
    <xs:complexContent>
      <xs:extension base="{$Parent}">
        <xs:sequence>
          <xs:element ref="{$RoleOfName}" minOccurs="{$Min}" maxOccurs="{$Max}"/>
          <xs:element ref="{$ElementName}" minOccurs="{$Min}" maxOccurs="{$Max}"/>
        </xs:sequence>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>

Example