Adjusted documentation based on feedback from @iMichaela

src/metaschema/examples/cis-sp-800-53-mapping.xml

@@ -7,16 +7,17 @@
         <title>Example mapping between CIS controls and SP 800-53 rev5</title>
         <last-modified>2022-04-13T08:37:21.323321800-04:00</last-modified>
         <version>0.0.1</version>
-        <oscal-version>1.0.3</oscal-version>
+        <oscal-version>1.1.0</oscal-version>
     </metadata>
     <mapping uuid="9eb2019c-f3be-4f96-947e-58876a46b2a9">
         <source-resource type="catalog" href="#a84961de-55ae-4bf3-a2d3-86cc32b651af"></source-resource>
         <target-resource type="catalog" href="#711085f6-c390-4b25-b5f1-30066a56073d"></target-resource>
         <map uuid="6a9a1161-770e-4556-9740-41e1809e14ea">
-            <relationship>equivalent-to</relationship>
+            <!-- Note: Once issue #1332 is resolved, one of the new relationships can be used, in place of subset-of, to represent that cis-1.1 is a stricter version of the same requirements defined by the combination of {cm-8 and cm-8.1}. -->
+            <relationship>subset-of</relationship>
             <source type="control" id-ref="#cis-1.1"/>
             <target type="control" id-ref="#cm-8">
-                <!-- TODO: consider a way to reference parameters allowing the review period of at least bi-annually to be described -->
+                <!-- TODO: consider a way to reference parameters allowing the review period of at least bi-annually to be described. This would allow for equivalent-to to be used. -->
                 <!-- <using-param id="cm-08_odp.02">at least bi-annually</using-param>-->
             </target>
             <target type="control" id-ref="#cm-8.1"/>

src/metaschema/oscal_mapping-common_metaschema.xml

@@ -12,7 +12,7 @@
 
     <define-assembly name="map">
         <formal-name>Mapping Entry</formal-name>
-        <description>An individual entry that is part of a larger mapping.</description>
+        <description>A relationship-based mapping between a source and target set consisting of members (i.e., controls, control statements) from the respective source and target.</description>
         <define-flag name="uuid" as-type="uuid" required="yes">
             <formal-name>Mapping Entry Identifier</formal-name>
             <description>The unique identifier for the mapping entry.</description>
@@ -26,7 +26,7 @@
             </assembly>
             <define-field name="relationship" as-type="token" min-occurs="1">
                 <formal-name>Mapping Entry Relationship</formal-name>
-                <description>The relationship type for the mapping entry.</description>
+                <description>The relationship type for the mapping entry, which describes the relationship between the effective requirements of the specified source and target sets.</description>
                 <define-flag name="ns" as-type="uri">
                     <formal-name>Relationship Value Namespace</formal-name>
                     <description>A namespace qualifying the relationship's value. This allows different organizations to associate distinct semantics for relationships with the same name.</description>
@@ -37,11 +37,11 @@
                 </define-flag>
                 <constraint>
                     <allowed-values target=".[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]">
-                        <enum value="equivalent-to">The source is equivalent in semantic meaning to the target. The words may differ, but both mapped elements have the same effective meaning.</enum>
-                        <enum value="equal-to">The source is the same as the target. Differences in capitalization, spelling, and grammar can be ignored, if these differences do not change the meaning.</enum>
-                        <enum value="subset-of">The source is a semantic subset of the target.</enum>
-                        <enum value="superset-of">The source is a semantic superset of the target.</enum>
-                        <enum value="intersects-with">The source and target have some semantic equivalence, but not all effective requirements from each are contained within the other. Statement level mapping using 'equivalent-to', 'subset-of', and/or 'superset-of' may provide a richer mapping that using this relationship type.</enum>
+                        <enum value="equivalent-to">The effective requirements of the source is equivalent in semantic meaning to the effective requirements of the target. The words may differ, but both mapped sets convey similar information with the same effective meaning. This relationship may be reversed, since `A equivalent-to B` also means that `B equivalent-to A`.</enum>
+                        <enum value="equal-to">The actual requirements of the source are the same as the actual requirements target. Differences in capitalization, spelling, and grammar can be ignored, if these differences do not change the meaning. This relationship may be reversed, since `A equal-to B` also means that `B equal-to A`.</enum>
+                        <enum value="subset-of">The effective requirements of the source is a semantic subset of the effective requirements of the target. This relationship may be reversed as a `superset-of`, since `A subset-of B` also means that `B superset-of A`.</enum>
+                        <enum value="superset-of">The effective requirements of the source is a semantic superset of the effective requirements of the target. This relationship may be reversed as a `subset-of`, since `A superset-of B` also means that `B subset-of A`.</enum>
+                        <enum value="intersects-with">The effective requirements of the source and target have some semantic equivalence, but not all effective requirements from each are contained within the other. This relationship may be reversed, since `A intersects-with B` also means that `B intersects-with A`. A lower granularity mapping, such as a statement level mapping using 'equivalent-to', 'subset-of', and/or 'superset-of', may provide a more functional mapping that allows for more inference than using this relationship type.</enum>
                     </allowed-values>
                 </constraint>
                 <remarks>

src/metaschema/oscal_mapping_metaschema.xml

@@ -22,7 +22,7 @@
 
       <define-assembly name="mapping-collection">
             <formal-name>Mapping Collection</formal-name>
-            <description>A collection of control mappings.</description>
+            <description>A collection of relationship-based control and/or control statement mappings.</description>
             <root-name>mapping-collection</root-name>
             <define-flag name="uuid" as-type="uuid" required="yes">
                   <formal-name>Mapping Collection Universally Unique Identifier</formal-name>
@@ -40,13 +40,16 @@
                         </remarks>
                   </assembly>
             </model>
+            <remarks>
+                  <p>A mapping collection affirmatively declares the relationships that exist between sets of controls and/or control statements in a source and target. It is expected that inferences can be made based on what is mapped; however, no inferences should be made based on what is not mapped, since it is impossible to quantify how complete or granular a given mapping is.</p>
+            </remarks>
       </define-assembly>
       <define-assembly name="mapping">
             <formal-name>Control Mapping</formal-name>
             <description>A mapping between two target resources.</description>
             <define-flag name="uuid" as-type="uuid" required="yes">
                   <formal-name>Mapping Universally Unique Identifier</formal-name>
-                  <description>A <a href="/concepts/identifier-use/#machine-oriented">machine-oriented</a>, <a href="/concepts/identifier-use/#globally-unique">globally unique</a> identifier with <a href="/concepts/identifier-use/#cross-instance">cross-instance</a> scope that can be used to reference this mapping definition elsewhere in this or other OSCAL instances. The locally defined <em>UUID</em> of the <code>mapping</code> can be used to reference the data item locally or globally (e.g., in an imported OSCAL instance). This UUID should be assigned <a href="/concepts/identifier-use/#consistency">per-subject</a>, which means it should be consistently used to identify the same subject across revisions of the document.</description>
+                  <description>A <a href="/concepts/identifier-use/#machine-oriented">machine-oriented</a>, <a href="/concepts/identifier-use/#globally-unique">globally unique</a> identifier with <a href="/concepts/identifier-use/#cross-instance">cross-instance</a> scope that can be used to reference this mapping definition elsewhere in this or other OSCAL instances. The locally defined <em>UUID</em> of the <code>mapping</code> can be used to reference the data item locally or globally (e.g., in an imported OSCAL instance). This UUID should be assigned <a href="/concepts/identifier-use/#consistency">per-subject</a>, which means it should be consistently used to identify the same mapping across revisions of the document.</description>
             </define-flag>
             <model>
                   <assembly ref="mapping-resource-reference" min-occurs="1">