Add possible Schematron documentation checks (usnistgov#1501)

* Add possible Schematron documentation checks

This is the product of the meeting and spike where we pair-programmed
and came up with example Schematron rules for tentative editorial
standards that can be used for reviews of models and embedded docs as
part of usnistgov#801.

Co-authored-by: Chris Compton <chris.compton@nist.gov>
Co-authored-by: Rene Rene Tshiteya <rene-claude.tshiteya@gsa.gov>
Co-authored-by: Wendell Piez <wendell.piez@nist.gov>

Add CI/CD checking of Schematron doc standards checking.
Always zip and upload Schematron validation results for potential debug.

* After, show the Schematron checks passing after Metaschema def fixes.

* Revert validate-metaschema.sh changes.

* Revert refactored Schematron and remove from PR.

* Update metaschema module to include updated Schematron in usnistgov/metaschema#246.

Co-authored-by: David Waltermire <david.waltermire@nist.gov>

.github/workflows/workflow-generate-metaschema-resources.yml

@@ -119,12 +119,24 @@ jobs:
       run: |
         zip ${{ runner.temp }}/metaschema-artifacts.zip -r xml/schema/*.xsd json/schema/*.json xml/convert/*.xsl json/convert/*.xsl
       working-directory: ${{ env.CHECKOUT_PATH }}
+    - name: Zip Schematron Validation Results for Debugging
+      if: always()
+      run: |
+        zip ${{ runner.temp }}/schematron-validations.zip -r ${{ runner.temp }} build/metaschema/toolchains/xslt-M4/validate/metaschema-composition-check-compiled.xsl
+      working-directory: ${{ env.CHECKOUT_PATH }}
     - uses: actions/upload-artifact@83fd05a356d7e2593de66fc9913b3002723633cb
       with:
         name: schemas-and-converters
         path: |
           ${{ runner.temp }}/metaschema-artifacts.zip
         retention-days: 5
+    - uses: actions/upload-artifact@3cea5372237819ed00197afe530f5a7ea3e805c8
+      if: always()
+      with:
+        name: schematron-validation-reports
+        path: |
+          ${{ runner.temp }}/schematron-validations.zip
+        retention-days: 5
     # Store Built Artifacts
     # ---------------
     - name: Publish Schemas and Converters

src/metaschema/oscal_control-common_metaschema.xml

@@ -6,7 +6,7 @@
    <!ENTITY allowed-values-control-group-property-name SYSTEM "./shared-constraints/allowed-values-control-group-property-name.ent">
 ]>
 <?xml-stylesheet type="text/css" href="metaschema-author.css"?>
-<METASCHEMA xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+<METASCHEMA
         xmlns="http://csrc.nist.gov/ns/oscal/metaschema/1.0" abstract="yes">
         <schema-name>OSCAL Control Catalog Format -- Common Models</schema-name>
         <schema-version>1.0.4</schema-version>

src/metaschema/oscal_ssp_metaschema.xml

@@ -30,7 +30,7 @@
   <!-- ############################################## -->
   <define-assembly name="system-security-plan">
     <formal-name>System Security Plan (SSP)</formal-name>
-    <description>A system security plan, such as those described in NIST SP 800-18</description>
+    <description>A system security plan, such as those described in NIST SP 800-18.</description>
     <root-name>system-security-plan</root-name>
     <define-flag name="uuid" as-type="uuid" required="yes">
       <formal-name>System Security Plan Universally Unique Identifier</formal-name>
@@ -106,8 +106,7 @@
       <field ref="date-authorized"/>
       <define-field name="security-sensitivity-level" min-occurs="1">
         <formal-name>Security Sensitivity Level</formal-name>
-        <description>The overall information system sensitivity categorization, such as defined by <a href="https://doi.org/10.6028/NIST.FIPS.199">FIPS-199</a>.
-        </description>
+        <description>The overall information system sensitivity categorization, such as defined by <a href="https://doi.org/10.6028/NIST.FIPS.199">FIPS-199</a>.</description>
         <remarks>
           <p>Often, organizations require the security sensitivity level to correspond with the highest confidentiality, integrity, or availability level identified by <code>security-impact-level</code>.
           </p>
@@ -181,8 +180,7 @@
   </define-assembly>
   <define-assembly name="system-information">
     <formal-name>System Information</formal-name>
-    <description>Contains details about all information types that are stored, processed, or transmitted by the system, such as privacy information, and those defined in <a href="https://doi.org/10.6028/NIST.SP.800-60v2r1">NIST SP 800-60</a>.
-    </description>
+    <description>Contains details about all information types that are stored, processed, or transmitted by the system, such as privacy information, and those defined in <a href="https://doi.org/10.6028/NIST.SP.800-60v2r1">NIST SP 800-60</a>.</description>
     <model>
       <assembly ref="property" max-occurs="unbounded">
         <group-as name="props" in-json="ARRAY"/>
@@ -192,8 +190,7 @@
       </assembly>
       <define-assembly name="information-type" min-occurs="1" max-occurs="unbounded">
         <formal-name>Information Type</formal-name>
-        <description>Contains details about one information type that is stored, processed, or transmitted by the system, such as privacy information, and those defined in <a href="https://doi.org/10.6028/NIST.SP.800-60v2r1">NIST SP 800-60</a>.
-        </description>
+        <description>Contains details about one information type that is stored, processed, or transmitted by the system, such as privacy information, and those defined in <a href="https://doi.org/10.6028/NIST.SP.800-60v2r1">NIST SP 800-60</a>.</description>
         <group-as name="information-types" in-json="ARRAY"/>
         <define-flag name="uuid" as-type="uuid">
           <formal-name>Information Type Universally Unique Identifier</formal-name>
@@ -535,8 +532,7 @@
       </assembly>
       <define-assembly name="leveraged-authorization" max-occurs="unbounded">
         <formal-name>Leveraged Authorization</formal-name>
-        <description>A description of another authorized system from which this system inherits capabilities that satisfy security requirements. Another term for this concept is a <em>common control provider</em>.
-        </description>
+        <description>A description of another authorized system from which this system inherits capabilities that satisfy security requirements. Another term for this concept is a <em>common control provider</em>.</description>
         <group-as name="leveraged-authorizations" in-json="ARRAY"/>
         <define-flag name="uuid" as-type="uuid" required="yes">
           <formal-name>Leveraged Authorization Universally Unique Identifier</formal-name>