Add possible Schematron documentation checks

.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@3cea5372237819ed00197afe530f5a7ea3e805c8
       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

build/ci-cd/validate-metaschema.sh

@@ -96,14 +96,23 @@ fi
 
 # compile the schematron
 metaschema_toolchain="${OSCALDIR}/build/metaschema/toolchains/xslt-M4"
-schematron="${metaschema_toolchain}/validate/metaschema-composition-check.sch"
-compiled_schematron="${metaschema_toolchain}/validate/metaschema-composition-check-compiled.xsl"
+composition_check_schematron="${metaschema_toolchain}/validate/metaschema-composition-check.sch"
+documentation_check_schematron="${OSCALDIR}/src/utils/schematron/oscal-documentation.sch"
+compiled_composition_check_schematron="${metaschema_toolchain}/validate/metaschema-composition-check-compiled.xsl"
+compiled_documentation_check_schematron="${SCRATCH_DIR}/oscal-documentation.xsl"
 metaschema_xsd="${OSCALDIR}/build/metaschema/schema/xml/metaschema.xsd"
 
-build_schematron "$schematron" "$compiled_schematron"
+build_schematron "$composition_check_schematron" "$compiled_composition_check_schematron"
 cmd_exitcode=$?
 if [ $cmd_exitcode -ne 0 ]; then
-  echo -e "${P_ERROR}Compilation of Schematron '${P_END}${schematron}${P_ERROR}' failed.${P_END}"
+  echo -e "${P_ERROR}Compilation of Schematron '${P_END}${composition_check_schematron}${P_ERROR}' failed.${P_END}"
+  exit 1
+fi
+
+build_schematron "$documentation_check_schematron" "$compiled_documentation_check_schematron"
+cmd_exitcode=$?
+if [ $cmd_exitcode -ne 0 ]; then
+  echo -e "${P_ERROR}Compilation of Schematron '${P_END}${documentation_check_schematron}${P_ERROR}' failed.${P_END}"
   exit 1
 fi
 
@@ -137,26 +146,39 @@ while IFS="|" read path gen_schema gen_converter gen_docs || [[ -n "$path" ]]; d
       echo -e "${P_ERROR}XML Schema validation failed for metaschema '${P_END}${metaschema_relative}${P_ERROR}'.${P_END}"
       echo -e "${P_ERROR}${result}${P_END}"
       exitcode=1
+    fi
+
+    svrl_result="$SCRATCH_DIR/svrl/composition_check_${metaschema/$OSCALDIR\/src\//}.svrl"
+    svrl_result_dir=${svrl_result%/*}
+    mkdir -p "$svrl_result_dir"
+    result=$(validate_with_schematron "$compiled_composition_check_schematron" "$metaschema" "$svrl_result")
+    cmd_exitcode=$?
+    if [ $cmd_exitcode -ne 0 ]; then
+      echo -e "${P_ERROR}Schematron composition validation failed for metaschema '${P_END}${metaschema_relative}${P_ERROR}'.${P_END}"
+        echo -e "${P_ERROR}${result}${P_END}"
+        exitcode=1
     else
-      svrl_result="$SCRATCH_DIR/svrl/${metaschema/$OSCALDIR\/src\//}.svrl"
-      svrl_result_dir=${svrl_result%/*}
-      mkdir -p "$svrl_result_dir"
-      result=$(validate_with_schematron "$compiled_schematron" "$metaschema" "$svrl_result")
-      cmd_exitcode=$?
-      if [ $cmd_exitcode -ne 0 ]; then
-        echo -e "${P_ERROR}Schematron validation failed for metaschema '${P_END}${metaschema_relative}${P_ERROR}'.${P_END}"
-          echo -e "${P_ERROR}${result}${P_END}"
-          exitcode=1
-      else
-        echo -e "${P_OK}XML Schema and Schematron validation passed for '${P_END}${metaschema_relative}${P_OK}'.${P_END}"
-      fi
+      echo -e "${P_OK}Schematron composition validation passed for '${P_END}${metaschema_relative}${P_OK}'.${P_END}"
+    fi
+
+    svrl_result="$SCRATCH_DIR/svrl/documentation_check_${metaschema/$OSCALDIR\/src\//}.svrl"
+    svrl_result_dir=${svrl_result%/*}
+    mkdir -p "$svrl_result_dir"
+    result=$(validate_with_schematron "$compiled_documentation_check_schematron" "$metaschema" "$svrl_result")
+    cmd_exitcode=$?
+    if [ $cmd_exitcode -ne 0 ]; then
+      echo -e "${P_ERROR}Schematron documentation validation failed for metaschema '${P_END}${metaschema_relative}${P_ERROR}'.${P_END}"
+        echo -e "${P_ERROR}${result}${P_END}"
+        exitcode=1
+    else
+      echo -e "${P_OK}All XML Schema and Schematron validation passed for '${P_END}${metaschema_relative}${P_OK}'.${P_END}"
     fi
   done
 done < $OSCALDIR/build/ci-cd/config/metaschema
 shopt -u nullglob
 shopt -u globstar
 
 # cleanup compiled schematron
-rm -f "$compiled_schematron"
+rm -f "$compiled_composition_check_schematron"
 
 exit $exitcode

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>

src/utils/schematron/oscal-documentation.sch

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<sch:schema xmlns:sch="http://purl.oclc.org/dsdl/schematron" queryBinding="xslt2"
+    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+    xmlns:m="http://csrc.nist.gov/ns/oscal/metaschema/1.0"
+    xmlns:nm="http://csrc.nist.gov/ns/metaschema"
+    xmlns:sqf="http://www.schematron-quickfix.com/validator/process"
+    xmlns:oscal="http://csrc.nist.gov/ns/oscal/1.0">
+
+    <sch:ns uri="http://csrc.nist.gov/ns/oscal/metaschema/1.0" prefix="m"/>
+    <sch:ns uri="http://csrc.nist.gov/ns/metaschema" prefix="nm"/>
+
+    <sch:pattern>
+        <sch:rule context="m:description">
+            <sch:assert role="error" test="ends-with(.,'.')" id="description-ends-with-dot">Description should end with a period.</sch:assert>
+            <sch:assert role="error" test="string-length(.) gt 6" id="description-long-enough">Description is too short.</sch:assert>
+        </sch:rule>
+    </sch:pattern>
+</sch:schema>