From ef8fa01879358d5ef3a64ccfd83b4912d4a5fe27 Mon Sep 17 00:00:00 2001 From: Alexander Stein Date: Tue, 11 Oct 2022 12:52:45 -0400 Subject: [PATCH] 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/OSCAL#801. Co-authored-by: Chris Compton Co-authored-by: Rene Rene Tshiteya Co-authored-by: Wendell Piez Add CI/CD checking of Schematron doc standards checking. Always zip and upload Schematron validation results for potential debug. --- ...workflow-generate-metaschema-resources.yml | 12 ++++ build/ci-cd/validate-metaschema.sh | 56 +++++++++++++------ src/utils/schematron/oscal-documentation.sch | 18 ++++++ 3 files changed, 69 insertions(+), 17 deletions(-) create mode 100644 src/utils/schematron/oscal-documentation.sch diff --git a/.github/workflows/workflow-generate-metaschema-resources.yml b/.github/workflows/workflow-generate-metaschema-resources.yml index cd3eab594c..1b963e9e6d 100644 --- 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 index 50a4fbf4dc..7c2152eef0 100755 --- 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,19 +146,32 @@ 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 @@ -157,6 +179,6 @@ 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 new file mode 100644 index 0000000000..70ab1ecfa0 --- /dev/null +++ b/src/utils/schematron/oscal-documentation.sch @@ -0,0 +1,18 @@ + + + + + + + + + Description should end with a period. + Description is too short. + + + \ No newline at end of file