sdcvalidator 4.0.2__tar.gz → 4.0.5__tar.gz

{sdcvalidator-4.0.2 → sdcvalidator-4.0.5}/CHANGELOG.rst

@@ -2,6 +2,107 @@
 CHANGELOG
 *********
 
+`v4.0.5`_ (2025-11-04)
+======================
+**Selective ExceptionalValue Tagging & Configurable Output**
+
+* **NOTE**: Version 4.0.4 was published with preliminary selective tagging; this release adds configurable output and fixes
+* **CRITICAL CLARIFICATION**: ExceptionalValue tagging applies **only to data-bearing elements**
+* **Fixed**: Structural and metadata elements now properly fail validation instead of being tagged
+* **Breaking Change**: Validation errors in structural elements (label, vtb, vte, tr, modified, etc.) now cause validation failure as intended by SDC4 spec
+* **NEW**: Configurable output file paths with user-friendly naming convention
+* **NEW**: Automatic file saving with {original_filename}-ev.xml naming
+* **NEW**: Inline validation error comments in ExceptionalValue elements
+* **Data-Bearing Elements** that receive ExceptionalValue tags:
+
+  * xdstring-value, xdcount-value, xdquantity-value
+  * xdboolean-value, xdfile-value, xdlink-value
+  * xdtemporal-value, xdordinal-value, xdratio-value
+  * xdinterval-value, xdtoken-value
+
+* **Structural/Metadata Elements** that must be valid (validation fails if invalid):
+
+  * label - Component labels must be valid
+  * vtb, vte, tr, modified - Temporal metadata must be valid dateTime
+  * act - Audit/control/trust elements must conform to schema
+  * latitude, longitude - Geographic coordinates must be valid
+  * normal-status, magnitude-status, accuracy_margin, precision_digits - Quantified metadata
+
+**Changes:**
+
+* Updated ErrorMapper.map_error() to return None for structural element errors
+* Updated InstanceModifier.insert_exceptional_value() to check element type before tagging
+* Added DATA_BEARING_ELEMENTS and STRUCTURAL_ELEMENTS constants
+* Added element name extraction from XPath in both ErrorMapper and InstanceModifier
+* Fixed Clark notation XPath parsing for namespace-aware element location
+* Fixed parent element insertion (ExceptionalValue inserted into parent, not child)
+* Added output_path parameter to validate_with_recovery()
+* Added save parameter to validate_with_recovery() (default: True)
+* Default output naming: saves to same directory as input with -ev suffix
+* Automatic XML formatting with 4-space indentation
+* Enhanced SDC4 README.md with selective tagging and output configuration documentation
+
+**New API:**
+
+.. code-block:: python
+
+    from sdcvalidator.sdc4 import SDC4Validator
+
+    validator = SDC4Validator('schema.xsd')
+
+    # Default: saves to 'input-ev.xml' in same directory
+    validator.validate_with_recovery('input.xml')
+
+    # Custom output path
+    validator.validate_with_recovery('input.xml', output_path='/custom/path.xml')
+
+    # Skip saving (in-memory only)
+    tree = validator.validate_with_recovery('input.xml', save=False)
+
+**Migration Guide:**
+
+If your code relies on structural elements being tagged with ExceptionalValue, you will need to update your validation logic. Structural elements must now be valid for the XML instance to pass validation.
+
+The validate_with_recovery() method now saves recovered XML automatically. Use save=False if you want the old behavior of only returning the tree without saving.
+
+----
+
+`v4.0.3`_ (2025-11-04)
+======================
+**Critical Fix: Xerces/Saxon Gold Standard Compatibility**
+
+* **CRITICAL FIX**: Use validation='lax' to match Xerces 1.1 and Saxon EE 1.1 behavior (gold standard validators)
+* **Documentation**: Add comprehensive SDC4 Quick Start guide with XMLSchema11 and uri_mapper examples
+* **Fixed**: sdcvalidator was rejecting valid XSD 1.1 schemas that pass Xerces and Saxon validation
+* **Fixed**: validation='strict' (default) was stricter than XSD spec, causing false rejections
+* **Recommendation**: Always use XMLSchema11 with validation='lax' for SDC4 schemas
+* **Breaking Fix**: This ensures SDC4 community can use standard-compliant schemas
+
+**Key Changes for SDC4 Users:**
+
+* Use `XMLSchema11` explicitly (XMLSchema is alias to XMLSchema10, will prune XSD 1.1 schemas)
+* Use `uri_mapper` parameter for offline validation (maps schema URLs to local files)
+* Use `validation='lax'` to match Xerces/Saxon behavior
+* See sdcvalidator/sdc4/README.md for complete Quick Start guide
+
+**Example:**
+
+.. code-block:: python
+
+    from sdcvalidator import XMLSchema11
+
+    uri_mapper = {
+        'https://semanticdatacharter.com/ns/sdc4/sdc4.xsd': '/path/to/sdc4.xsd'
+    }
+
+    schema = XMLSchema11(
+        'my_datamodel.xsd',
+        uri_mapper=uri_mapper,
+        validation='lax'  # Matches Xerces/Saxon
+    )
+
+----
+
 `v4.0.2`_ (2025-11-04)
 ======================
 **SDCValidator Release**

{sdcvalidator-4.0.2/sdcvalidator.egg-info → sdcvalidator-4.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sdcvalidator
-Version: 4.0.2
+Version: 4.0.5
 Summary: SDC4 XML validation with ExceptionalValue recovery
 Author: Axius-SDC, Inc.
 Maintainer-email: Tim Cook <contact@axius-sdc.com>

{sdcvalidator-4.0.2 → sdcvalidator-4.0.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sdcvalidator"
-version = "4.0.2"
+version = "4.0.5"
 description = "SDC4 XML validation with ExceptionalValue recovery"
 readme = "README.md"
 license = "MIT"

{sdcvalidator-4.0.2 → sdcvalidator-4.0.5}/sdcvalidator/sdc4/constants.py

@@ -107,6 +107,39 @@ EXCEPTIONAL_VALUE_TYPES: Dict[str, tuple] = {
 # XPath patterns for locating elements in SDC4 data model instances
 XDANY_TYPE_PATTERN = r"xd(?:string|count|quantity|boolean|file|link|temporal|ordinal|ratio|interval)-value"
 
+# Data-bearing elements that can receive ExceptionalValue tags
+# These are the actual data values - validation errors here use quarantine-and-tag pattern
+DATA_BEARING_ELEMENTS = {
+    'xdstring-value',
+    'xdcount-value',
+    'xdquantity-value',
+    'xdboolean-value',
+    'xdfile-value',
+    'xdlink-value',
+    'xdtemporal-value',
+    'xdordinal-value',
+    'xdratio-value',
+    'xdinterval-value',
+    'xdtoken-value',
+}
+
+# Structural/metadata elements that should FAIL validation (not use ExceptionalValue)
+# These include labels, temporal metadata, and other structural elements
+STRUCTURAL_ELEMENTS = {
+    'label',           # Component labels
+    'act',             # Audit/control/trust
+    'vtb',             # Valid time begin
+    'vte',             # Valid time end
+    'tr',              # Transaction time
+    'modified',        # Modification timestamp
+    'latitude',        # Geographic coordinate
+    'longitude',       # Geographic coordinate
+    'normal-status',   # Quantified metadata
+    'magnitude-status',# Quantified metadata
+    'accuracy_margin', # Quantified metadata
+    'precision_digits',# Quantified metadata
+}
+
 # Element sequence position for ExceptionalValue in XdAnyType
 # Per SDC4 schema: label, act, ExceptionalValue, vtb, vte, tr, modified, latitude, longitude, ...
 EXCEPTIONAL_VALUE_INSERT_AFTER = ['label', 'act']

{sdcvalidator-4.0.2 → sdcvalidator-4.0.5}/sdcvalidator/sdc4/error_mapper.py

@@ -14,7 +14,11 @@ from sdcvalidator.core.exceptions import (
     XMLSchemaDecodeError,
     XMLSchemaChildrenValidationError
 )
-from .constants import ExceptionalValueType
+from .constants import (
+    ExceptionalValueType,
+    DATA_BEARING_ELEMENTS,
+    STRUCTURAL_ELEMENTS
+)
 
 
 class ErrorMapper:
@@ -86,13 +90,30 @@ class ErrorMapper:
         """
         self._rules.append((condition, ev_type))
 
-    def map_error(self, error: XMLSchemaValidationError) -> ExceptionalValueType:
+    def map_error(self, error: XMLSchemaValidationError) -> Optional[ExceptionalValueType]:
         """
         Map a validation error to an ExceptionalValue type.
 
+        Only data-bearing elements (xdstring-value, xdcount-value, etc.) can receive
+        ExceptionalValue tags. Structural/metadata elements (label, vtb, vte, tr, etc.)
+        should fail validation.
+
         :param error: The XML Schema validation error.
-        :return: The appropriate ExceptionalValueType.
+        :return: The appropriate ExceptionalValueType, or None if this is a structural
+                 element that should fail validation.
+        :raises XMLSchemaValidationError: If the error occurs in a structural element.
         """
+        # Extract element name from the error path
+        element_name = self._extract_element_name(error.path)
+
+        # Check if this is a structural element - these should fail validation
+        if element_name and element_name in STRUCTURAL_ELEMENTS:
+            # Don't map to ExceptionalValue - let validation fail
+            return None
+
+        # For SDC4 data-bearing elements or unknown elements, map to appropriate ExceptionalValue
+        # Note: We're permissive here - only STRUCTURAL_ELEMENTS fail validation
+        # This allows the system to work with custom element names and future SDC versions
         for condition, ev_type in self._rules:
             if condition(error):
                 return ev_type
@@ -100,6 +121,38 @@ class ErrorMapper:
         # Should never reach here due to default rule, but just in case
         return ExceptionalValueType.NI
 
+    def _extract_element_name(self, xpath: Optional[str]) -> Optional[str]:
+        """
+        Extract the element name from an XPath expression.
+
+        Handles paths like:
+        - /DataModel/xdstring-value
+        - /ns:DataModel/ns:xdstring-value[1]
+        - //xdcount-value
+
+        :param xpath: The XPath expression from the validation error.
+        :return: The local element name (without namespace prefix), or None.
+        """
+        if not xpath:
+            return None
+
+        # Get the last path component
+        parts = xpath.strip('/').split('/')
+        if not parts:
+            return None
+
+        last_part = parts[-1]
+
+        # Remove namespace prefix (e.g., 'sdc4:xdstring-value' -> 'xdstring-value')
+        if ':' in last_part:
+            last_part = last_part.split(':')[-1]
+
+        # Remove predicates (e.g., 'xdstring-value[1]' -> 'xdstring-value')
+        if '[' in last_part:
+            last_part = last_part[:last_part.index('[')]
+
+        return last_part if last_part else None
+
     # =========================================================================
     # Error classification helper methods
     # =========================================================================
@@ -221,14 +274,25 @@ class ErrorMapper:
         return any(re.search(pattern, reason) for pattern in patterns)
 
     def get_error_summary(self, error: XMLSchemaValidationError,
-                          ev_type: ExceptionalValueType) -> Dict[str, str]:
+                          ev_type: Optional[ExceptionalValueType]) -> Dict[str, str]:
         """
         Generate a summary of the error mapping.
 
         :param error: The validation error.
-        :param ev_type: The mapped ExceptionalValueType.
+        :param ev_type: The mapped ExceptionalValueType, or None for structural elements.
         :return: A dictionary with error details.
         """
+        if ev_type is None:
+            # Structural/metadata element error - no ExceptionalValue
+            return {
+                'xpath': error.path or 'unknown',
+                'error_type': type(error).__name__,
+                'reason': error.reason or 'No reason provided',
+                'exceptional_value_type': None,
+                'exceptional_value_name': None,
+                'description': 'Structural/metadata element - validation fails',
+            }
+
         return {
             'xpath': error.path or 'unknown',
             'error_type': type(error).__name__,

{sdcvalidator-4.0.2 → sdcvalidator-4.0.5}/sdcvalidator/sdc4/instance_modifier.py

@@ -13,7 +13,9 @@ from .constants import (
     SDC4_NAMESPACE,
     ExceptionalValueType,
     EXCEPTIONAL_VALUE_INSERT_AFTER,
-    EXCEPTIONAL_VALUE_INSERT_BEFORE
+    EXCEPTIONAL_VALUE_INSERT_BEFORE,
+    DATA_BEARING_ELEMENTS,
+    STRUCTURAL_ELEMENTS
 )
 
 
@@ -43,29 +45,75 @@ class InstanceModifier:
         """
         Insert an ExceptionalValue element at the specified XPath location.
 
+        Only data-bearing elements (xdstring-value, xdcount-value, etc.) can receive
+        ExceptionalValue tags. Structural/metadata elements (label, vtb, vte, tr, etc.)
+        should not be tagged.
+
         :param root: The root element of the XML document.
         :param xpath: XPath to the element where the error occurred.
         :param ev_type: The ExceptionalValueType to insert.
         :param reason: Optional additional reason text.
-        :return: True if insertion was successful, False otherwise.
+        :return: True if insertion was successful, False if element should not be tagged.
         """
+        # Check if this element should receive ExceptionalValue tag
+        element_name = self._extract_element_name_from_xpath(xpath)
+
+        # Don't tag structural elements - these should fail validation
+        if element_name and element_name in STRUCTURAL_ELEMENTS:
+            return False
+
+        # All other elements (data-bearing, custom, or unknown) can be tagged
+        # This allows flexibility for custom element names and future SDC versions
+
         # Ensure namespace is registered
         self._register_namespace()
 
-        # Find the target element using XPath
-        target_elem = self._find_element_by_xpath(root, xpath)
-        if target_elem is None:
+        # Find the element with the invalid value using XPath
+        invalid_elem = self._find_element_by_xpath(root, xpath)
+        if invalid_elem is None:
+            return False
+
+        # Find the parent element (XdAnyType) where ExceptionalValue should be inserted
+        parent_elem = self._find_parent_element(root, invalid_elem)
+        if parent_elem is None:
             return False
 
         # Create the ExceptionalValue element
         ev_element = self._create_exceptional_value_element(ev_type, reason)
 
-        # Insert at the appropriate position in the sequence
-        insert_pos = self._find_insertion_position(target_elem)
-        target_elem.insert(insert_pos, ev_element)
+        # Insert at the appropriate position in the parent's sequence
+        insert_pos = self._find_insertion_position(parent_elem)
+        parent_elem.insert(insert_pos, ev_element)
 
         return True
 
+    def _extract_element_name_from_xpath(self, xpath: str) -> Optional[str]:
+        """
+        Extract the element name from an XPath expression.
+
+        :param xpath: The XPath expression.
+        :return: The local element name (without namespace prefix), or None.
+        """
+        if not xpath:
+            return None
+
+        # Get the last path component
+        parts = xpath.strip('/').split('/')
+        if not parts:
+            return None
+
+        last_part = parts[-1]
+
+        # Remove namespace prefix (e.g., 'sdc4:xdstring-value' -> 'xdstring-value')
+        if ':' in last_part:
+            last_part = last_part.split(':')[-1]
+
+        # Remove predicates (e.g., 'xdstring-value[1]' -> 'xdstring-value')
+        if '[' in last_part:
+            last_part = last_part[:last_part.index('[')]
+
+        return last_part if last_part else None
+
     def _register_namespace(self):
         """Register the SDC4 namespace with ElementTree."""
         try:
@@ -76,15 +124,20 @@ class InstanceModifier:
 
     def _find_element_by_xpath(self, root: ET.Element, xpath: str) -> Optional[ET.Element]:
         """
-        Find an element by XPath.
+        Find an element by XPath (including Clark notation support).
 
         :param root: The root element to search from.
-        :param xpath: The XPath expression.
+        :param xpath: The XPath expression (may use Clark notation: {namespace}localname).
         :return: The found element or None.
         """
         if not xpath:
             return None
 
+        # Handle Clark notation in XPath by traversing manually
+        # Clark notation: /{namespace}localname/{namespace}localname/...
+        if '{' in xpath:
+            return self._find_element_by_clark_path(root, xpath)
+
         # Handle namespace prefixes in XPath
         # Convert xpath like /ns:root/ns:child to proper namespaced search
         namespaces = self._extract_namespaces(root)
@@ -111,6 +164,88 @@ class InstanceModifier:
 
         return None
 
+    def _find_element_by_clark_path(self, root: ET.Element, clark_path: str) -> Optional[ET.Element]:
+        """
+        Find an element by traversing a Clark notation path.
+
+        Clark notation: /{namespace}localname/{namespace}localname/...
+
+        :param root: The root element to search from.
+        :param clark_path: The path using Clark notation.
+        :return: The found element or None.
+        """
+        # Parse Clark notation path components
+        # Need to be careful not to split on slashes inside the namespace URI
+        parts = []
+        i = 0
+        while i < len(clark_path):
+            if clark_path[i] == '/':
+                # Skip slashes
+                i += 1
+                continue
+            elif clark_path[i] == '{':
+                # Start of namespaced element: {namespace}localname
+                # Find the matching '}'
+                end_brace = clark_path.index('}', i)
+                # Find the next '/' or end of string
+                next_slash = clark_path.find('/', end_brace)
+                if next_slash == -1:
+                    next_slash = len(clark_path)
+                # Extract the full element name with namespace
+                part = clark_path[i:next_slash]
+                parts.append(part)
+                i = next_slash
+            else:
+                # Element without namespace
+                next_slash = clark_path.find('/', i)
+                if next_slash == -1:
+                    next_slash = len(clark_path)
+                part = clark_path[i:next_slash]
+                parts.append(part)
+                i = next_slash
+
+        if not parts:
+            return None
+
+        # Start from root
+        current = root
+
+        # Check if the first part is the root element itself
+        if parts[0] == root.tag:
+            # Skip the root element in the path
+            parts = parts[1:]
+            if not parts:
+                return root
+
+        # Traverse each part of the path
+        for part in parts:
+            # The part is in Clark notation: {namespace}localname or just localname
+            found = False
+            for child in current:
+                if child.tag == part:
+                    current = child
+                    found = True
+                    break
+
+            if not found:
+                return None
+
+        return current
+
+    def _find_parent_element(self, root: ET.Element, child: ET.Element) -> Optional[ET.Element]:
+        """
+        Find the parent element of a given child element.
+
+        :param root: The root element to search from.
+        :param child: The child element whose parent we want to find.
+        :return: The parent element or None.
+        """
+        # Iterate through all elements in the tree
+        for parent in root.iter():
+            if child in list(parent):
+                return parent
+        return None
+
     def _extract_namespaces(self, root: ET.Element) -> Dict[str, str]:
         """
         Extract namespace mappings from the root element.
@@ -204,19 +339,27 @@ class InstanceModifier:
         """
         Create an ExceptionalValue element.
 
+        Per SDC4 spec, the element name is the ExceptionalValue code (INV, UNK, etc.)
+        with a child <ev-name> element containing the human-readable name.
+
+        Example:
+            <sdc4:INV>
+                <ev-name>Invalid</ev-name>
+            </sdc4:INV>
+
         :param ev_type: The ExceptionalValueType.
         :param reason: Optional additional reason text.
         :return: The created element.
         """
-        # Create element with namespaced tag
+        # Create element with the ExceptionalValue code as the tag name
         tag = f"{{{self.sdc4_ns}}}{ev_type.code}"
         ev_elem = ET.Element(tag)
 
         # Add the ev-name child element
-        ev_name_elem = ET.SubElement(ev_elem, f"{{{self.sdc4_ns}}}ev-name")
+        ev_name_elem = ET.SubElement(ev_elem, "ev-name")
         ev_name_elem.text = ev_type.ev_name
 
-        # Optionally add reason as a comment or custom element
+        # Optionally add reason as a comment
         if reason:
             comment = ET.Comment(f" Validation error: {reason} ")
             ev_elem.insert(0, comment)

{sdcvalidator-4.0.2 → sdcvalidator-4.0.5}/sdcvalidator/sdc4/validator.py

@@ -72,14 +72,38 @@ class SDC4Validator:
 
     def validate_with_recovery(self,
                                 xml_source: Union[str, Path, ET.Element, XMLResource],
-                                remove_existing_ev: bool = True) -> ET.ElementTree:
+                                output_path: Optional[Union[str, Path]] = None,
+                                remove_existing_ev: bool = True,
+                                save: bool = True) -> ET.ElementTree:
         """
         Validate an XML instance and insert ExceptionalValue elements for errors.
 
+        The recovered XML with ExceptionalValue tags is automatically saved unless save=False.
+
         :param xml_source: The XML instance to validate (file path, element, or XMLResource).
+        :param output_path: Optional output file path. If None and xml_source is a file path,
+                           defaults to '{original_filename}-ev.xml' in the same directory.
+                           If xml_source is not a file path, you must provide output_path or set save=False.
         :param remove_existing_ev: If True, remove any existing ExceptionalValue elements before processing.
+        :param save: If True (default), save the recovered XML to output_path. Set to False to skip saving.
         :return: Modified XML ElementTree with ExceptionalValue elements inserted.
+        :raises ValueError: If save=True but output_path cannot be determined.
+
+        Example usage:
+            # Default: saves to 'count_error_example-ev.xml' in same directory
+            validator.validate_with_recovery('count_error_example.xml')
+
+            # Custom output path
+            validator.validate_with_recovery('input.xml', output_path='/path/to/recovered.xml')
+
+            # Don't save, just return the tree
+            tree = validator.validate_with_recovery('input.xml', save=False)
         """
+        # Track the original file path for default output naming
+        original_file_path = None
+        if isinstance(xml_source, (str, Path)):
+            original_file_path = Path(xml_source)
+
         # Parse the XML if it's a path
         if isinstance(xml_source, (str, Path)):
             tree = ET.parse(str(xml_source))
@@ -109,6 +133,10 @@ class SDC4Validator:
             # Map error to ExceptionalValue type
             ev_type = self.error_mapper.map_error(error)
 
+            # Skip if error mapper returned None (structural/metadata element)
+            if ev_type is None:
+                continue
+
             # Get the XPath to the error location
             xpath = error.path
 
@@ -126,6 +154,27 @@ class SDC4Validator:
                     # For now, we'll just continue
                     pass
 
+        # Save the recovered XML if requested
+        if save:
+            # Determine output path
+            if output_path is None:
+                if original_file_path is None:
+                    raise ValueError(
+                        "Cannot determine output path: xml_source is not a file path. "
+                        "Either provide output_path parameter or set save=False."
+                    )
+                # Default naming: {original_filename}-ev.xml
+                output_path = original_file_path.parent / f"{original_file_path.stem}-ev{original_file_path.suffix}"
+            else:
+                output_path = Path(output_path)
+
+            # Ensure parent directory exists
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+
+            # Save with formatting
+            ET.indent(tree, space='    ')
+            tree.write(str(output_path), encoding='UTF-8', xml_declaration=True)
+
         return tree
 
     def iter_errors_with_mapping(self,
@@ -152,6 +201,11 @@ class SDC4Validator:
             # Map error to ExceptionalValue type
             ev_type = self.error_mapper.map_error(error)
 
+            # Skip if error mapper returned None (structural/metadata element)
+            # These errors cannot be recovered with ExceptionalValue
+            if ev_type is None:
+                continue
+
             # Generate summary
             summary = self.error_mapper.get_error_summary(error, ev_type)
 

{sdcvalidator-4.0.2 → sdcvalidator-4.0.5/sdcvalidator.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sdcvalidator
-Version: 4.0.2
+Version: 4.0.5
 Summary: SDC4 XML validation with ExceptionalValue recovery
 Author: Axius-SDC, Inc.
 Maintainer-email: Tim Cook <contact@axius-sdc.com>