Fixed error "used to by" in section 10.4.

Closes #95.

publish/niem-ndr.html

@@ -798,7 +798,7 @@
                       = exists(@name[ends-with(., 'Association')])"
       >An element MUST have a name that ends in 'Association' if and only if it has a type that is an association type.</sch:assert>
   </sch:rule>
-&lt;/sch:pattern&gt;</pre></div><p>Using the qualifier <code>Association</code> immediately identifies an element as representing an association. This document defines the term <a name="d3e10606"></a><a href="#definition_association_type"><span class="termRef">association type</span></a>.</p></div></div></div><div class="section"><div class="heading"><a name="section-augmentations"></a><a name="section_10.4"></a>10.4. Augmentations</div><p>Developers of domain schemas and other schemas that build on and extend the NIEM release schemas need to be able to define additional characteristics of common types. For example, the JXDM domain, which addresses justice and public safety concerns, considers the following elements to be characteristics of a person, as defined by <code>nc:PersonType</code>:</p><ul><li><code>j:PersonMedicalInsuranceIndicator</code></li><li><code>j:PersonProfessionalCertificateText</code></li><li><code>j:PersonSightedIndicator</code></li><li><code>j:PersonFBIIdentification</code></li></ul><p>There are several approaches that could be used to by a domain to add elements to a common type. One method is to have each domain create an extension of <code>nc:PersonType</code> (using <code>xs:extension</code>) that adds elements and attributes for the needed content. Some of the problems with this approach include:</p><ul><li>It results in numerous, domain-specific specializations of <code>nc:PersonType</code>, each with common content and extension-specific content.</li><li>There is no method for the developer of an information exchange package description (IEPD) to bring these types back together into a single type that carries the attributes desired for the IEPD. XML Schema does not support multiple inheritance, so there would be no way to join together <code>nc:PersonType</code>, <code>j:PersonType</code>, and <code>im:PersonType</code>.</li><li>There is no standard or easy way for the developer to express that the various element instances of the various person types represent the same person, or which parts of those instances are required to be populated; does each person restate the name and birth-date, or is that handled by just one instance?</li></ul><p>This approach turns into a morass that is difficult to use and maintain, and which does not scale to support the breadth of the NIEM community.</p><p>To handle this need, NIEM has adopted augmentations. There are several parts that fit together for the definition and use of augmentations:</p><ul><li><p>Each object type and association type carries an augmentation point element, which provides a place for domain- and extension-specific content in the type. Augmentation points are optional in extension schema documents, but must appear in reference schema documents. Augmentation points are also defined for the base types for <a name="d3e10694"></a><a href="#definition_object_type"><span class="termRef">object types</span></a> and <a name="d3e10697"></a><a href="#definition_association_type"><span class="termRef">association types</span></a>:</p><ul><li><code>structures:ObjectType</code> has augmentation point <code>structures:ObjectAugmentationPoint</code>.</li><li><code>structures:AssociationType</code> has augmentation point <code>structures:AssociationAugmentationPoint</code>.</li></ul></li><li>A developer of a domain or other schema that extends common types may define elements that are substitutable for an augmentation point. Each of these elements expresses an additional characteristic or relationship of the base type.</li><li>A developer may also define an augmentation type, and a corresponding augmentation element of that type, which acts as a container of elements that apply to the base type. An augmentation element is defined to be substitutable for an augmentation point, which enables it to appear in instances of that base type.</li><li><p>A developer of an information exchange may choose, through selection and subsetting reference schemas:</p><ul><li>Which types will carry augmentation point elements, and the cardinality (i.e. minOccurs, maxOccurs) of those augmentation point elements</li><li>Which elements will be included that substitute for an augmentation point. Some of these may be direct elements, while others may have an augmentation type, and carry multiple elements for the base type.</li><li>Which elements will be carried within the augmentation types; each of these will apply to its base type.</li></ul></li><li>Augmentation point elements also appear on <code>structures:ObjectType</code> and <code>structures:AssociationType</code>. This allows schema developers to define elements that may be applied to <em>any</em> object or association.</li></ul><p>In addition, a developer may create an extension of a base type and have it carry augmentation elements, in order to avoid element substitution and flexible content models; whether to substitute or concretely use the elements is at the discretion of the developers and implementers of an information exchange.</p><p>The term <a name="d3e10770"></a><a href="#definition_augmentation"><span class="termRef">augmentation</span></a> describes any element in a NIEM-conformant instance XML document that appears as a result of being substituted for an augmentation point element. Such an element may have a type that is an <a name="d3e10773"></a><a href="#definition_augmentation_type"><span class="termRef">augmentation type</span></a>, or it may be a direct element that represents a property.</p><div class="box"><div class="normativeHead"><a name="definition_augmentation"></a>[Definition: <dfn>augmentation</dfn>]</div><div class="sub"><p>An <strong>augmentation</strong> is a <a name="d3e10784"></a><a href="#definition_conformant_element_information_item"><span class="termRef">conformant element information item</span></a> that:</p><ol><li>is an instance of an <a name="d3e10793"></a><a href="#definition_augmentation_element_declaration"><span class="termRef">augmentation element declaration</span></a>,</li><li>is a child of a <a name="d3e10800"></a><a href="#definition_conformant_element_information_item"><span class="termRef">conformant element information item</span></a> that is an instance of an <a name="d3e10803"></a><a href="#definition_augmentable_type"><span class="termRef">augmentable type</span></a>, and</li><li>appears in the instance as a substitution for an augmentation point element.</li></ol></div></div><p>As an example, here is a definition for <code>nc:PersonType</code>, which includes its augmentation point element:</p><div class="figure"><div class="caption"><a name="figure_10-9"></a>Figure 10-9: Definition of augmentable type <code>nc:PersonType</code></div><div class="box"><pre>&lt;xs:complexType name="PersonType"&gt;
+&lt;/sch:pattern&gt;</pre></div><p>Using the qualifier <code>Association</code> immediately identifies an element as representing an association. This document defines the term <a name="d3e10606"></a><a href="#definition_association_type"><span class="termRef">association type</span></a>.</p></div></div></div><div class="section"><div class="heading"><a name="section-augmentations"></a><a name="section_10.4"></a>10.4. Augmentations</div><p>Developers of domain schemas and other schemas that build on and extend the NIEM release schemas need to be able to define additional characteristics of common types. For example, the JXDM domain, which addresses justice and public safety concerns, considers the following elements to be characteristics of a person, as defined by <code>nc:PersonType</code>:</p><ul><li><code>j:PersonMedicalInsuranceIndicator</code></li><li><code>j:PersonProfessionalCertificateText</code></li><li><code>j:PersonSightedIndicator</code></li><li><code>j:PersonFBIIdentification</code></li></ul><p>There are several approaches that could be used by a domain to add elements to a common type. One method is to have each domain create an extension of <code>nc:PersonType</code> (using <code>xs:extension</code>) that adds elements and attributes for the needed content. Some of the problems with this approach include:</p><ul><li>It results in numerous, domain-specific specializations of <code>nc:PersonType</code>, each with common content and extension-specific content.</li><li>There is no method for the developer of an information exchange package description (IEPD) to bring these types back together into a single type that carries the attributes desired for the IEPD. XML Schema does not support multiple inheritance, so there would be no way to join together <code>nc:PersonType</code>, <code>j:PersonType</code>, and <code>im:PersonType</code>.</li><li>There is no standard or easy way for the developer to express that the various element instances of the various person types represent the same person, or which parts of those instances are required to be populated; does each person restate the name and birth-date, or is that handled by just one instance?</li></ul><p>This approach turns into a morass that is difficult to use and maintain, and which does not scale to support the breadth of the NIEM community.</p><p>To handle this need, NIEM has adopted augmentations. There are several parts that fit together for the definition and use of augmentations:</p><ul><li><p>Each object type and association type carries an augmentation point element, which provides a place for domain- and extension-specific content in the type. Augmentation points are optional in extension schema documents, but must appear in reference schema documents. Augmentation points are also defined for the base types for <a name="d3e10694"></a><a href="#definition_object_type"><span class="termRef">object types</span></a> and <a name="d3e10697"></a><a href="#definition_association_type"><span class="termRef">association types</span></a>:</p><ul><li><code>structures:ObjectType</code> has augmentation point <code>structures:ObjectAugmentationPoint</code>.</li><li><code>structures:AssociationType</code> has augmentation point <code>structures:AssociationAugmentationPoint</code>.</li></ul></li><li>A developer of a domain or other schema that extends common types may define elements that are substitutable for an augmentation point. Each of these elements expresses an additional characteristic or relationship of the base type.</li><li>A developer may also define an augmentation type, and a corresponding augmentation element of that type, which acts as a container of elements that apply to the base type. An augmentation element is defined to be substitutable for an augmentation point, which enables it to appear in instances of that base type.</li><li><p>A developer of an information exchange may choose, through selection and subsetting reference schemas:</p><ul><li>Which types will carry augmentation point elements, and the cardinality (i.e. minOccurs, maxOccurs) of those augmentation point elements</li><li>Which elements will be included that substitute for an augmentation point. Some of these may be direct elements, while others may have an augmentation type, and carry multiple elements for the base type.</li><li>Which elements will be carried within the augmentation types; each of these will apply to its base type.</li></ul></li><li>Augmentation point elements also appear on <code>structures:ObjectType</code> and <code>structures:AssociationType</code>. This allows schema developers to define elements that may be applied to <em>any</em> object or association.</li></ul><p>In addition, a developer may create an extension of a base type and have it carry augmentation elements, in order to avoid element substitution and flexible content models; whether to substitute or concretely use the elements is at the discretion of the developers and implementers of an information exchange.</p><p>The term <a name="d3e10770"></a><a href="#definition_augmentation"><span class="termRef">augmentation</span></a> describes any element in a NIEM-conformant instance XML document that appears as a result of being substituted for an augmentation point element. Such an element may have a type that is an <a name="d3e10773"></a><a href="#definition_augmentation_type"><span class="termRef">augmentation type</span></a>, or it may be a direct element that represents a property.</p><div class="box"><div class="normativeHead"><a name="definition_augmentation"></a>[Definition: <dfn>augmentation</dfn>]</div><div class="sub"><p>An <strong>augmentation</strong> is a <a name="d3e10784"></a><a href="#definition_conformant_element_information_item"><span class="termRef">conformant element information item</span></a> that:</p><ol><li>is an instance of an <a name="d3e10793"></a><a href="#definition_augmentation_element_declaration"><span class="termRef">augmentation element declaration</span></a>,</li><li>is a child of a <a name="d3e10800"></a><a href="#definition_conformant_element_information_item"><span class="termRef">conformant element information item</span></a> that is an instance of an <a name="d3e10803"></a><a href="#definition_augmentable_type"><span class="termRef">augmentable type</span></a>, and</li><li>appears in the instance as a substitution for an augmentation point element.</li></ol></div></div><p>As an example, here is a definition for <code>nc:PersonType</code>, which includes its augmentation point element:</p><div class="figure"><div class="caption"><a name="figure_10-9"></a>Figure 10-9: Definition of augmentable type <code>nc:PersonType</code></div><div class="box"><pre>&lt;xs:complexType name="PersonType"&gt;
   &lt;xs:annotation&gt;
     &lt;xs:documentation&gt;A data type for a human being.&lt;/xs:documentation&gt;
   &lt;/xs:annotation&gt;

publish/niem-ndr.txt

@@ -3768,7 +3768,7 @@ Rule 10-22. Association element type is an association type
 
       *  j:PersonFBIIdentification
 
-   There are several approaches that could be used to by a domain to add elements to a common type. One method is to have each domain create an extension of nc:PersonType (using xs:extension) that adds elements and attributes for the needed content. Some of the problems with this approach include:
+   There are several approaches that could be used by a domain to add elements to a common type. One method is to have each domain create an extension of nc:PersonType (using xs:extension) that adds elements and attributes for the needed content. Some of the problems with this approach include:
 
       *  It results in numerous, domain-specific specializations of nc:PersonType, each with common content and extension-specific content.
 

src/ndr-doc.xml.m4

@@ -5384,7 +5384,7 @@ m4_dnl   MACRO_HAS_DATA_DEFINITION(Schema, sch, xs:schema, A schema document ele
           <li><p><qName>j:PersonFBIIdentification</qName></p></li>
         </ul>
 
-        <p>There are several approaches that could be used to by a domain to add elements to a common type. One
+        <p>There are several approaches that could be used by a domain to add elements to a common type. One
           method is to have each domain create an extension of <qName>nc:PersonType</qName>
           (using <qName>xs:extension</qName>) that adds elements and attributes for the needed content. Some of
           the problems with this approach include:</p>