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 <[email protected]> Co-authored-by: Rene Rene Tshiteya <[email protected]> Co-authored-by: Wendell Piez <[email protected]> Add CI/CD checking of Schematron doc standards checking. Always zip and upload Schematron validation results for potential debug.
aj-stein-nist · Oct 31, 2022 · ef8fa01 · ef8fa01
1 parent ef62215
commit ef8fa01
Show file tree

Hide file tree

Showing 3 changed files with 69 additions and 17 deletions.
diff --git a/.github/workflows/workflow-generate-metaschema-resources.yml b/.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

diff --git a/build/ci-cd/validate-metaschema.sh b/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
diff --git a/src/utils/schematron/oscal-documentation.sch b/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>