sdcvalidator

sdcvalidator

SDC4 構造バリデーター — 2 段階のエラー分類機能を備えた xmlschema の薄いラッパーです。

機能

• XML インスタンスを SDC4 XSD スキーマに照らして検証します
• エラーを構造エラー（Tier 1：拒否）と意味エラー（Tier 2：報告）に分類します
• SDC4 スキーマへの準拠をチェックします（xsd:extension は不可。xsd:restriction のみ）
• デフォルトで厳密に検証します — 無効な制限派生（誤った要素名、型の不一致）をスキーマの読み込み時に検出します
• スキーマを考慮した変換により、XML と JSON を相互変換します

インストール

pip install sdcvalidator

または、ソースからインストールします。

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 パラメーターは、XSD スキーマの読み込み時にスキーマ自体をどの程度厳密にチェックするかを制御します。

• 'strict'（デフォルト）— スキーマに無効な制限派生（例：ベース型と一致しない要素名）が含まれている場合、XMLSchemaParseError を発生させます。推奨モードです。
• 'lax' — 例外を発生させずに、スキーマ派生エラーを収集します。問題があることがわかっている既存のスキーマに限って使用してください。
• 'skip' — スキーマレベルの検証を完全にスキップします。

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

スキーマ準拠チェック

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")

エラー分類

from sdcvalidator import ErrorClassifier, ErrorTier

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

Exceptional Value の回復

意味エラー（Tier 2）があっても、レコードを必ずしも拒否する必要はありません。回復では値を保持し、その隣に ISO 21090 の ExceptionalValue（型、パターン、範囲、列挙値に適合しない値には Invalid）を挿入します。これにより、レコード内で使用できない値とその理由が示され、残りの部分は引き続き利用できます。

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

• レコードにすでに含まれている ExceptionalValue（レコード作成時に記録された拒否やマスク済みフィールド）は保持され、その値をカバーします。回復処理で 2 つ目が挿入されることはありません。remove_existing_ev=True を指定すると、最初に既存のものを削除します。
• 回復でカバーできないエラーは recover() の unrecoverable に返され、validate_with_recovery() では SDC4UnrecoverableError として発生します。スキップされることはありません。
• 構造エラー（Tier 1）は SDC4StructuralValidationError を発生させます。
• レコードの内容にプレフィックス付き QName（xsi:type="sdc4:..."）が含まれる場合は、XMLResource を渡してください。

XML/JSON 変換

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 — XML をスキーマに照らして検証

# 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

終了コード：0 は有効、1 は意味エラーのみ、2 は構造エラーです。

sdcvalidator-xml2json — XML を JSON に変換

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

sdcvalidator-json2xml — JSON を XML に変換

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

MCP サーバー

sdcvalidator には stdio MCP（Model Context Protocol）サーバーが付属しているため、MCP 対応のエージェントであれば Python ライブラリをインポートせずに SDC4 データを検証できます。JSON-RPC 2.0 を stdio 経由で直接実装しており、外部 MCP SDK への依存はありません。

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

クライアントの設定に必要なのは "command": "uvx", "args": ["sdcvalidator"] だけです。

ツール

ツール	説明
validate_instance	XML インスタンスを対応する SDC4 XSD スキーマに照らして検証します。エラー数と分類済みエラーを含む合否を返します。
validate_and_report	インスタンスを検証し、構造エラーと意味エラーの 2 段階分類を含む詳細なレポートを返します。
check_schema_compliance	XSD スキーマが SDC4 の原則（xsd:restriction のみ、xsd:extension は不可）に準拠しているかチェックします。インスタンスは検証しません。

validate_instance と validate_and_report は schema_path と instance_path に加え、省略可能な check_compliance ブール値（デフォルトは true）を受け取ります。check_schema_compliance が受け取るのは schema_path のみです。

2 段階のエラー分類

段階	種類	例	アクション
1	構造	未知の要素、出現回数制約違反、誤った入れ子	拒否
2	セマンティック	型エラー、パターン違反、列挙値の不一致	報告、または例外値で回復

SDC4 スキーマへの準拠

SDC4 データモデルでは、xsd:restriction のみを使用する必要があります。xsd:extension は使用しないでください。これにより、構造（参照モデル）とセマンティクス（データモデル）が分離され、グローバルな相互運用性が保証されます。

バリデーターはデフォルトでこれをチェックし、この原則に違反するスキーマを拒否します。

ステータス

本番環境で使用可能です。Apache 2.0 の下で PyPI から入手できます。

ライセンス

Apache License 2.0 — LICENSE を参照してください。

リンク

• Semantic Data Charter
• SDC4 Reference Model
• xmlschema