Update Schematron Model and Processor to use new/updated Schematron Error Messages from APHL (#624)

BradySkylight · web-flow · commit b1b0ffe45c48 · 2026-06-11T11:39:23.000-06:00
## Description During testing APHL was able to find that many eICRs that should have been processed by TTC did not and were marked as 'No Schematron Errors to process' essentially. This was due to a mis-match in the Schematron Error Messages between what was being used in APHL's pipeline and the TTC code base. We received new Schematron files with updated ids and messages. I have updated the Schematron Model to use the new/update Schematron Error Messages. Tests were updated as well. We will have another ticket/PR to change from using the Error Message to using the AssertionID in the near future (this is already a WIP). ## Related Issues Closes #623 ## Additional Notes ## Checklist for Reviewers Please review and complete the following checklist during the review process: - [ ] The code follows best practices and conventions. - [ ] The changes implement the desired functionality or fix the reported issue. - [ ] The tests cover the new changes and pass successfully. - [ ] Any potential edge cases or error scenarios have been considered.
diff --git a/e2e/assets/eicr_test/eicr_test_schematron_errors.xml b/e2e/assets/eicr_test/eicr_test_schematron_errors.xml
@@ -8,7 +8,7 @@
     <Results xmlns="urn:gov:nist:cdaGuideValidator">
         <validationResult xmlns="">
             <issue severity="errors">
-                <message>Text to Code: Lab Test Name Ordered does not have a @code attribute</message>
+                <message>Text to Code: Planned observation code data element has no @code attribute</message>
                 <context>
                     /ClinicalDocument/component[1]/structuredBody[1]/component[1]/section[1]/entry[1]/observation[1]</context>
                 <test> not(cda:code) or cda:code/@code or cda:code/cda:translation/@code</test>
diff --git a/e2e/assets/namespace_preservation/namespace_preservation_schematron_errors.xml b/e2e/assets/namespace_preservation/namespace_preservation_schematron_errors.xml
@@ -160,7 +160,7 @@
             <issue severity="text_to_code">
                 <assertionID>ttc-labTestNameResulted-noCode</assertionID>
                 <flag/>
-                <message>Text to Code: Lab Test Name Resulted does not have a @code attribute</message>
+                <message>Text to Code: Lab Test Name Resulted does not have a @code attribute.</message>
                 <context>/ClinicalDocument[1]/component[1]/structuredBody[1]/component[6]/section[1]/entry[1]/organizer[1]/component[1]/observation[1]</context>
                 <test>           not(cda:code)           or cda:code/@code           or cda:code/cda:translation/@code</test>
                 <specification/>
diff --git a/e2e/assets/sample7/eICR_Sample7_nullFlavorResultValues_schematron_errors.xml b/e2e/assets/sample7/eICR_Sample7_nullFlavorResultValues_schematron_errors.xml
@@ -284,7 +284,7 @@
         <issue severity="text_to_code">
             <assertionID>ttc-labTestNameResulted-noCode</assertionID>
             <flag/>
-            <message>Text to Code: Lab Test Name Resulted does not have a @code attribute</message>
+            <message>Text to Code: Lab Test Name Resulted does not have a @code attribute.</message>
             <context>/ClinicalDocument[1]/component[1]/structuredBody[1]/component[8]/section[1]/entry[1]/organizer[1]/component[1]/observation[1]</context>
             <test>                 not(cda:code)                  or cda:code/@code                 or cda:code/cda:translation/@code</test>
             <specification/>
diff --git a/e2e/snapshots/test_e2e/test_upload_and_process/augmentation_metadata.json b/e2e/snapshots/test_e2e/test_upload_and_process/augmentation_metadata.json
@@ -1 +1,22 @@
-{"original_eicr_id": "c8516bdc-8bb2-40aa-8dae-20a77546488f", "augmented_eicr_id": "d44dc1c6-8a0c-5236-906e-12f6475589ec", "nonstandard_codes": [{"schematron_error": "Text to Code: Lab Test Name Ordered does not have a @code attribute", "schematron_error_xpath": "\n                    /ClinicalDocument/component[1]/structuredBody[1]/component[1]/section[1]/entry[1]/observation[1]", "field_type": "Lab Test Name Ordered", "new_translation": {"code": "82041-5", "code_system": "2.16.840.1.113883.6.1", "code_system_name": "LOINC", "display_name": "Weed Allerg Mix3 IgE Qn", "value_set": null, "value_set_version": null, "original_text": "A custom code in display name."}, "new_translation_xpath": "/ClinicalDocument/component/structuredBody/component/section/entry/observation/code/translation"}], "error": null}
+{
+    "original_eicr_id": "c8516bdc-8bb2-40aa-8dae-20a77546488f",
+    "augmented_eicr_id": "d44dc1c6-8a0c-5236-906e-12f6475589ec",
+    "nonstandard_codes": [
+        {
+            "schematron_error": "Text to Code: Planned observation code data element has no @code attribute",
+            "schematron_error_xpath": "\n                    /ClinicalDocument/component[1]/structuredBody[1]/component[1]/section[1]/entry[1]/observation[1]",
+            "field_type": "Lab Test Name Ordered",
+            "new_translation": {
+                "code": "82041-5",
+                "code_system": "2.16.840.1.113883.6.1",
+                "code_system_name": "LOINC",
+                "display_name": "Weed Allerg Mix3 IgE Qn",
+                "value_set": null,
+                "value_set_version": null,
+                "original_text": "A custom code in display name."
+            },
+            "new_translation_xpath": "/ClinicalDocument/component/structuredBody/component/section/entry/observation/code/translation"
+        }
+    ],
+    "error": null
+}
diff --git a/packages/text-to-code-lambda/tests/assets/test_schematron_errors.xml b/packages/text-to-code-lambda/tests/assets/test_schematron_errors.xml
@@ -8,7 +8,7 @@
     <Results xmlns="urn:gov:nist:cdaGuideValidator">
         <validationResult xmlns="">
             <issue severity="errors">
-                <message>Text to Code: Lab Test Name Ordered does not have a @code attribute</message>
+                <message>Text to Code: Planned observation code data element has no @code attribute</message>
                 <context>
                     /ClinicalDocument/component[1]/structuredBody[1]/component[1]/section[1]/entry[1]/observation[1]</context>
                 <test> not(cda:code) or cda:code/@code or cda:code/cda:translation/@code</test>
diff --git a/packages/text-to-code-lambda/tests/snapshots/test_lambda_function/test_handler_adds_unmatched_error_when_selected_candidate_has_no_opensearch_hits/no_opensearch_hits_none_metadata_output.json b/packages/text-to-code-lambda/tests/snapshots/test_lambda_function/test_handler_adds_unmatched_error_when_selected_candidate_has_no_opensearch_hits/no_opensearch_hits_none_metadata_output.json
@@ -24,7 +24,7 @@
       "field_type": "Lab Test Name Ordered",
       "issue_context": "/ClinicalDocument/component[1]/structuredBody[1]/component[1]/section[1]/entry[1]/observation[1]",
       "issue_id": null,
-      "issue_message": "Text to Code: Lab Test Name Ordered does not have a @code attribute",
+      "issue_message": "Text to Code: Planned observation code data element has no @code attribute",
       "issue_test": "not(cda:code) or cda:code/@code or cda:code/cda:translation/@code",
       "new_translation": null,
       "opensearch_retrieved_scores": {
diff --git a/packages/text-to-code-lambda/tests/snapshots/test_lambda_function/test_handler_continues_when_selected_candidate_is_none/continues_selected_candidate_none_metadata_output.json b/packages/text-to-code-lambda/tests/snapshots/test_lambda_function/test_handler_continues_when_selected_candidate_is_none/continues_selected_candidate_none_metadata_output.json
@@ -20,7 +20,7 @@
       "field_type": "Lab Test Name Ordered",
       "issue_context": "/ClinicalDocument/component[1]/structuredBody[1]/component[1]/section[1]/entry[1]/observation[1]",
       "issue_id": null,
-      "issue_message": "Text to Code: Lab Test Name Ordered does not have a @code attribute",
+      "issue_message": "Text to Code: Planned observation code data element has no @code attribute",
       "issue_test": "not(cda:code) or cda:code/@code or cda:code/cda:translation/@code",
       "new_translation": null,
       "opensearch_retrieved_scores": null,
diff --git a/packages/text-to-code-lambda/tests/snapshots/test_lambda_function/test_handler_reranker_returns_empty/reranker_returns_empty_ttc_metadata_output.json b/packages/text-to-code-lambda/tests/snapshots/test_lambda_function/test_handler_reranker_returns_empty/reranker_returns_empty_ttc_metadata_output.json
@@ -24,7 +24,7 @@
       "field_type": "Lab Test Name Ordered",
       "issue_context": "/ClinicalDocument/component[1]/structuredBody[1]/component[1]/section[1]/entry[1]/observation[1]",
       "issue_id": null,
-      "issue_message": "Text to Code: Lab Test Name Ordered does not have a @code attribute",
+      "issue_message": "Text to Code: Planned observation code data element has no @code attribute",
       "issue_test": "not(cda:code) or cda:code/@code or cda:code/cda:translation/@code",
       "new_translation": null,
       "opensearch_retrieved_scores": {
diff --git a/packages/text-to-code-lambda/tests/snapshots/test_lambda_function/test_handler_success/handler_success_ttc_metadata_output.json b/packages/text-to-code-lambda/tests/snapshots/test_lambda_function/test_handler_success/handler_success_ttc_metadata_output.json
@@ -24,7 +24,7 @@
       "field_type": "Lab Test Name Ordered",
       "issue_context": "/ClinicalDocument/component[1]/structuredBody[1]/component[1]/section[1]/entry[1]/observation[1]",
       "issue_id": null,
-      "issue_message": "Text to Code: Lab Test Name Ordered does not have a @code attribute",
+      "issue_message": "Text to Code: Planned observation code data element has no @code attribute",
       "issue_test": "not(cda:code) or cda:code/@code or cda:code/cda:translation/@code",
       "new_translation": {
         "code": "82041-5",
diff --git a/packages/text-to-code/src/text_to_code/models/schematron.py b/packages/text-to-code/src/text_to_code/models/schematron.py
@@ -7,15 +7,21 @@
 class LabTestNameOrderedSchematronErrors(Enum):
     """The list of Schematron error messages relevant to the lab test name ordered data field."""
 
-    MISSING_CODE_ATTRIBUTE = "Text to Code: Lab Test Name Ordered does not have a @code attribute"
-    INVALID_CODE_SYSTEM = "Text to Code: Lab Test Name Ordered code and translation data elements @codeSystem attribute are not LOINC 2.16.840.1.113883.6.1"
+    MISSING_CODE_ATTRIBUTE = (
+        "Text to Code: Planned observation code data element has no @code attribute"
+    )
+    INVALID_CODE_SYSTEM = "Text to Code: Lab Test Name Resulted code and translation data elements @codeSystem attribute are not LOINC (2.16.840.1.113883.6.1), SNOMED CT (2.16.840.1.113883.6.96),  CPT-4 (2.16.840.1.113883.6.12), ICD10 PCS (2.16.840.1.113883.6.4) or CDT-2 (2.16.840.1.113883.6.13)"
+    BLANK_CODE = "Text to Code: Planned observation code data element @code attribute is blank"
+    NULL_FLAVOR_CODE = "Text to Code: Planned observation code data element is nullFlavor"
 
 
 class LabTestNameResultedSchematronErrors(Enum):
     """The list of Schematron error messages relevant to the lab test name resulted data field."""
 
-    MISSING_CODE_ATTRIBUTE = "Text to Code: Lab Test Name Resulted does not have a @code attribute"
+    MISSING_CODE_ATTRIBUTE = "Text to Code: Lab Test Name Resulted does not have a @code attribute."
     INVALID_CODE_SYSTEM = "Text to Code: Lab Test Name Resulted code and translation data elements @codeSystem attribute are not LOINC 2.16.840.1.113883.6.1"
+    BLANK_CODE = "Text to Code: Result observation code data element @code attribute is blank."
+    NULL_FLAVOR_CODE = "Text to Code: Result observation code data element is nullFlavor."
 
 
 SchematronErrors = LabTestNameOrderedSchematronErrors | LabTestNameResultedSchematronErrors
diff --git a/packages/text-to-code/tests/assets/test_schematron_errors.xml b/packages/text-to-code/tests/assets/test_schematron_errors.xml
@@ -56,7 +56,7 @@
     <Results xmlns="urn:gov:nist:cdaGuideValidator">
         <validationResult xmlns="">
             <issue severity="errors">
-                <message>Text to Code: Lab Test Name Resulted does not have a @code attribute</message>
+                <message>Text to Code: Lab Test Name Resulted does not have a @code attribute.</message>
                 <context>/ClinicalDocument/component[1]/structuredBody[1]/component[5]/section[1]/entry[1]/organizer[1]/component[1]/observation[1]</context>
                 <test> not(cda:code) or cda:code/@code or cda:code/cda:translation/@code</test>
                 <specification/>
@@ -70,23 +70,55 @@
                 <specification/>
             </issue>
         </validationResult>
+        <validationResult xmlns="">
+            <issue severity="errors">
+                <message>Text to Code: Result observation code data element @code attribute is blank.</message>
+                <context>/ClinicalDocument/component[1]/structuredBody[1]/component[5]/section[1]/entry[1]/organizer[1]/component[1]/observation[1]</context>
+                <test> not(cda:code) or cda:code[@nullFlavor] or count(cda:code[@code = '']) = 0</test>
+                <specification/>
+            </issue>
+        </validationResult>
+        <validationResult xmlns="">
+            <issue severity="errors">
+                <message>Text to Code: Result observation code data element is nullFlavor.</message>
+                <context>/ClinicalDocument/component[1]/structuredBody[1]/component[5]/section[1]/entry[1]/organizer[1]/component[1]/observation[1]</context>
+                <test> not(cda:code) or cda:code[not(@nullFlavor)]</test>
+                <specification/>
+            </issue>
+        </validationResult>
     </Results>
     <Results xmlns="urn:gov:nist:cdaGuideValidator">
         <validationResult xmlns="">
             <issue severity="errors">
-                <message>Text to Code: Lab Test Name Ordered does not have a @code attribute</message>
+                <message>Text to Code: Planned observation code data element has no @code attribute</message>
                 <context>/ClinicalDocument/component[1]/structuredBody[1]/component[5]/section[1]/entry[1]/observation[1]</context>
                 <test> not(cda:code) or cda:code/@code or cda:code/cda:translation/@code</test>
                 <specification/>
             </issue>
         </validationResult>
         <validationResult xmlns="">
             <issue severity="errors">
-                <message>Text to Code: Lab Test Name Ordered code and translation data elements @codeSystem attribute are not LOINC 2.16.840.1.113883.6.1</message>
+                <message>Text to Code: Lab Test Name Resulted code and translation data elements @codeSystem attribute are not LOINC (2.16.840.1.113883.6.1), SNOMED CT (2.16.840.1.113883.6.96),  CPT-4 (2.16.840.1.113883.6.12), ICD10 PCS (2.16.840.1.113883.6.4) or CDT-2 (2.16.840.1.113883.6.13)</message>
                 <context>/ClinicalDocument/component[1]/structuredBody[1]/component[5]/section[1]/entry[1]/observation[1]</context>
                 <test>not(cda:code/@code or cda:code/cda:translation/@code) or cda:code[@codeSystem = '2.16.840.1.113883.6.1'] or cda:code/cda:translation[@codeSystem = '2.16.840.1.113883.6.1']</test>
                 <specification/>
             </issue>
         </validationResult>
+        <validationResult xmlns="">
+            <issue severity="errors">
+                <message>Text to Code: Planned observation code data element is nullFlavor</message>
+                <context>/ClinicalDocument/component[1]/structuredBody[1]/component[5]/section[1]/entry[1]/observation[1]</context>
+                <test>not(cda:code) or cda:code[not(@nullFlavor)]</test>
+                <specification/>
+            </issue>
+        </validationResult>
+        <validationResult xmlns="">
+            <issue severity="errors">
+                <message>Text to Code: Planned observation code data element @code attribute is blank</message>
+                <context>/ClinicalDocument/component[1]/structuredBody[1]/component[5]/section[1]/entry[1]/observation[1]</context>
+                <test>not(cda:code) or cda:code[@nullFlavor] or count(cda:code[@code = '']) = 0</test>
+                <specification/>
+            </issue>
+        </validationResult>
     </Results>
 </Report>
diff --git a/packages/text-to-code/tests/unit/test_schematron_processor.py b/packages/text-to-code/tests/unit/test_schematron_processor.py
@@ -16,6 +16,9 @@
 
 class TestSchematronProcessor:
     SCHEMATRON_ERROR_FILE: str | None = None
+    LAB_TEST_RESULTED_ERROR: str = (
+        "Text to Code: Lab Test Name Resulted does not have a @code attribute."
+    )
 
     def file_setup(self) -> str:
         if self.SCHEMATRON_ERROR_FILE is None:
@@ -65,8 +68,8 @@ def test_get_schematron_error_data_fields(self):
             schematron_error_file,
         )
 
-        expected_lab_test_name_resulted = 2
-        expected_lab_test_name_ordered = 2
+        expected_lab_test_name_resulted = 4
+        expected_lab_test_name_ordered = 4
 
         lab_test_name_resulted_errors = [
             error for error in error_result if error.field == DataField.LAB_TEST_NAME_RESULTED
@@ -83,28 +86,21 @@ def test_get_schematron_error_detail_fields(self):
         error_result = get_data_fields_from_schematron_error(
             schematron_error_file,
         )
-        expected_total_errors = 4
+        expected_total_errors = 8
 
         assert len(error_result) == expected_total_errors
 
         lab_test_name_resulted_error = next(
             error
             for error in error_result
             if error.field == DataField.LAB_TEST_NAME_RESULTED
-            and error.error_message
-            == "Text to Code: Lab Test Name Resulted does not have a @code attribute"
+            and error.error_message == self.LAB_TEST_RESULTED_ERROR
         )
 
         assert lab_test_name_resulted_error.eicr_id is None
         assert lab_test_name_resulted_error.field == DataField.LAB_TEST_NAME_RESULTED
-        assert (
-            lab_test_name_resulted_error.error
-            == "Text to Code: Lab Test Name Resulted does not have a @code attribute"
-        )
-        assert (
-            lab_test_name_resulted_error.error_message
-            == "Text to Code: Lab Test Name Resulted does not have a @code attribute"
-        )
+        assert lab_test_name_resulted_error.error == self.LAB_TEST_RESULTED_ERROR
+        assert lab_test_name_resulted_error.error_message == self.LAB_TEST_RESULTED_ERROR
         assert (
             lab_test_name_resulted_error.error_context
             == "/ClinicalDocument/component[1]/structuredBody[1]/component[5]/section[1]/entry[1]/organizer[1]/component[1]/observation[1]"
@@ -126,7 +122,7 @@ def test_get_schematron_error_processes_validation_result_root(self):
         schematron_errors = """
         <validationResult>
             <issue>
-                <message>Text to Code: Lab Test Name Resulted does not have a @code attribute</message>
+                <message>Text to Code: Lab Test Name Resulted does not have a @code attribute.</message>
                 <context>/ClinicalDocument/component[1]</context>
                 <test>test-expression</test>
                 <assertionID>ttc-labTestNameResulted-noCode</assertionID>
@@ -138,14 +134,8 @@ def test_get_schematron_error_processes_validation_result_root(self):
 
         assert len(result) == 1
         assert result[0].field == DataField.LAB_TEST_NAME_RESULTED
-        assert (
-            result[0].error
-            == "Text to Code: Lab Test Name Resulted does not have a @code attribute"
-        )
-        assert (
-            result[0].error_message
-            == "Text to Code: Lab Test Name Resulted does not have a @code attribute"
-        )
+        assert result[0].error == self.LAB_TEST_RESULTED_ERROR
+        assert result[0].error_message == self.LAB_TEST_RESULTED_ERROR
         assert result[0].error_context == "/ClinicalDocument/component[1]"
         assert result[0].error_test == "test-expression"
         assert result[0].error_id == "ttc-labTestNameResulted-noCode"
@@ -187,7 +177,7 @@ def test_get_schematron_error_skips_validation_result_when_context_is_missing(se
             <result>
                 <validationResult>
                     <issue>
-                        <message>Text to Code: Lab Test Name Resulted does not have a @code attribute</message>
+                        <message>Text to Code: Lab Test Name Resulted does not have a @code attribute.</message>
                     </issue>
                 </validationResult>
             </result>
@@ -222,7 +212,7 @@ def test_get_schematron_error_skips_when_error_enum_value_is_none(self):
             <result>
                 <validationResult>
                     <issue>
-                        <message>Text to Code: Lab Test Name Resulted does not have a @code attribute</message>
+                        <message>Text to Code: Lab Test Name Resulted does not have a @code attribute.</message>
                         <context>/ClinicalDocument/component[1]</context>
                     </issue>
                 </validationResult>
@@ -250,14 +240,14 @@ def test_get_schematron_error_deduplicates_duplicate_errors(self):
             <result>
                 <validationResult>
                     <issue>
-                        <message>Text to Code: Lab Test Name Resulted does not have a @code attribute</message>
+                        <message>Text to Code: Lab Test Name Resulted does not have a @code attribute.</message>
                         <context>/ClinicalDocument/component[1]</context>
                         <test>test-expression</test>
                     </issue>
                 </validationResult>
                 <validationResult>
                     <issue>
-                        <message>Text to Code: Lab Test Name Resulted does not have a @code attribute</message>
+                        <message>Text to Code: Lab Test Name Resulted does not have a @code attribute.</message>
                         <context>/ClinicalDocument/component[1]</context>
                         <test>test-expression</test>
                     </issue>
@@ -276,7 +266,7 @@ def test_get_schematron_error_logs_when_issue_processing_fails(self):
             <result>
                 <validationResult>
                     <issue>
-                        <message>Text to Code: Lab Test Name Resulted does not have a @code attribute</message>
+                        <message>Text to Code: Lab Test Name Resulted does not have a @code attribute.</message>
                         <context>/ClinicalDocument/component[1]/structuredBody[1]/component[5]/section[1]/entry[1]/organizer[1]/component[1]/observation[1]</context>
                         <test>not(cda:code) or cda:code/@code or cda:code/cda:translation/@code</test>
                     </issue>
@@ -298,7 +288,7 @@ def test_get_schematron_error_logs_when_issue_processing_fails(self):
         mock_exception.assert_called_once_with(
             "Failed to process a schematron error detail",
             extra={
-                "error_message": "Text to Code: Lab Test Name Resulted does not have a @code attribute",
+                "error_message": self.LAB_TEST_RESULTED_ERROR,
                 "error_context": "/ClinicalDocument/component[1]/structuredBody[1]/component[5]/section[1]/entry[1]/organizer[1]/component[1]/observation[1]",
                 "status": "error",
             },
diff --git a/packages/validation/src/validation/eicr-validator/schematron/APHL_TextToCodeSchematron_09252025.sch b/packages/validation/src/validation/eicr-validator/schematron/APHL_TextToCodeSchematron_09252025.sch
diff --git a/packages/validation/tests/test_validation.py b/packages/validation/tests/test_validation.py
