MaiML-Domain

MaiML(JIS K 0200 / MaiML-Schema-1_0)の XSD 定義に対応した Python ドメインモデルライブラリです。 MaiML-Library organization におけるSDK (PyMaiML など)や周辺ツールが共通して利用する、 基盤となる共通データモデルです。

特徴

• MaiML の各 XSD(maiml-core.xsd / maiml-property.xsd / maiml-document.xsd / maiml-protocol.xsd / maiml-data.xsd / maiml-eventLog.xsd / maiml-pnml.xsd / maiml-refTypes.xsd / maiml-simpleTypes.xsd / maiml.xsd)に 1:1 で対応したドメインクラスを提供します。
• property/content 型はスカラー型 23 種・property 側リスト型 23 種(PropertyListType 含む)・content 側リスト型 22 種を完全に網羅しています。
• 暗号化されたプロパティ/コンテンツ(encryptionGroup)用の EncryptionType にも対応しています(平文フィールドとの排他はコンストラクタで検証します)。
• 依存ライブラリなし(Python 標準ライブラリのみ)。

インストール

開発版をローカルからインストールする場合:

git clone https://github.com/MaiML-Library/MaiML-Domain.git
cd MaiML-Domain
pip install -e .

使い方

from datetime import datetime
from maiml_domain import (
    DocumentType, VendorType, OwnerType, CreatorType, VendorRefType,
)

vendor = VendorType(id="v1")
owner = OwnerType(id="o1")
creator = CreatorType(id="c1", vendor_refs=[VendorRefType(id="vr1", ref="v1")])

document = DocumentType(
    id="d1",
    date=datetime.now(),
    creators=[creator],
    vendors=[vendor],
    owners=[owner],
)

パッケージ内モジュールと対応 XSD・主なクラスの詳細な一覧は maiml_domain/README.md を参照してください。

MaiML-Library における位置づけ

MaiML-Library organization は次のような階層構造を基本方針としています(.github の組織方針を参照)。

• MaiML-Domain(本リポジトリ) -- JIS K 0200 / MaiML XSDに対応する、 言語SDK共通のドメインモデル。MaiMLの構造・型・ローカル制約を表現する。 Pythonでの実装
• PyMaiML(MaiML-Library/PyMaiML) -- MaiML-Domainを基盤として、MaiML文書の読み書き、検証、検索、構築、 意味的操作を提供するPython SDK。他言語向けSDKを追加する場合、本 リポジトリはPython実装のため直接は共有できず、その言語向けに本 リポジトリ相当のドメインモデルを別途実装することになる
• API・ツール群 -- SDK / ドメイン層に依存

バリデーションの範囲

本リポジトリは「純粋なデータモデル」を掲げていますが、完全に無検証というわけではありません。 責務境界の基準は次の一文です(MaiML_Domain_XSD_builtin_validation_policy.mdで確定した方針)。

MaiML-Domainは、単一のDomainフィールドまたは単一オブジェクトのみから判定でき、 XML namespace contextや他オブジェクトとの関係を必要としない制約を検証する。 namespaceの解決、idの文書内一意性、IDREFの参照先解決、その他のオブジェクト間・ セクション間の整合性検証はPyMaiMLが担う。

「単一フィールドのみ」ではなく「単一オブジェクト」まで含めているのは、encryptionと 平文フィールドのxs:choice排他検証のように、同一オブジェクト内の複数フィールドを 見る必要はあるが文書全体のコンテキストは不要な検証を含めるためです。

対象の具体例(minOccurs/maxOccurs、xs:choiceの排他性、required属性、simpleTypeの うち対応している字句・値域制約など)は各クラスのコンストラクタで検証し、違反時には ValueError/TypeErrorを送出します(例: HasIdAttributeType.idが空文字またはNCNameとして 不正なら拒否、GlobalObjectContentでencryptionと平文フィールドを同時に指定すると拒否、 integer系の値域超過・UUID字句不正・xs:decimalの非有限値(NaN/Infinity)を拒否、xs:ID/ xs:IDREFのNCName字句制約、xs:QNameのプレフィックス:ローカル名構文、xs:languageの パターンなど)。xs:QNameの字句検証はQualifiedNameTypeだけでなく、全property/content 共通のUncertaintyBaseType.key属性(これ自体もxs:QName)にも適用しています。

もう一つの原則として、MaiML-DomainはXML上の元の字句表現ではなく、XSDの値空間に対応する Python値を表現します(例: xs:dateTime → datetime、xs:decimal → Decimal/int、 xs:base64Binary → bytes)。したがって元XMLの文字列表現を完全に保存・再現することは 目的としていません。

1.0.0以降、この節に記載した検証・型変換の挙動はSemVer互換性保証の対象になります。 対象範囲の詳細(クラスのコンストラクタ引数・公開属性・例外の型が対象、例外メッセージの 文言や内部ヘルパー関数は対象外、など)は CONTRIBUTING.mdの「公開APIの範囲(1.0.0のSemVer保証対象)」節を参照してください。

XSD built-in型ごとの責務

xs:tokenのwhiteSpace collapseは「拒否のための検証」というより値の正規化であり、 コンストラクタで入力値を暗黙に書き換えると「渡した値がそのまま保持される」という直感を 崩しかねないため、現時点では積極的な正規化をDomainへ導入していません。xs:anyURIも urn:example:dataや相対パスなど多様な形式を許容するため、HTTP(S)スキームや到達可能性を 要求する専用バリデータとしては扱いません。いずれも必要性を確認したうえで別Issueとして 検討する対象です。

一方、複数要素・複数セクションをまたいで初めて判断できる検証(id/refの整合性、 ref参照先の型チェック、イベントログのlifecycle:transition="complete"必須化など JIS / MaiML AI Common Specificationの業務ルール)は、あえて本リポジトリの責務外としています。 これらはSDK層(PyMaiMLのpymaiml.validation) が担います。新しい検証ロジックをどちらに実装すべきか迷ったら、この基準(単一フィールド/ 単一オブジェクトだけで判定できるか否か)に照らして判断してください。

コントリビューション

仕様に関わる変更は Issue / Pull Request で議論のうえ、CHANGELOG.md に記録してください。 バグ報告・ドキュメント改善なども歓迎します。詳しい手順(XSD更新時の対応・ _StrictAttributesMixinの規約・バリデーションの範囲など)は CONTRIBUTING.md を参照してください。

ライセンス

Apache License 2.0 (LICENSE を参照)