sdcvalidator 4.2.0__tar.gz → 4.3.0__tar.gz

{sdcvalidator-4.2.0/src/sdcvalidator.egg-info → sdcvalidator-4.3.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: sdcvalidator
-Version: 4.2.0
-Summary: SDC4 structural validator — thin wrapper over xmlschema with error classification
+Version: 4.3.0
+Summary: SDC4 structural validator with ExceptionalValue recovery — thin wrapper over xmlschema
 Author: Semantic Data Charter Foundation
 License-Expression: Apache-2.0
 Classifier: Development Status :: 4 - Beta

{sdcvalidator-4.2.0 → sdcvalidator-4.3.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sdcvalidator"
-version = "4.2.0"
-description = "SDC4 structural validator — thin wrapper over xmlschema with error classification"
+version = "4.3.0"
+description = "SDC4 structural validator with ExceptionalValue recovery — thin wrapper over xmlschema"
 license = "Apache-2.0"
 requires-python = ">=3.10"
 readme = "README.md"
@@ -30,6 +30,7 @@ dev = ["pytest>=7.0", "pytest-cov"]
 sdcvalidate = "sdcvalidator.cli:validate_main"
 sdcvalidator-xml2json = "sdcvalidator.cli:xml2json_main"
 sdcvalidator-json2xml = "sdcvalidator.cli:json2xml_main"
+sdcvalidator-mcp = "sdcvalidator.mcp_server:main"
 
 [tool.setuptools.packages.find]
 where = ["src"]

sdcvalidator-4.3.0/src/sdcvalidator/__init__.py

@@ -0,0 +1,65 @@
+#
+# Copyright 2025 Semantic Data Charter Foundation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+"""
+sdcvalidator — SDC4 structural validator with ExceptionalValue recovery.
+
+Thin wrapper over xmlschema with two-tier error classification and the SDC4
+"quarantine-and-tag" recovery pattern (ISO 21090 ExceptionalValues).
+"""
+
+__version__ = "4.3.0"
+
+# etree_tostring is re-exported from xmlschema so callers can serialize the
+# ElementTree returned by validate_with_recovery() without importing xmlschema
+# directly. The import location moved across xmlschema versions; try both.
+try:  # xmlschema >= 2.x
+    from xmlschema import etree_tostring
+except ImportError:  # pragma: no cover - fallback for older layouts
+    from xmlschema.etree import etree_tostring
+
+from .validator import (
+    SDC4Validator,
+    ValidationResult,
+    validate_with_recovery,
+)
+from .error_classifier import ErrorClassifier
+from .error_mapper import ErrorMapper
+from .instance_modifier import InstanceModifier
+from .exceptions import SDC4StructuralValidationError
+from .constants import (
+    ErrorTier,
+    ExceptionalValueType,
+    EXCEPTIONAL_VALUE_TYPES,
+)
+from .schema_checker import (
+    validate_sdc4_schema_compliance,
+    assert_sdc4_schema_compliance,
+    SDC4SchemaValidationError,
+)
+
+# Intentionally NOT exporting XMLSchema11 — SDCStudio's fallback import handles this.
+
+__all__ = [
+    "__version__",
+    "SDC4Validator",
+    "ValidationResult",
+    "ErrorClassifier",
+    "ErrorMapper",
+    "InstanceModifier",
+    "ErrorTier",
+    "ExceptionalValueType",
+    "EXCEPTIONAL_VALUE_TYPES",
+    "SDC4StructuralValidationError",
+    "validate_with_recovery",
+    "etree_tostring",
+    "validate_sdc4_schema_compliance",
+    "assert_sdc4_schema_compliance",
+    "SDC4SchemaValidationError",
+]

sdcvalidator-4.3.0/src/sdcvalidator/constants.py

@@ -0,0 +1,162 @@
+#
+# Copyright 2025 Semantic Data Charter Foundation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+"""
+Constants and type definitions for SDC4 validation.
+"""
+
+from enum import Enum
+from typing import Dict
+
+# SDC4 Namespace URIs
+SDC4_NAMESPACE = "https://semanticdatacharter.com/ns/sdc4/"
+SDC4_META_NAMESPACE = "https://semanticdatacharter.com/ontology/sdc4-meta/"
+XSD_NAMESPACE = "http://www.w3.org/2001/XMLSchema"
+
+
+class ErrorTier(Enum):
+    """
+    Two-tier error classification for SDC4 validation.
+
+    STRUCTURAL (Tier 1): Unknown elements, wrong nesting, cardinality -> REJECT
+    SEMANTIC (Tier 2): Type errors, pattern violations, range constraints -> REPORT
+    """
+    STRUCTURAL = "structural"
+    SEMANTIC = "semantic"
+
+
+# Data-bearing elements in SDC4 schemas
+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 recoverable)
+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
+}
+
+
+class ExceptionalValueType(Enum):
+    """
+    SDC4 ExceptionalValue types based on ISO 21090 NULL Flavors.
+
+    These types indicate why data is missing or invalid. All types inherit
+    from ExceptionalValueType in the SDC4 reference model.
+    """
+
+    # Primary types for validation errors
+    INV = ("INV", "Invalid",
+           "The value as represented in the instance is not a member of the "
+           "set of permitted data values in the constrained value domain of a variable.")
+
+    OTH = ("OTH", "Other",
+           "The actual value is not a member of the permitted data values in the "
+           "variable (e.g., when the value of the variable is not by the coding system).")
+
+    UNC = ("UNC", "Unencoded",
+           "No attempt has been made to encode the information correctly but the "
+           "raw source information is represented, usually in free text.")
+
+    # Missing data types
+    NI = ("NI", "No Information",
+          "The value is exceptional (missing, omitted, incomplete, improper). "
+          "No information as to the reason for being an exceptional value is provided. "
+          "This is the most general exceptional value and the default.")
+
+    NA = ("NA", "Not Applicable",
+          "No proper value is applicable in this context (e.g., the number of "
+          "cigarettes smoked per day by a non-smoker subject).")
+
+    UNK = ("UNK", "Unknown",
+           "A proper value is applicable, but not known.")
+
+    ASKU = ("ASKU", "Asked but Unknown",
+            "Information was sought but not found (e.g., patient was asked but did not know).")
+
+    ASKR = ("ASKR", "Asked and Refused",
+            "Information was sought but refused to be provided (e.g., patient was "
+            "asked but refused to answer).")
+
+    NASK = ("NASK", "Not Asked",
+            "This information has not been sought (e.g., patient was not asked).")
+
+    NAV = ("NAV", "Not Available",
+           "This information is not available and the specific reason is not known.")
+
+    MSK = ("MSK", "Masked",
+           "There is information on this item available but it has not been provided "
+           "by the sender due to security, privacy or other reasons.")
+
+    # Special value types
+    DER = ("DER", "Derived",
+           "An actual value may exist, but it must be derived from the provided "
+           "information; usually an expression is provided directly.")
+
+    PINF = ("PINF", "Positive Infinity", "Positive infinity of numbers.")
+
+    NINF = ("NINF", "Negative Infinity", "Negative infinity of numbers.")
+
+    TRC = ("TRC", "Trace",
+           "The content is greater or less than zero but too small to be quantified.")
+
+    QS = ("QS", "Sufficient Quantity",
+          "The specific quantity is not known, but is known to non-zero and it is "
+          "not specified because it makes up the bulk of the material.")
+
+    def __init__(self, code: str, name: str, description: str):
+        self.code = code
+        self.ev_name = name
+        self.description = description
+
+    @classmethod
+    def from_code(cls, code: str) -> 'ExceptionalValueType':
+        """Get ExceptionalValueType from its code string."""
+        for ev_type in cls:
+            if ev_type.code == code:
+                return ev_type
+        raise ValueError(f"Unknown ExceptionalValue code: {code}")
+
+
+# Mapping of ExceptionalValue types to their codes and names
+EXCEPTIONAL_VALUE_TYPES: Dict[str, tuple] = {
+    ev_type.code: (ev_type.ev_name, ev_type.description)
+    for ev_type in ExceptionalValueType
+}
+
+# All ExceptionalValue code strings (used to detect existing EV elements)
+EXCEPTIONAL_VALUE_CODES = [ev_type.code for ev_type in ExceptionalValueType]
+
+# XPath pattern for locating data-bearing elements in SDC4 instances
+XDANY_TYPE_PATTERN = r"xd(?:string|count|quantity|boolean|file|link|temporal|ordinal|ratio|interval)-value"
+
+# 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']
+EXCEPTIONAL_VALUE_INSERT_BEFORE = ['vtb', 'vte', 'tr', 'modified', 'latitude', 'longitude']

sdcvalidator-4.3.0/src/sdcvalidator/error_mapper.py

@@ -0,0 +1,343 @@
+#
+# Copyright 2025 Semantic Data Charter Foundation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+"""
+Maps XML Schema validation errors to SDC4 ExceptionalValue types.
+
+Tiering (structural vs semantic) is delegated to ErrorClassifier so there is a
+single source of truth for that decision; this module adds only the mapping
+from a semantic error to the appropriate ExceptionalValue type.
+"""
+
+import re
+from typing import Optional, Callable, Dict, List
+from xmlschema.validators.exceptions import (
+    XMLSchemaValidationError,
+    XMLSchemaDecodeError,
+    XMLSchemaChildrenValidationError,
+)
+from .constants import ExceptionalValueType, STRUCTURAL_ELEMENTS
+from .error_classifier import ErrorClassifier
+
+
+class ErrorMapper:
+    """
+    Maps XMLSchema validation errors to appropriate SDC4 ExceptionalValue types.
+
+    The mapper uses a rule-based system to classify errors. Rules can be customized
+    or extended for domain-specific requirements.
+    """
+
+    def __init__(self, classifier: Optional[ErrorClassifier] = None):
+        """
+        Initialize the error mapper with default rules.
+
+        :param classifier: Optional ErrorClassifier used for the structural-vs-semantic
+                            decision. Defaults to a fresh ErrorClassifier so the tiering
+                            logic stays identical to SDC4Validator.validate().
+        """
+        self._classifier = classifier or ErrorClassifier()
+        self._rules: List[tuple[Callable, ExceptionalValueType]] = []
+        self._register_default_rules()
+
+    def _register_default_rules(self):
+        """Register the default error mapping rules."""
+        # Order matters - more specific rules should come first
+
+        # Missing required elements/attributes
+        self.add_rule(
+            lambda err: self._is_missing_required(err),
+            ExceptionalValueType.NI
+        )
+
+        # Type violations (wrong data type, invalid format)
+        self.add_rule(
+            lambda err: self._is_type_violation(err),
+            ExceptionalValueType.INV
+        )
+
+        # Pattern, facet, or constraint violations
+        self.add_rule(
+            lambda err: self._is_constraint_violation(err),
+            ExceptionalValueType.INV
+        )
+
+        # Enumeration violations
+        self.add_rule(
+            lambda err: self._is_enumeration_violation(err),
+            ExceptionalValueType.OTH
+        )
+
+        # Unexpected elements/attributes in strict contexts
+        self.add_rule(
+            lambda err: self._is_unexpected_content(err),
+            ExceptionalValueType.NA
+        )
+
+        # Encoding/format errors
+        self.add_rule(
+            lambda err: self._is_encoding_error(err),
+            ExceptionalValueType.UNC
+        )
+
+        # Default fallback
+        self.add_rule(
+            lambda err: True,  # Matches everything
+            ExceptionalValueType.NI
+        )
+
+    def add_rule(self, condition: Callable[[XMLSchemaValidationError], bool],
+                  ev_type: ExceptionalValueType):
+        """
+        Add a custom mapping rule.
+
+        :param condition: A callable that takes an error and returns True if the rule matches.
+        :param ev_type: The ExceptionalValueType to return when the rule matches.
+        """
+        self._rules.append((condition, ev_type))
+
+    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, or None if this is a structural
+                 element that should fail validation.
+        """
+        # 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
+
+        # Should never reach here due to default rule, but just in case
+        return ExceptionalValueType.NI
+
+    def is_structural_error(self, error: XMLSchemaValidationError) -> bool:
+        """
+        Classify an error as structural (Tier 1) vs semantic (Tier 2).
+
+        Delegated to ErrorClassifier so the tiering decision is identical to the
+        one used by SDC4Validator.validate().
+
+        :param error: The validation error to classify.
+        :return: True if structural (reject), False if semantic (quarantine).
+        """
+        return self._classifier.is_structural_error(error)
+
+    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
+    # =========================================================================
+
+    def _is_missing_required(self, error: XMLSchemaValidationError) -> bool:
+        """Check if error indicates missing required element/attribute."""
+        if not error.reason:
+            return False
+
+        reason = error.reason.lower()
+        # Use simple substring checks where possible; regex only where needed
+        keywords = [
+            'missing required',
+            'is not complete',
+        ]
+        if any(kw in reason for kw in keywords):
+            return True
+
+        patterns = [
+            r'required \S+ is missing',
+            r'element \S+ is required',
+            r'minimum \S+ is \d+',
+        ]
+        return any(re.search(pattern, reason) for pattern in patterns)
+
+    def _is_type_violation(self, error: XMLSchemaValidationError) -> bool:
+        """Check if error indicates wrong data type."""
+        # Decode errors are always type issues
+        if isinstance(error, XMLSchemaDecodeError):
+            return True
+
+        if not error.reason:
+            return False
+
+        reason = error.reason.lower()
+        keywords = [
+            'not a valid value',
+            'invalid value',
+            'is not valid for type',
+            'cannot be converted',
+            'expected type',
+            'wrong type',
+            'malformed',
+        ]
+        if any(kw in reason for kw in keywords):
+            return True
+
+        patterns = [
+            r'type \S+ does not match',
+            r'invalid\S* format',
+        ]
+        return any(re.search(pattern, reason) for pattern in patterns)
+
+    def _is_constraint_violation(self, error: XMLSchemaValidationError) -> bool:
+        """Check if error indicates constraint/facet violation."""
+        if not error.reason:
+            return False
+
+        reason = error.reason.lower()
+        keywords = [
+            'does not match pattern',
+            'length constraint',
+            'minlength', 'maxlength',
+            'mininclusive', 'maxinclusive',
+            'minexclusive', 'maxexclusive',
+            'totaldigits', 'fractiondigits',
+            'constraint',
+        ]
+        if any(kw in reason for kw in keywords):
+            return True
+
+        patterns = [
+            r'pattern\S* not matched',
+            r'assertion\S* failed',
+            r'exceeds\S* maximum',
+            r'below\S* minimum',
+        ]
+        return any(re.search(pattern, reason) for pattern in patterns)
+
+    def _is_enumeration_violation(self, error: XMLSchemaValidationError) -> bool:
+        """Check if error indicates enumeration violation."""
+        if not error.reason:
+            return False
+
+        reason = error.reason.lower()
+        keywords = [
+            'not in enumeration',
+            'invalid enumeration',
+        ]
+        if any(kw in reason for kw in keywords):
+            return True
+
+        patterns = [
+            r'not\S* allowed value',
+            r'not\S* permitted value',
+            r'value\S* not\S* allowed',
+        ]
+        return any(re.search(pattern, reason) for pattern in patterns)
+
+    def _is_unexpected_content(self, error: XMLSchemaValidationError) -> bool:
+        """Check if error indicates unexpected element/attribute."""
+        if isinstance(error, XMLSchemaChildrenValidationError):
+            # Check if it's an unexpected child element
+            if error.invalid_tag is not None:
+                return True
+
+        if not error.reason:
+            return False
+
+        reason = error.reason.lower()
+        keywords = [
+            'unexpected',
+            'not allowed',
+            'not permitted',
+            'extra element',
+            'unknown element',
+            'not expected',
+        ]
+        return any(kw in reason for kw in keywords)
+
+    def _is_encoding_error(self, error: XMLSchemaValidationError) -> bool:
+        """Check if error indicates encoding/format problem."""
+        if not error.reason:
+            return False
+
+        reason = error.reason.lower()
+        keywords = [
+            'encoding error',
+            'decode error',
+            'invalid character',
+            'whitespace',
+        ]
+        if any(kw in reason for kw in keywords):
+            return True
+
+        return bool(re.search(r'character\S* not\S* allowed', reason))
+
+    def get_error_summary(self, error: XMLSchemaValidationError,
+                          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, 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__,
+            'reason': error.reason or 'No reason provided',
+            'exceptional_value_type': ev_type.code,
+            'exceptional_value_name': ev_type.ev_name,
+            'description': ev_type.description,
+        }

sdcvalidator-4.3.0/src/sdcvalidator/exceptions.py

@@ -0,0 +1,63 @@
+#
+# Copyright 2025 Semantic Data Charter Foundation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+"""
+SDC4-specific exceptions for validation.
+"""
+
+from typing import List, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from xmlschema.validators.exceptions import XMLSchemaValidationError
+
+
+class SDC4StructuralValidationError(Exception):
+    """
+    Raised when structural validation fails (Tier 1 rejection).
+
+    This error indicates the XML document has structural violations
+    (unknown elements, wrong nesting, cardinality violations) that
+    cannot be recovered via ExceptionalValue quarantine.
+
+    Structural errors include:
+    - Unknown/unexpected elements not defined in the XSD
+    - Missing required child elements (incomplete content)
+    - Cardinality violations (minOccurs/maxOccurs)
+    - Incorrect element nesting
+
+    These errors represent potential security risks (e.g., mass assignment
+    attacks) and must be rejected outright rather than quarantined.
+    """
+
+    def __init__(self, errors: List['XMLSchemaValidationError'], message: str = None):
+        """
+        Initialize the structural validation error.
+
+        :param errors: List of structural validation errors that caused the rejection.
+        :param message: Optional custom message. If None, a message is built from errors.
+        """
+        self.errors = errors
+        if message is None:
+            message = self._build_message()
+        super().__init__(message)
+
+    def _build_message(self) -> str:
+        """Build a detailed error message from the list of structural errors."""
+        lines = ["Structural validation failed (Tier 1 rejection):"]
+        for i, error in enumerate(self.errors, 1):
+            reason = error.reason or str(error)
+            lines.append(f"  {i}. {reason}")
+            if error.path:
+                lines.append(f"     at: {error.path}")
+        return "\n".join(lines)
+
+    @property
+    def error_count(self) -> int:
+        """Return the number of structural errors."""
+        return len(self.errors)