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

Augmentation Pattern

Augmentations are used in NIEM as a replacement for xsd:extension in cases where no new specialized object needs to be created. For example, if a domain has additional conveyance-related properties not already contained in or inherited by nc:ConveyanceType, that domain will create a conveyance augmentation rather than a conveyance extension. This augmentation can be substituted for the augmentation point already contained in nc:ConveyanceType (nc:ConveyanceAugmentationPoint), so the new domain conveyance properties can be reused everywhere nc:ConveyanceType occurs throughout NIEM.

The augmentation technique prevents the need for type substitution in IEPD instances in order to use additional properties on existing types. It also allows IEPDs to use augmentations from more than one domain together, which could not be done with type extension.

Type extension is still used for specialization. For example, NIEM Core 3.0 defines three specializations of nc:ConveyanceType - nc:AircraftType, nc:VehicleType, and nc:VesselType. An aircraft-specific property would not belong with the more general nc:ConveyanceType, so a new Aircraft object type extending nc:ConveyanceType is created instead.

Note that augmentation elements are defined but not reused in NIEM domains. Reuse occurs only in IEPDs via element substitution.

Variable Replacement Table

Variable Description Usage NDR Reference
{$Name} Association element / type name Required NDR Rule 7-5: Component naming
NDR Section 10.8: Naming Rules
{$Definition} Augmentation element / type definition Required NDR Rule 9-25: Complex type has definition
NDR Rule 9-36: Element has definition
NDR Section 11.6.1: Human-readable documentation
{$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    

Augmentation Type and Element Declaration

<xs:complexType name="{$Name}AugmentationType">
    <xs:annotation>
      <xs:documentation>A data type for additional information about {$Definition}</xs:documentation>
    </xs:annotation>
    <xs:complexContent>
      <xs:extension base="structures:AugmentationType">
        <xs:sequence>
          <xs:element ref="{$ElementName}" minOccurs="{$Min}" maxOccurs="{$Max}"/>
        </xs:sequence>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>

  <xs:element name="{$Name}Augmentation" type="{$Name}AugmentationType" substitutionGroup="{$Name}AugmentationPoint">
    <xs:annotation>
      <xs:documentation>Additional information about {$Definition}</xs:documentation>
    </xs:annotation>
  </xs:element>

Example