{
  "markdown": "# sdcvalidator\n\n<!-- mcp-name: io.github.SemanticDataCharter/sdcvalidator -->\n\n**SDC4 structural validator** — a thin wrapper over [xmlschema](https://pypi.org/project/xmlschema/) with two-tier error classification.\n\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n\n## What it does\n\n- Validates XML instances against SDC4 XSD schemas\n- Classifies errors into **structural** (Tier 1: reject) vs **semantic** (Tier 2: report)\n- Checks SDC4 schema compliance (no `xsd:extension` — only `xsd:restriction`)\n- **Strict validation by default** — catches invalid restriction derivations (wrong element names, type mismatches) at schema load time\n- Converts between XML and JSON using schema-aware conversion\n\n## Install\n\n```bash\npip install sdcvalidator\n```\n\nOr from source:\n\n```bash\ngit clone https://github.com/SemanticDataCharter/sdcvalidator.git\ncd sdcvalidator\npip install -e .\n```\n\n## Python API\n\n```python\nfrom sdcvalidator import SDC4Validator, ErrorTier\n\n# Validate an XML instance (strict mode by default)\nvalidator = SDC4Validator(\"my_schema.xsd\")\nresult = validator.validate(\"my_instance.xml\")\n\nif result.is_valid:\n    print(\"Valid!\")\nelse:\n    for err in result.structural_errors:\n        print(f\"STRUCTURAL: {err.reason}\")\n    for err in result.semantic_errors:\n        print(f\"SEMANTIC: {err.reason}\")\n```\n\n### Validation modes\n\nThe `validation` parameter controls how strictly the XSD schema itself is checked when loaded:\n\n- **`'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.\n- **`'lax'`** — Silently collects schema derivation errors without raising. Use only for pre-existing schemas known to have issues.\n- **`'skip'`** — Skips schema-level validation entirely.\n\n```python\n# Explicit lax mode for legacy schemas\nvalidator = SDC4Validator(\"legacy_schema.xsd\", validation='lax')\n```\n\n### Schema compliance checking\n\n```python\nfrom sdcvalidator import validate_sdc4_schema_compliance, assert_sdc4_schema_compliance\n\n# Check if a schema uses xsd:extension (not allowed in SDC4)\nis_valid, errors = validate_sdc4_schema_compliance(\"schema.xsd\")\n\n# Or raise an exception\nassert_sdc4_schema_compliance(\"schema.xsd\")\n```\n\n### Error classification\n\n```python\nfrom sdcvalidator import ErrorClassifier, ErrorTier\n\nclassifier = ErrorClassifier()\ntier = classifier.classify(some_xmlschema_error)\n# ErrorTier.STRUCTURAL or ErrorTier.SEMANTIC\n```\n\n### XML/JSON conversion\n\n```python\nfrom sdcvalidator.converters import xml_to_json, json_to_xml\n\n# XML -> JSON (schema-aware)\ndata = xml_to_json(\"instance.xml\", schema_path=\"schema.xsd\")\n\n# JSON -> XML\njson_to_xml(data, \"schema.xsd\", \"output.xml\")\n```\n\n## CLI\n\n### `sdcvalidate` — Validate XML against schema\n\n```bash\n# Basic validation\nsdcvalidate schema.xsd instance.xml\n\n# JSON output\nsdcvalidate schema.xsd instance.xml --json\n\n# Skip SDC4 compliance check\nsdcvalidate --no-compliance-check schema.xsd instance.xml\n```\n\nExit codes: `0` valid, `1` semantic errors only, `2` structural errors.\n\n### `sdcvalidator-xml2json` — Convert XML to JSON\n\n```bash\nsdcvalidator-xml2json instance.xml --schema schema.xsd\nsdcvalidator-xml2json instance.xml -o output.json\n```\n\n### `sdcvalidator-json2xml` — Convert JSON to XML\n\n```bash\nsdcvalidator-json2xml data.json schema.xsd -o output.xml\n```\n\n## MCP Server\n\n`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.\n\n```bash\nsdcvalidator-mcp serve --mcp\n```\n\n### Tools\n\n| Tool | Purpose |\n|------|---------|\n| `validate_instance` | Validate an XML instance against its SDC4 XSD schema. Returns pass/fail with error count and classified errors. |\n| `validate_and_report` | Validate an instance and return a detailed report with two-tier (structural vs semantic) error classification. |\n| `check_schema_compliance` | Check whether an XSD schema follows SDC4 principles (restriction only, no `xsd:extension`). Does not validate instances. |\n\n`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.\n\n## Two-Tier Error Classification\n\n| Tier | Type | Examples | Action |\n|------|------|----------|--------|\n| 1 | Structural | Unknown elements, cardinality violations, wrong nesting | **Reject** |\n| 2 | Semantic | Type errors, pattern violations, enumeration mismatches | **Report** |\n\n## SDC4 Schema Compliance\n\nSDC4 data models must use `xsd:restriction` only — never `xsd:extension`. This enforces separation of structure (reference model) and semantics (data models), guaranteeing global interoperability.\n\nThe validator checks this by default and rejects schemas that violate this principle.\n\n## Status\n\nProduction-ready. Available on [PyPI](https://pypi.org/project/sdcvalidator/) under Apache 2.0.\n\n## License\n\nApache License 2.0 — see [LICENSE](LICENSE).\n\n## Links\n\n- [Semantic Data Charter](https://semanticdatacharter.com)\n- [SDC4 Reference Model](https://semanticdatacharter.com/ns/sdc4/)\n- [xmlschema](https://pypi.org/project/xmlschema/)\n",
  "bytes": 5462,
  "sha": "edfe4b408d36f466f4aa13e7e742a6dbff1caa735798a3d88dfc82e74a3f546d",
  "repo_slug": "semanticdatacharter/sdcvalidator",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_semanticdatacharter_sdcvalidat_601977ec/readme"
}