Adapters

Adapters are the mechanism NIEM uses to allow content from external standards without causing conformance validation errors.

An adapter is a type that contains an external property. It is marked as an adapter in the schema so that NIEM conformance rules skip over its external (non-conformant) contents instead of throwing errors. Otherwise, an adapter type looks and acts like a standard NIEM type.

geo:SurfaceType is an adapter type in NIEM that contains element Surface from GML, an external standard. It can be used normally by other NIEM components. Because it is an adapter type, NDR conformance tests will not throw errors if the element from the GML external standard does not follow NIEM rules.

Adapter image

Modeling guidance

Adapter flag

An adapter type must have attribute appinfo:externalAdapterTypeIndicator with a value of true in its schema declaration.

Parent type

An adapter type must extend structures:ObjectType.

External content

The sub-properties from an adapter type must be from external namespaces.

An adapter type simply wraps external content; it should not be used to build larger objects. Other NIEM types may be created that combine regular content with elements that have adapter types.

Extra documentation

NIEM requires that all namespaces and components be documented. Because external standards might not have this documentation, or might not have this documentation in a consistent manner as NIEM, NIEM requires all usages of external namespaces and components to be documented.

No extensions

Adapter types may not be extended by other types. Each adapter type is meant to represent a single concept from an external namespace and stand alone.

No external ID attributes

NIEM defines structures:id to enable references between components. For consistency, the use of external attributes with an ID type is not allowed so as not to bypass this standard mechanism.

IEPD exceptions

External attributes

In an extension namespace, a non-adapter type is allowed to directly contain a reference to an external attribute as long as a definition is also provided with the reference.

XML

XML example

Adapters appear in XML instances like other content.

<nc:LocationArea>
  <nc:LocationArea>
    <geo:Ellipse>    <!-- NIEM element with an adapter type -->
      <xls:Ellipse>  <!-- External element from GML -->
        <!-- GML content -->
      </xls:Ellipse>
    </geo:Ellipse>
  </nc:LocationArea>
</nc:Location>

XML Schema example

The following is a subset from the Geospatial adapter schema in the NIEM 4.0 release.

  • The import statement of the GML external namespace includes a definition and attribute appinfo:externalImportIndicator="true".
  • The complex type declaration is an adapter type, with attribute appinfo:externalAdapterTypeIndicator="true.
  • The reference to the external element gml:AbstractGeometry also includes a definition.
  • Nothing special is required by the element below that uses this adapter type. The type can now be used like any other type.
<xs:schema xmlns:gml="http://www.opengis.net/gml/3.2" ...>
  <xs:import schemaLocation="../../../external/ogc/gml/3.2.1/gml.xsd" namespace="http://www.opengis.net/gml/3.2" appinfo:externalImportIndicator="true">
    <xs:annotation>
      <xs:documentation>Geography Markup Language (GML) version 3.2.1 schemas...</xs:documentation>
    </xs:annotation>
  </xs:import>

  <xs:complexType name="GeometryType" appinfo:externalAdapterTypeIndicator="true">
    <xs:annotation>
      <xs:documentation>A data type that encapsulates a GML geometry element.</xs:documentation>
    </xs:annotation>
    <xs:complexContent>
      <xs:extension base="structures:ObjectType">
        <xs:sequence>
          <xs:element ref="gml:AbstractGeometry" minOccurs="1" maxOccurs="1">
            <xs:annotation>
              <xs:documentation>The AbstractGeometry element is the abstract head of the substitution group for all geometry elements of GML. This includes ...</xs:documentation>
            </xs:annotation>
          </xs:element>
        </xs:sequence>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>

  <xs:element name="Geometry" type="geo:GeometryType" nillable="true">
    <xs:annotation>
      <xs:documentation>A general-purpose GML geometry adapter.</xs:documentation>
    </xs:annotation>
  </xs:element>

</xs:schema>

XML Schema template

<xs:schema>
  <xs:import schemaLocation="PATH" namespace="URI" appinfo:externalImportIndicator="true">
    <xs:annotation>
      <xs:documentation>EXTERNAL NAMESPACE DEFINITION</xs:documentation>
    </xs:annotation>
  </xs:import>

  <xs:complexType name="NAMEType" appinfo:externalAdapterTypeIndicator="true">
    <xs:annotation>
      <xs:documentation>DEFINITION</xs:documentation>
    </xs:annotation>
    <xs:complexContent>
      <xs:extension base="structures:ObjectType">
        <xs:sequence>
          <xs:element ref="EXTERNAL_ELEMENT" minOccurs="1" maxOccurs="1">
            <xs:annotation>
              <xs:documentation>EXTERNAL_ELEMENT_DEFINITION</xs:documentation>
            </xs:annotation>
          </xs:element>
        </xs:sequence>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>

</xs:schema>

JSON

Guidance is not yet available for adapters and the use of external standards in JSON.

NDR references

NDR 5.0
Rule Applicability Title
NDR 10-8 REF, EXT External adapter type has indicator
NDR 10-9 REF, EXT Structure of external adapter type definition follows pattern
NDR 10-10 REF, EXT Element use from external adapter type defined by external schema documents
NDR 10-11 REF, EXT External adapter type not a base type
NDR 10-12 SET External adapter type not a base type
NDR 10-13 REF External attribute use only in external adapter type
NDR 10-14 REF, EXT External attribute use has data definition
NDR 10-15 SET External attribute use not an ID
NDR 10-16 REF, EXT External element use has data definition
NDR 10-71 REF, EXT External adapter type indicator annotates complex type
NDR 10-72 REF, EXT appinfo:appliesToTypes annotates metadata element
NDR 10-73 SET appinfo:appliesToTypes references types
NDR 10-74 REF, EXT appinfo:appliesToElements annotates metadata element
NDR 10-75 SET appinfo:appliesToElements references elements
NDR 4.0
Rule Applicability Title
NDR 10-8 REF, EXT External adapter type has indicator
NDR 10-9 REF, EXT Structure of external adapter type definition follows pattern
NDR 10-10 REF, EXT Element use from external adapter type defined by external schema documents
NDR 10-11 REF, EXT External adapter type not a base type
NDR 10-12 SET External adapter type not a base type
NDR 10-13 REF External attribute use only in external adapter type
NDR 10-14 REF, EXT External attribute use has data definition
NDR 10-15 SET External attribute use not an ID
NDR 10-16 REF, EXT External element use has data definition
NDR 10-70 REF, EXT External adapter type indicator annotates complex type
NDR 10-71 REF, EXT appinfo:appliesToTypes annotates metadata element
NDR 10-72 SET appinfo:appliesToTypes references types
NDR 10-73 REF, EXT appinfo:appliesToElements annotates metadata element
NDR 10-74 SET appinfo:appliesToElements references elements