Add the with-parent-controls for #1662. (#1717)

aj-stein-nist · wendellpiez · web-flow · commit 5f16e76b8bb0 · 2023-03-30T13:34:56.000-04:00
* with-parent-controls for import only for #1662 Add it for insert-controls, but not exclusion or merge, based upon team review and analysis of current profile resolution specification. * Clarify spec for #1662. * Apply suggestions from code review Co-authored-by: Wendell Piez <wendell.piez@nist.gov> * Update src/specifications/profile-resolution/profile-resolution-specml.xml * Apply suggestions from code review Co-authored-by: Wendell Piez <wendell.piez@nist.gov> --------- Co-authored-by: Wendell Piez <wendell.piez@nist.gov>
diff --git a/src/metaschema/oscal_profile_metaschema.xml b/src/metaschema/oscal_profile_metaschema.xml
@@ -81,13 +81,24 @@
                                     <p>Identifies that all controls are to be included from the imported catalog or profile.</p>
                               </remarks>
                         </assembly>
-                        <assembly ref="select-control-by-id" min-occurs="1" max-occurs="unbounded">
-                              <use-name>include-controls</use-name>
-                              <group-as name="include-controls" in-json="ARRAY"/>
+                        <define-assembly name="include-controls" min-occurs="1" max-occurs="unbounded">
+                              <formal-name>Select Control</formal-name>
+                              <description>Select a control or controls from an imported control set.</description>
+                              <flag ref="with-child-controls"/>
+                              <flag ref="with-parent-controls"/>
+                              <model>
+                                    <field ref="with-id" max-occurs="unbounded">
+                                          <group-as name="with-ids" in-json="ARRAY"/>
+                                    </field>
+                                    <assembly ref="matching" max-occurs="unbounded">
+                                          <group-as name="matching" in-json="ARRAY"/>
+                                    </assembly>
+                              </model>
                               <remarks>
-                                    <p>Identifies a subset of controls to import from the referenced catalog or profile by control identifier or match pattern.</p>
+                                    <p>If <code>with-child-controls</code> is <q>yes</q> on the call to a control, any controls appearing within it (child controls) will be selected, with no additional <code>call</code> directives required. This flag provides a way to include controls with all their dependent controls (enhancements) without having to call them individually.</p>
+                                   <p>If with-parent-controls is "yes" on the call to a control, it will not be selected and removed from (shown without) a parent control, but instead will be copied with its parent in the source. This flag provides a way to include controls with all their ancestor controls (enhancements) without having to call them individually.</p>
                               </remarks>
-                        </assembly>
+                        </define-assembly>
                   </choice>
                   <assembly ref="select-control-by-id" max-occurs="unbounded">
                         <use-name>exclude-controls</use-name>
@@ -444,18 +455,12 @@
             <description>Select a control or controls from an imported control set.</description>
             <flag ref="with-child-controls"/>
             <model>
-                  <define-field name="with-id" as-type="token" max-occurs="unbounded">
-                        <formal-name>Match Controls by Identifier</formal-name>
-                        <description>Selecting a control by its ID given as a literal.</description>
+                  <field ref="with-id" max-occurs="unbounded">
                         <group-as name="with-ids" in-json="ARRAY"/>
-                  </define-field>
-                  <define-assembly name="matching" max-occurs="unbounded">
-                        <formal-name>Match Controls by Pattern</formal-name>
-                        <description>Selecting a set of controls by matching their IDs with a
-                              wildcard pattern.</description>
+                  </field>
+                  <assembly ref="matching" max-occurs="unbounded">
                         <group-as name="matching" in-json="ARRAY"/>
-                        <flag ref="pattern"/>
-                  </define-assembly>
+                  </assembly>
             </model>
             <remarks>
                   <p>If <code>with-child-controls</code> is <q>yes</q> on the call to a control, no sibling <code>call</code>elements need to be used to call any controls appearing within it. Since generally, this is how control enhancements are represented (as controls within controls), this provides a way to include controls with all their dependent controls (enhancements) without having to call them individually.</p>
@@ -471,8 +476,27 @@
                   </allowed-values>
             </constraint>
       </define-flag>
+      <define-flag as-type="token" name="with-parent-controls">
+            <formal-name>Include Parent Controls with Control</formal-name>
+            <description>When a control is included, whether its parent (ancestor) controls are also included.</description>
+            <constraint>
+                  <allowed-values>
+                        <enum value="yes">Include parent controls with an included control.</enum>
+                        <enum value="no">When importing a control, only include parent controls that are also explicitly called.</enum>
+                  </allowed-values>
+            </constraint>
+      </define-flag>
       <define-flag as-type="string" name="pattern">
             <formal-name>Pattern</formal-name>
             <description>A <a href="https://en.wikipedia.org/wiki/Glob_(programming)">glob expression</a> matching the IDs of one or more controls to be selected.</description>
       </define-flag>
+      <define-field name="with-id" as-type="token">
+            <formal-name>Match Controls by Identifier</formal-name>
+            <description>Selecting a control by its ID given as a literal.</description>
+      </define-field>
+      <define-assembly name="matching">
+            <formal-name>Match Controls by Pattern</formal-name>
+            <description>Selecting a set of controls by matching their IDs with a wildcard pattern.</description>
+            <flag ref="pattern"/>
+      </define-assembly>
 </METASCHEMA>
diff --git a/src/specifications/profile-resolution/profile-resolution-specml.xml b/src/specifications/profile-resolution/profile-resolution-specml.xml
@@ -532,7 +532,7 @@ include-controls:
         </p>
         <section id="include-child-controls">
           <head>with-child-controls</head>
-          <p>Child controls are, for the most part, treated the same as top level controls: they can be explicitly included using the selection directives above. As a shortcut to manually including all of the desired descendant controls of a given control, OSCAL provides the <code>with-child-controls</code> option. <code>with-child-controls</code> appears as a child object under a given inclusion directive, and defines additional behavior that is to be executed alongside the parent inclusion.</p>
+          <p>When a control is selected, any child controls can be included by means the <code>with-child-controls</code> flag. This provides an alternative to selecting child or descendant controls explicitly by <code>id</code> or match. <code>with-child-controls</code> appears as a child object under a given inclusion directive and defines behaviors listed below.</p>
           <p><req level="must" id="req-with-child-controls-yes">A
             <src>with-child-controls: yes</src> directive on an
             <src>include-controls</src> indicates that
@@ -549,11 +549,7 @@ include-controls:
         </section>
         <section id="include-parent-controls">
           <head>with-parent-controls</head>
-          <p>Although similar to the above
-            <src>with-child-controls</src>, the optional
-            <src>with-parent-controls</src> applies to parents of the included control, and has the opposite default behavior. In order to maintain the structure of the source catalog, profile resolution includes all parents of an included control by default. If a profile author wants to change this structure, they should use an exclude directive that lists all of the undesired parents. As a shortcut for this,
-            <src>with-parent-controls</src> provides the following functionality:
-          </p>
+          <p>The the optional <src>with-parent-controls</src> flag defines behavior applicable to parents or ancestors (a parent's parent etc.) of the included control, in cases of nested controls. <src>with-parent-controls</src> appears as a child object under a given inclusion directive and defines the behaviors listed below. Its semantics assume that nesting of controls indicates logical dependencies in catalogs, which should be retained unless a profile specifically indicates otherwise.</p>
           <p><req level="must" id="req-with-parent-controls-yes">A
             <src>with-parent-controls: yes</src> directive on an
             <src>include-controls</src> indicates that
