Release 1.0 metaschema adjustments (#1065)

* Many fixes to the constraints in the OSCAL metaschemas to repair broken Metapaths. * fixing defects in metaschema constraints * Updating to latest Metaschema toolchain. Removed use of the "require" constraint. * updating readme with current links
usnistgov · Dec 9, 2021 · ade0245 · ade0245
1 parent 0f619b3
commit ade0245
Show file tree

Hide file tree

Showing 7 changed files with 45 additions and 67 deletions.
diff --git a/build/metaschema b/build/metaschema
diff --git a/src/metaschema/oscal_assessment-common_metaschema.xml b/src/metaschema/oscal_assessment-common_metaschema.xml
@@ -1677,17 +1677,15 @@
          <!-- <any/> -->
       </model>
       <constraint>
-         <require when="@name='assessment'">
-            <allowed-values target="prop/@name" allow-other="yes">
-               <enum value="method">The assessment method to use. This typically appears on parts with the name "assessment".</enum>
-            </allowed-values>
-            <has-cardinality target="prop[@name='method']" min-occurs="1"/>
-            <allowed-values target="prop[@name='method']/@value">
-               <enum value="INTERVIEW">The process of holding discussions with individuals or groups of individuals within an organization to once again, facilitate assessor understanding, achieve clarification, or obtain evidence.</enum>
-               <enum value="EXAMINE">The process of reviewing, inspecting, observing, studying, or analyzing one or more assessment objects (i.e., specifications, mechanisms, or activities).</enum>
-               <enum value="TEST">The process of exercising one or more assessment objects (i.e., activities or mechanisms) under specified conditions to compare actual with expected behavior.</enum>
-            </allowed-values>
-         </require>
+         <allowed-values target=".[@name='objective']/prop/@name" allow-other="yes">
+            <enum value="method">The assessment method to use. This typically appears on parts with the name "objective".</enum>
+         </allowed-values>
+         <has-cardinality target=".[@name='objective']/prop[@name='method']" min-occurs="1"/>
+         <allowed-values target=".[@name='objective']/prop[@name='method']/@value">
+            <enum value="INTERVIEW">The process of holding discussions with individuals or groups of individuals within an organization to once again, facilitate assessor understanding, achieve clarification, or obtain evidence.</enum>
+            <enum value="EXAMINE">The process of reviewing, inspecting, observing, studying, or analyzing one or more assessment objects (i.e., specifications, mechanisms, or activities).</enum>
+            <enum value="TEST">The process of exercising one or more assessment objects (i.e., activities or mechanisms) under specified conditions to compare actual with expected behavior.</enum>
+         </allowed-values>
       </constraint>
       <remarks>
          <p>A <code>part</code> provides for logical partitioning of prose, and can be thought of as a grouping structure (e.g., section). A <code>part</code> can have child parts allowing for arbitrary nesting of prose content (e.g., statement hierarchy). A <code>part</code> can contain <code>prop</code> objects that allow for enriching prose text with structured name/value information.</p>

diff --git a/src/metaschema/oscal_catalog_metaschema.xml b/src/metaschema/oscal_catalog_metaschema.xml
@@ -166,7 +166,7 @@
                   <!-- <any/> -->
             </model>
             <constraint>
-                  <has-cardinality target="part[@name='statement']" min-occurs="1" max-occurs="1" />
+                  <has-cardinality id="catalog-control-require-statement-when-not-withdrawn" target=".[not(exists(prop[@name='status'])) or prop[@name='status']/@value != 'withdrawn']/part[@name='statement']" min-occurs="1" max-occurs="1" />
                   <allowed-values target="prop/@name" allow-other="yes">
             &allowed-values-control-group-property-name;
                         <enum value="status">The status of a <code>control</code>. For example, a value of 'withdrawn' can indicate that the <code>control</code> has been withdrawn and should no longer be used.</enum>

diff --git a/src/metaschema/oscal_control-common_metaschema.xml b/src/metaschema/oscal_control-common_metaschema.xml
@@ -84,17 +84,15 @@
                         <allowed-values target="prop/@name" allow-other="yes">
             &allowed-values-control-group-property-name;
                         </allowed-values>
-                        <require when="@name='assessment'">
-                                <allowed-values target="prop/@name" allow-other="yes">
-                                        <enum value="method">The assessment method to use. This typically appears on parts with the name "assessment".</enum>
-                                </allowed-values>
-                                <has-cardinality target="prop[@name='method']" min-occurs="1"/>
-                                <allowed-values target="prop[@name='method']/@value">
-                                        <enum value="INTERVIEW">The process of holding discussions with individuals or groups of individuals within an organization to once again, facilitate assessor understanding, achieve clarification, or obtain evidence.</enum>
-                                        <enum value="EXAMINE">The process of reviewing, inspecting, observing, studying, or analyzing one or more assessment objects (i.e., specifications, mechanisms, or activities).</enum>
-                                        <enum value="TEST">The process of exercising one or more assessment objects (i.e., activities or mechanisms) under specified conditions to compare actual with expected behavior.</enum>
-                                </allowed-values>
-                        </require>
+                        <allowed-values target=".[@name='assessment']/prop/@name" allow-other="yes">
+                                <enum value="method">The assessment method to use. This typically appears on parts with the name "assessment".</enum>
+                        </allowed-values>
+                        <has-cardinality target=".[@name='assessment']/prop[@name='method']" min-occurs="1"/>
+                        <allowed-values target=".[@name='assessment']/prop[@name='method']/@value">
+                                <enum value="INTERVIEW">The process of holding discussions with individuals or groups of individuals within an organization to once again, facilitate assessor understanding, achieve clarification, or obtain evidence.</enum>
+                                <enum value="EXAMINE">The process of reviewing, inspecting, observing, studying, or analyzing one or more assessment objects (i.e., specifications, mechanisms, or activities).</enum>
+                                <enum value="TEST">The process of exercising one or more assessment objects (i.e., activities or mechanisms) under specified conditions to compare actual with expected behavior.</enum>
+                        </allowed-values>
                 </constraint>
                 <remarks>
                         <p>A <code>part</code> provides for logical partitioning of prose, and can be thought of as a grouping structure (e.g., section). A <code>part</code> can have child parts allowing for arbitrary nesting of prose content (e.g., statement hierarchy). A <code>part</code> can contain <code>prop</code> objects that allow for enriching prose text with structured name/value information.</p>

diff --git a/src/metaschema/oscal_metadata_metaschema.xml b/src/metaschema/oscal_metadata_metaschema.xml
@@ -125,7 +125,7 @@
             </define-field>
             <field ref="published" />
             <field ref="last-modified"/>
-            <field ref="version"/>
+            <field ref="version" min-occurs="1"/>
             <field ref="oscal-version"/>
             <assembly ref="property" max-occurs="unbounded">
                 <group-as name="props" in-json="ARRAY"/>
@@ -136,7 +136,9 @@
             <field ref="remarks" in-xml="WITH_WRAPPER"/>
         </model>
         <constraint>
-            <has-cardinality target="published|last-modified|version|link[@rel='canonical']" min-occurs="1"/>
+<!-- TODO: consider making this a warning
+            <has-cardinality target="published|last-modified|link[@rel='canonical']" min-occurs="1"/>
+-->
             <allowed-values target="link/@rel" allow-other="yes">
                 <enum value="canonical">The link identifies the authoritative location for this file. Defined by <a href="https://tools.ietf.org/html/rfc6596">RFC 6596</a>.</enum>
                 <enum value="alternate">The link identifies an alternative location or format for this file. Defined by <a href="https://html.spec.whatwg.org/multipage/links.html#linkTypes">the HTML Living Standard</a></enum>
@@ -252,7 +254,7 @@
         </define-flag>
         <model>
             <!-- CHANGE: changed from "party-name" to "name" -->
-            <define-field name="name" min-occurs="1">
+            <define-field name="name">
                 <formal-name>Party Name</formal-name>
                 <description>The full name of the party. This is typically the legal name associated with the party.</description>
             </define-field>
@@ -541,13 +543,11 @@
                             </p>
                         </remarks>
                     </is-unique>
-                    <require when="citation">
-                        <has-cardinality target="title" min-occurs="1">
-                            <remarks>
-                                <p>A <code>title</code> is required when a citation is provided.</p>
-                            </remarks>
-                        </has-cardinality>
-                    </require>
+                    <has-cardinality target=".[citation]/title" min-occurs="1">
+                        <remarks>
+                            <p>A <code>title</code> is required when a citation is provided.</p>
+                        </remarks>
+                    </has-cardinality>
                 </constraint>
                 <remarks>
                     <p>A resource can be used in two ways. 1) it may point to an specific retrievable network resource using a <code>rlink</code>, or 2) it may be included as an attachment using a <code>base64</code>. A resource may contain multiple <code>rlink</code> and <code>base64</code> entries that represent alternative download locations (rlink) and attachments (base64) for the same resource. Both rlink and base64 allow for a <code>media-type</code> to be specified, which is used to distinguish between different representations of the same resource (e.g., Microsoft Word, PDF). When multiple <code>rlink</code> and <code>base64</code> items are included for a given resource, all items must contain equivalent information. This allows the document consumer to choose a preferred item to process based on a the selected item's <code>media-type</code>. This is extremely important when the items represent OSCAL content that is represented in alternate formats (i.e., XML, JSON, YAML), allowing the same OSCAL data to be processed from any of the available formats indicated by the items.</p>
@@ -669,17 +669,11 @@
             </define-field>
         </model>
         <constraint>
-            <require when="@rel=('reference')">
-                <require when="starts-with(@href,'#')">
-                    <matches target="@href" datatype="uri-reference"/>
-                    <index-has-key name="index-back-matter-resource" target=".">
-                        <key-field target="@href" pattern="#(.*)"/>
-                    </index-has-key>
-                </require>
-                <require when="not(starts-with(@href,'#'))">
-                    <matches target="@href" datatype="uri"/>
-                </require>
-            </require>
+            <matches target=".[@rel=('reference') and starts-with(@href,'#')]/@href" datatype="uri-reference"/>
+            <index-has-key name="index-back-matter-resource" target=".[@rel=('reference') and starts-with(@href,'#')]">
+                <key-field target="@href" pattern="#(.*)"/>
+            </index-has-key>
+            <matches target=".[@rel=('reference') and not(starts-with(@href,'#'))]/@href" datatype="uri"/>
         </constraint>
         <remarks>
             <p>To provide a cryptographic hash for a remote target resource, a local reference to a back matter <code>resource</code> is needed. The resource allows one or more hash values to be provided using the <code>rlink/hash</code> object.</p>

diff --git a/src/metaschema/oscal_profile_metaschema.xml b/src/metaschema/oscal_profile_metaschema.xml
@@ -91,15 +91,8 @@
             <model>
                   <assembly ref="combine"/>
                   <choice>
-                        <define-assembly name="flat" min-occurs="1">
-                              <formal-name>Flat</formal-name>
-                              <description>Use the flat structuring method.</description>
-                        </define-assembly>
-                        <define-field name="as-is" as-type="boolean" min-occurs="1">
-                              <formal-name>As is</formal-name>
-                              <description>An As-is element indicates that the controls should be structured in resolution as they are structured in their source catalogs. It does not contain any elements or attributes.</description>
-                        </define-field>
-                        <assembly ref="custom" min-occurs="1"/>
+                        <field ref="as-is"/>
+                        <assembly ref="custom"/>
                   </choice>
             </model>
             <remarks>
@@ -116,7 +109,10 @@
                   <p>This setting permits a profile designer to apply a rule for the resolution of such cases. In a well-designed profile, such collisions would ordinarily be avoided, but this setting can be useful for defining what to do when it occurs.</p>
             </remarks>
       </define-assembly>
-
+      <define-field name="as-is" as-type="boolean">
+            <formal-name>As is</formal-name>
+            <description>An As-is element indicates that the controls should be structured in resolution as they are structured in their source catalogs. It does not contain any elements or attributes.</description>
+      </define-field>
       <define-flag name="method" as-type="string">
             <formal-name>Combination method</formal-name>
             <description>How clashing controls should be handled</description>
@@ -250,14 +246,6 @@
                                     </assembly>
                               </choice>
                         </model>
-                        <constraint>
-                              <is-unique id="unique-profile-modify-set-parameter" target="set-parameter">
-                                    <key-field target="@param-id"/>
-                                    <remarks>
-                                          <p>Since multiple <code>set-parameter</code> entries can be provided, each parameter must be set only once.</p>
-                                    </remarks>
-                              </is-unique>
-                        </constraint>
                   </define-assembly>
                   <assembly ref="alter" max-occurs="unbounded">
                         <group-as name="alters" in-json="ARRAY"/>
@@ -438,7 +426,7 @@
             <constraint>
                   <allowed-values>
                         <enum value="yes">Include child controls with an included control.</enum>
-                        <enum value="no">(default) When importing a control, only include child controls that are also explicitly called.</enum>
+                        <enum value="no">When importing a control, only include child controls that are also explicitly called.</enum>
                   </allowed-values>
             </constraint>
       </define-flag>

diff --git a/src/utils/util/readme.md b/src/utils/util/readme.md
@@ -1,10 +1,10 @@
 # OSCAL Utilities
 
-Current best tooling for OSCAL can be found listed on our web site:
+The OSCAL project maintains [a list of tools for OSCAL on our web site](https://pages.nist.gov/OSCAL/tools/ "OSCAL tools page").
 
-See in particular the repository at https://github.com/usnistgov/oscal-tools
+Additionally, we maintain a repository of tools at https://github.com/usnistgov/oscal-tools; and members of the community offer OSCAL tools, frequently in open repositories free to use, which we do not maintain.
 
-Functionality maintained here includes:
+Functionality archived here includes:
 
 `resolver-pipeline` a demonstration implementation of OSCAL Profile resolution.