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

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-mcp serve --mcp

Tools

Tool	Purpose
validate_instance	Validate an XML instance against its SDC4 XSD schema. Returns pass/fail with error count and classified errors.
validate_and_report	Validate an instance and return a detailed report with two-tier (structural vs semantic) error classification.
check_schema_compliance	Check whether an XSD schema follows SDC4 principles (restriction only, no xsd:extension). Does not validate instances.

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

Tier	Type	Examples	Action
1	Structural	Unknown elements, cardinality violations, wrong nesting	Reject
2	Semantic	Type errors, pattern violations, enumeration mismatches	Report

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