POAM related finding support, fixes #1120 (#1478)

* Add related finding assembly. #1120
* Add finding assembly to support related-findings, also moved finding to assessment common from assessment result metaschema.
* Accept suggestion to revise description.

Co-authored-by: Alexander Stein <alexander.stein@nist.gov>

src/metaschema/oscal_assessment-common_metaschema.xml

@@ -786,6 +786,72 @@
       </model>
    </define-assembly>
 
+   <define-assembly name="finding">
+      <formal-name>Finding</formal-name>
+      <description>Describes an individual finding.</description>
+      <define-flag name="uuid" required="yes" as-type="uuid">
+        <formal-name>Finding Universally Unique Identifier</formal-name>
+        <!-- Identifier Declaration -->
+        <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 finding in <a href="/concepts/identifier-use/#ar-identifiers">this or other OSCAL instances</a>. The locally defined <em>UUID</em> of the <code>finding</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>
+      </define-flag>
+      <model>
+        <define-field name="title" min-occurs="1" as-type="markup-line">
+          <formal-name>Finding Title</formal-name>
+          <description>The title for this finding.</description>
+        </define-field>
+        <!-- CHANGE: Added WITH_WRAPPER to description -->
+        <define-field name="description" min-occurs="1" in-xml="WITH_WRAPPER" as-type="markup-multiline">
+          <formal-name>Finding Description</formal-name>
+          <description>A human-readable description of this finding.</description>
+        </define-field>
+
+        <assembly ref="property" max-occurs="unbounded">
+          <group-as name="props" in-json="ARRAY"/>
+        </assembly>
+        <assembly ref="link" max-occurs="unbounded">
+          <group-as name="links" in-json="ARRAY"/>
+        </assembly>
+
+        <assembly ref="origin" max-occurs="unbounded">
+          <group-as name="origins" in-json="ARRAY"/>
+          <remarks>
+            <p>Used to identify the individual and/or tool generated this finding.</p>
+          </remarks>
+        </assembly>
+        <assembly ref="finding-target" min-occurs="1">
+          <use-name>target</use-name>
+        </assembly>
+        <define-field name="implementation-statement-uuid" as-type="uuid" min-occurs="0" max-occurs="1">
+          <formal-name>Implementation Statement UUID</formal-name>
+          <!-- Identifier Reference -->
+          <description>A <a href="/concepts/identifier-use/#machine-oriented">machine-oriented</a> identifier reference to the implementation statement in the SSP to which this finding is related.</description>
+        </define-field>
+        <!-- CHANGED: replaced embedded observation with references -->
+        <define-assembly name="related-observation" max-occurs="unbounded">
+          <formal-name>Related Observation</formal-name>
+          <description>Relates the finding to a set of referenced observations that were used to determine the finding.</description>
+          <group-as name="related-observations" in-json="ARRAY"/>
+          <define-flag name="observation-uuid" as-type="uuid" required="yes">
+            <formal-name>Observation Universally Unique Identifier Reference</formal-name>
+            <!-- Identifier Reference -->
+            <description>A <a href="/concepts/identifier-use/#machine-oriented">machine-oriented</a> identifier reference to an observation defined in the list of observations.</description>
+          </define-flag>
+        </define-assembly>
+        <!-- CHANGED: replaced "risk" with new "assciated-risk" -->
+        <define-assembly name="associated-risk" max-occurs="unbounded">
+          <formal-name>Associated Risk</formal-name>
+          <description>Relates the finding to a set of referenced risks that were used to determine the finding.</description>
+          <group-as name="related-risks" in-json="ARRAY"/>
+          <define-flag name="risk-uuid" as-type="uuid" required="yes">
+            <formal-name>Risk Universally Unique Identifier Reference</formal-name>
+            <!-- Identifier Reference -->
+            <description>A <a href="/concepts/identifier-use/#machine-oriented">machine-oriented</a> identifier reference to a risk defined in the list of risks.</description>
+          </define-flag>
+        </define-assembly>
+        <field ref="remarks" in-xml="WITH_WRAPPER" min-occurs="0" max-occurs="1"/>
+      </model>
+   </define-assembly>
+
    <define-assembly name="observation">
       <formal-name>Observation</formal-name>
       <description>Describes an individual observation.</description>

src/metaschema/oscal_assessment-results_metaschema.xml

@@ -248,71 +248,7 @@
     </model>
   </define-assembly>
 
-  <define-assembly name="finding">
-    <formal-name>Finding</formal-name>
-    <description>Describes an individual finding.</description>
-    <define-flag name="uuid" required="yes" as-type="uuid">
-      <formal-name>Finding Universally Unique Identifier</formal-name>
-      <!-- Identifier Declaration -->
-      <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 finding in <a href="/concepts/identifier-use/#ar-identifiers">this or other OSCAL instances</a>. The locally defined <em>UUID</em> of the <code>finding</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>
-    </define-flag>
-    <model>
-      <define-field name="title" min-occurs="1" as-type="markup-line">
-        <formal-name>Finding Title</formal-name>
-        <description>The title for this finding.</description>
-      </define-field>
-      <!-- CHANGE: Added WITH_WRAPPER to description -->
-      <define-field name="description" min-occurs="1" in-xml="WITH_WRAPPER" as-type="markup-multiline">
-        <formal-name>Finding Description</formal-name>
-        <description>A human-readable description of this finding.</description>
-      </define-field>
-
-      <assembly ref="property" max-occurs="unbounded">
-        <group-as name="props" in-json="ARRAY"/>
-      </assembly>
-      <assembly ref="link" max-occurs="unbounded">
-        <group-as name="links" in-json="ARRAY"/>
-      </assembly>
-
-      <assembly ref="origin" max-occurs="unbounded">
-        <group-as name="origins" in-json="ARRAY"/>
-        <remarks>
-          <p>Used to identify the individual and/or tool generated this finding.</p>
-        </remarks>
-      </assembly>
-      <assembly ref="finding-target" min-occurs="1">
-        <use-name>target</use-name>
-      </assembly>
-      <define-field name="implementation-statement-uuid" as-type="uuid" min-occurs="0" max-occurs="1">
-        <formal-name>Implementation Statement UUID</formal-name>
-        <!-- Identifier Reference -->
-        <description>A <a href="/concepts/identifier-use/#machine-oriented">machine-oriented</a> identifier reference to the implementation statement in the SSP to which this finding is related.</description>
-      </define-field>
-      <!-- CHANGED: replaced embedded observation with references -->
-      <define-assembly name="related-observation" max-occurs="unbounded">
-        <formal-name>Related Observation</formal-name>
-        <description>Relates the finding to a set of referenced observations that were used to determine the finding.</description>
-        <group-as name="related-observations" in-json="ARRAY"/>
-        <define-flag name="observation-uuid" as-type="uuid" required="yes">
-          <formal-name>Observation Universally Unique Identifier Reference</formal-name>
-          <!-- Identifier Reference -->
-          <description>A <a href="/concepts/identifier-use/#machine-oriented">machine-oriented</a> identifier reference to an observation defined in the list of observations.</description>
-        </define-flag>
-      </define-assembly>
-      <!-- CHANGED: replaced "risk" with new "assciated-risk" -->
-      <define-assembly name="associated-risk" max-occurs="unbounded">
-        <formal-name>Associated Risk</formal-name>
-        <description>Relates the finding to a set of referenced risks that were used to determine the finding.</description>
-        <group-as name="related-risks" in-json="ARRAY"/>
-        <define-flag name="risk-uuid" as-type="uuid" required="yes">
-          <formal-name>Risk Universally Unique Identifier Reference</formal-name>
-          <!-- Identifier Reference -->
-          <description>A <a href="/concepts/identifier-use/#machine-oriented">machine-oriented</a> identifier reference to a risk defined in the list of risks.</description>
-        </define-flag>
-      </define-assembly>
-      <field ref="remarks" in-xml="WITH_WRAPPER" min-occurs="0" max-occurs="1"/>
-    </model>
-  </define-assembly>
+  <!-- Moved Finding Assembly to Assessment Common -->
 
   <!-- Assessment Plan Import -->
   <define-assembly name="import-ap">

src/metaschema/oscal_poam_metaschema.xml

@@ -44,6 +44,9 @@
             <assembly ref="risk" min-occurs="0" max-occurs="unbounded">
                 <group-as name="risks" in-json="ARRAY"/>
             </assembly>
+            <assembly ref="finding" min-occurs="0" max-occurs="unbounded">
+                <group-as name="findings" in-json="ARRAY"/>
+            </assembly>
             <assembly ref="poam-item" min-occurs="1" max-occurs="unbounded">
                 <!-- CHANGED: removed the top-level "poam-items" -->
                 <!-- CHANGED: "poam-item-group" to "poam-items" -->
@@ -129,6 +132,16 @@
                 </remarks>
             </define-assembly>
 
+            <define-assembly name="related-finding" min-occurs="0" max-occurs="unbounded">
+                <formal-name>Related Finding</formal-name>
+                <description>Relates the poam-item to referenced finding(s).</description>
+                <group-as name="related-findings" in-json="ARRAY"/>
+                <define-flag name="finding-uuid" as-type="uuid" required="yes">
+                    <formal-name>Finding Universally Unique Identifier Reference</formal-name>
+                    <description>A <a href="/concepts/identifier-use/#machine-oriented">machine-oriented</a> identifier reference to a finding defined in the list of findings.</description>
+                </define-flag>
+            </define-assembly>
+
             <!-- TODO: add link; check in the other assessment models -->
             <!-- CHANGED: removed "collected" and "expires" (moved to observation) by brianrufgsa -->
             <!-- CHANGED: removed "objective-status" per brianrufgsa -->