io.github.SemanticDataCharter/sdcvalidator

sdcvalidator

SDC4 structural validator — a thin wrapper over xmlschema with two-tier error classification.

What it does

• Validates XML instances against SDC4 XSD schemas
• Classifies errors into structural (Tier 1: reject) vs semantic (Tier 2: report)
• Checks SDC4 schema compliance (no xsd:extension — only xsd:restriction)
• Strict validation by default — catches invalid restriction derivations (wrong element names, type mismatches) at schema load time
• Converts between XML and JSON using schema-aware conversion

Install

pip install sdcvalidator

Or from source:

git clone https://github.com/SemanticDataCharter/sdcvalidator.git
cd sdcvalidator
pip install -e .

Python API

from sdcvalidator import SDC4Validator, ErrorTier

# Validate an XML instance (strict mode by default)
validator = SDC4Validator("my_schema.xsd")
result = validator.validate("my_instance.xml")

if result.is_valid:
    print("Valid!")
else:
    for err in result.structural_errors:
        print(f"STRUCTURAL: {err.reason}")
    for err in result.semantic_errors:
        print(f"SEMANTIC: {err.reason}")

Validation modes

The validation parameter controls how strictly the XSD schema itself is checked when loaded:

• 'strict' (default) — Raises XMLSchemaParseError if the schema contains invalid restriction derivations (e.g., element names that don't match the base type). This is the recommended mode.
• 'lax' — Silently collects schema derivation errors without raising. Use only for pre-existing schemas known to have issues.
• 'skip' — Skips schema-level validation entirely.

# Explicit lax mode for legacy schemas
validator = SDC4Validator("legacy_schema.xsd", validation='lax')

Schema compliance checking

from sdcvalidator import validate_sdc4_schema_compliance, assert_sdc4_schema_compliance

# Check if a schema uses xsd:extension (not allowed in SDC4)
is_valid, errors = validate_sdc4_schema_compliance("schema.xsd")

# Or raise an exception
assert_sdc4_schema_compliance("schema.xsd")

Error classification

from sdcvalidator import ErrorClassifier, ErrorTier

classifier = ErrorClassifier()
tier = classifier.classify(some_xmlschema_error)
# ErrorTier.STRUCTURAL or ErrorTier.SEMANTIC

Exceptional Value recovery

A semantic (Tier 2) error does not have to reject a record. Recovery keeps the value and inserts an ISO 21090 ExceptionalValue beside it (Invalid, for a value that fails its type, pattern, range or enumeration), so the record says which value is unusable and why, and the rest of it stays usable.

from sdcvalidator import SDC4Validator, SDC4UnrecoverableError

v = SDC4Validator("dm-xxxx.xsd", validation="lax")
result = v.recover("record.xml")         # RecoveryResult; the source is never mutated
for r in result.recoveries:              # Recovery: path, code ("INV"), name, reason, inserted
    print(r.code, r.reason, r.path)
if not result.ok:                        # an error no ExceptionalValue covers
    print(result.unrecoverable)

tree = v.validate_with_recovery("record.xml", save=False)   # raises SDC4UnrecoverableError instead

• An ExceptionalValue the record already carries (a refusal, a masked field, written where the record was made) is kept, and covers its value; recovery never inserts a second one. remove_existing_ev=True removes them first.
• An error recovery cannot cover is returned in unrecoverable by recover(), and raised as SDC4UnrecoverableError by validate_with_recovery(); it is never skipped.
• Structural (Tier 1) errors raise SDC4StructuralValidationError.
• Pass an XMLResource when the record carries prefixed QNames in content (xsi:type="sdc4:...").

XML/JSON conversion

from sdcvalidator.converters import xml_to_json, json_to_xml

# XML -> JSON (schema-aware)
data = xml_to_json("instance.xml", schema_path="schema.xsd")

# JSON -> XML
json_to_xml(data, "schema.xsd", "output.xml")

CLI

sdcvalidate — Validate XML against schema

# Basic validation
sdcvalidate schema.xsd instance.xml

# JSON output
sdcvalidate schema.xsd instance.xml --json

# Skip SDC4 compliance check
sdcvalidate --no-compliance-check schema.xsd instance.xml

Exit codes: 0 valid, 1 semantic errors only, 2 structural errors.

sdcvalidator-xml2json — Convert XML to JSON

sdcvalidator-xml2json instance.xml --schema schema.xsd
sdcvalidator-xml2json instance.xml -o output.json

sdcvalidator-json2xml — Convert JSON to XML

sdcvalidator-json2xml data.json schema.xsd -o output.xml

MCP Server

sdcvalidator ships a stdio MCP (Model Context Protocol) server so any MCP-capable agent can validate SDC4 data without importing the Python library. It implements JSON-RPC 2.0 directly over stdio — no external MCP SDK dependency.

sdcvalidator            # what an MCP registry client runs (uvx sdcvalidator)
sdcvalidator mcp        # the same, spelled like the other Semantic Data Charter servers
sdcvalidator-mcp serve --mcp   # still works for existing client configurations

A client configuration needs only "command": "uvx", "args": ["sdcvalidator"].

Tools

validate_instance and validate_and_report take schema_path and instance_path, plus an optional check_compliance boolean (default true). check_schema_compliance takes schema_path only.

Two-Tier Error Classification

SDC4 Schema Compliance

SDC4 data models must use xsd:restriction only — never xsd:extension. This enforces separation of structure (reference model) and semantics (data models), guaranteeing global interoperability.

The validator checks this by default and rejects schemas that violate this principle.

Status

Production-ready. Available on PyPI under Apache 2.0.

License

Apache License 2.0 — see LICENSE.

Links

• Semantic Data Charter
• SDC4 Reference Model
• xmlschema