README.md

Official UMF Python support

umf-core provides the umf import namespace for the current UMF language. The authored spec/metamodel/umf.yaml generates the packaged JSON Schemas, portable constraint programs and Python shape data. Pydantic provides access models; it does not define a competing format. Consumer extensions and execution policies remain in consumer repositories.

Install the qualified release wheel:

pip install https://github.com/DocumentDrivenDX/umf/releases/download/umf-v0.5.1/umf_core-0.10.0-py3-none-any.whl

For development, use pip install ./python from a checkout. PyPI publication is not configured; the GitHub release and its checksums identify the distributed wheel. The separately distributed experimental umf_access host adapter is not required to read or validate UMF documents.

from umf import read_document, validate_document, write_document

document = read_document('''
umf: "0.10.0"
id: orders
vocabularies: {}
modules: []
''', format="yaml")
result = validate_document(document)
assert result.valid and result.complete
# Unknown or unregistered extension meaning can instead make complete false.
text = write_document(document, format="yaml")
assert read_document(text, format="yaml").to_dict() == document.to_dict()

Use canonical camelCase property names when constructing models. to_dict() preserves unknown content and field presence; checked_copy() revalidates mutable model state. Current APIs accept core 0.10.0; retired core dispatch and upgrade/rollback paths are removed. Structural checks and ordered core semantic constraints use generated data through bounded generic interpreters. Installed Python and TypeScript share 139 frozen conformance vectors; this is not a claim of parity for every TypeScript adapter or native execution API.

Unknown vocabulary versions, labels and qualifiers remain serializable and make interpretation incomplete. Consumers must refuse execution when their binding cannot interpret required semantics. Exact numeric token carriers, UUID/128-bit carriers, explicit null and omission retain their separate meanings.

Extensions register explicitly through Registry and Extension with exact versions, permitted scopes, a JSON Schema and optional semantic callback. Callbacks receive copies; schema references must be local. Documents never authorize loading code or fetching schemas. schema_validator() is reusable for consumer-owned schemas and honors their declared dialect.

Run python -m pytest python/tests from the repository root. Build with uv build --project python. The source distribution includes the current generated resources and supports building a wheel without the repository. Release checks install the actual wheel in an isolated environment, compare its packaged resource bytes and replay the shared core conformance corpus.