linkml-xsd 0.2.0__tar.gz

linkml_xsd-0.2.0/.gitignore

@@ -0,0 +1,33 @@
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Python cache
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+
+# Tool caches
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# Build artifacts
+build/
+dist/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# Downloaded test corpora (fetched by tools/fetch_corpora.py), keep the README
+tests/corpora/*
+!tests/corpora/README.md
+
+# Coverage artifacts
+.coverage
+coverage.xml
+htmlcov/

linkml_xsd-0.2.0/.gitlab-ci.yml

@@ -0,0 +1,156 @@
+image: python:3.14
+
+stages:
+  - test
+  - build
+  - release
+
+variables:
+  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
+  # setuptools_scm derives the version from git tags — needs full history.
+  GIT_DEPTH: 0
+
+cache:
+  paths:
+    - .cache/pip
+
+# Edge-testing: oldest supported (3.10, per requires-python) and newest (3.14).
+test:
+  stage: test
+  image: $PYTHON_IMAGE
+  parallel:
+    matrix:
+      - PYTHON_IMAGE: ["python:3.10", "python:3.14"]
+  before_script:
+    - pip install -e ".[dev]"
+  script:
+    - ruff check src tests
+    - ruff format --check src tests
+    - mypy src/linkml_to_xsd/
+    # Compliance + property tiers run on a plain checkout; corpus tiers skip.
+    - pytest -v --cov=linkml_to_xsd --cov-report=term
+  # Feeds the GitLab coverage badge (badges/main/coverage.svg).
+  coverage: '/TOTAL.*\s+(\d+%)$/'
+
+corpus:
+  stage: test
+  # Exercises the external-corpus smoke tier against LinkML's own schemas.
+  # allow_failure: a network hiccup fetching the corpus must not block the pipeline.
+  allow_failure: true
+  before_script:
+    - pip install -e ".[dev]"
+  script:
+    - python tools/fetch_corpora.py
+    - pytest -v tests/test_corpora.py
+
+build:
+  stage: build
+  before_script:
+    - pip install build
+  script:
+    - python -m build
+    - ls -l dist/
+  artifacts:
+    paths:
+      - dist/
+
+# On a version tag: collect the commit subjects since the previous tag as the
+# release notes (consumed by the `release` job below).
+release-notes:
+  stage: build
+  rules:
+    - if: '$CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+/'
+  script:
+    - PREV=$(git describe --tags --abbrev=0 "${CI_COMMIT_TAG}^" 2>/dev/null || true)
+    - if [ -n "$PREV" ]; then RANGE="${PREV}..${CI_COMMIT_TAG}"; else RANGE="${CI_COMMIT_TAG}"; fi
+    - echo "## linkml-to-xsd ${CI_COMMIT_TAG}" > release_notes.md
+    - echo "" >> release_notes.md
+    - git log --no-merges --pretty='- %s' ${RANGE} >> release_notes.md
+    - cat release_notes.md
+  artifacts:
+    paths:
+      - release_notes.md
+
+# On a version tag (v1.2.3): publish the wheel/sdist to this project's GitLab
+# package registry. Installable via:
+#   pip install linkml-to-xsd \
+#     --index-url https://gitlab.com/api/v4/projects/<PROJECT_ID>/packages/pypi/simple
+publish-registry:
+  stage: release
+  rules:
+    - if: '$CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+/'
+  needs: [build]
+  before_script:
+    - pip install twine
+  script:
+    - >
+      TWINE_USERNAME=gitlab-ci-token
+      TWINE_PASSWORD=${CI_JOB_TOKEN}
+      python -m twine upload
+      --repository-url ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/pypi
+      dist/*
+
+# Create the GitLab release entry for the tag, with the generated changelog.
+release:
+  stage: release
+  image: registry.gitlab.com/gitlab-org/release-cli:latest
+  rules:
+    - if: '$CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+/'
+  needs: [publish-registry, release-notes]
+  script:
+    - echo "Releasing $CI_COMMIT_TAG"
+  release:
+    tag_name: $CI_COMMIT_TAG
+    name: "linkml-to-xsd $CI_COMMIT_TAG"
+    description: release_notes.md
+
+# On a version tag: build the CLI image from the wheel and push it to this
+# project's GitLab container registry (public pulls, no rate-limit drama).
+#   docker run --rm registry.gitlab.com/glueswe/public/linkml:v0.1.0 --help
+docker-release:
+  stage: release
+  image: docker:27
+  services:
+    - docker:27-dind
+  rules:
+    - if: '$CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+/'
+  needs: [build]
+  script:
+    - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY
+    - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG -t $CI_REGISTRY_IMAGE:latest .
+    - docker push --all-tags $CI_REGISTRY_IMAGE
+
+# On a version tag: publish the wheel/sdist to the public PyPI registry using
+# PyPI trusted publishing (OIDC). Configure the publisher at:
+#   https://pypi.org/manage/account/publishing/
+# Project: linkml-xsd, namespace: glueswe, project: linkml, workflow: .gitlab-ci.yml
+publish-pypi:
+  stage: release
+  rules:
+    - if: '$CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+/'
+  needs: [build]
+  id_tokens:
+    PYPI_ID_TOKEN:
+      aud: pypi
+  before_script:
+    - pip install twine
+  script:
+    - |
+      python - <<'PY'
+      import json, os, urllib.request
+      oidc = os.environ["PYPI_ID_TOKEN"]
+      req = urllib.request.Request(
+          "https://pypi.org/_/oidc/mint-token",
+          data=json.dumps({"token": oidc}).encode(),
+          headers={"Content-Type": "application/json"},
+          method="POST",
+      )
+      resp = urllib.request.urlopen(req)
+      token = json.loads(resp.read())["token"]
+      with open("/tmp/pypi-token", "w") as f:
+          f.write(token)
+      PY
+    - >
+      TWINE_USERNAME=__token__
+      TWINE_PASSWORD=$(cat /tmp/pypi-token)
+      python -m twine upload dist/*

linkml_xsd-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+# Local hooks running the exact tool versions from `.[dev]` (no rev drift with
+# pyproject pins). Install once with: pre-commit install
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check
+        entry: ruff check --fix
+        language: system
+        types: [python]
+      - id: ruff-format
+        name: ruff format
+        entry: ruff format
+        language: system
+        types: [python]
+      - id: mypy
+        name: mypy (src)
+        entry: mypy src/linkml_to_xsd/
+        language: system
+        pass_filenames: false
+        files: ^src/

linkml_xsd-0.2.0/CITATION.cff

@@ -0,0 +1,21 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: "linkml-to-xsd"
+abstract: >-
+  Generator converting LinkML schemas to XML Schema (XSD 1.0/1.1) and
+  Schematron, following the LinkML generator conventions.
+type: software
+authors:
+  - family-names: Gutknecht
+    given-names: Christian
+    affiliation: "Glue Software Engineering AG"
+license: MIT
+repository-code: "https://gitlab.com/glueswe/public/linkml"
+keywords:
+  - LinkML
+  - XSD
+  - XML Schema
+  - Schematron
+  - schema generation
+  - Akoma Ntoso
+  - eCH-0296

linkml_xsd-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing
+
+Contributions are welcome — the project is built so that most improvements are
+**data, not code**.
+
+## Setup
+
+```bash
+pip install -e ".[dev]"
+pre-commit install          # ruff + mypy run on every commit
+```
+
+## Checks
+
+Exactly what CI runs:
+
+```bash
+ruff check src tests && ruff format --check src tests
+mypy src/linkml_to_xsd/
+pytest                       # 200+ tests, < 10 s
+```
+
+CI tests the oldest (3.10) and newest (3.14) supported Python.
+
+## Adding a feature mapping — one case, one option, one emitter change
+
+The house rule for every new LinkML→XSD capability:
+
+1. **Compliance case first** (test-first): `tests/compliance/<feature>/` with
+   `schema.yaml`, `valid/*.xml`, `invalid/*.xml` — see
+   [`tests/compliance/README.md`](tests/compliance/README.md). Watch it fail.
+2. If the mapping is a genuine *choice*, add a toggle to
+   `config.ConversionOptions` (validated `Literal`, documented default).
+3. Implement in the emitter (`emit/` for XSD, `schematron/` for rules);
+   profile-specific naming goes through `profile/`, never inline.
+4. `python tools/gen_golden.py <feature>` and **review** the golden XSD —
+   it is the contract, not just a snapshot.
+5. **Tag the case** in `tests/_coverage.py::CASE_FEATURES` —
+   `test_coverage.py` fails until you do (this keeps
+   [`docs/TEST_COVERAGE.md`](docs/TEST_COVERAGE.md) honest; regenerate it with
+   `python tools/coverage_matrix.py`).
+6. Update the mapping status in
+   [`docs/LINKML_XSD_MAPPING.md`](docs/LINKML_XSD_MAPPING.md).
+
+A construct you *cannot* express must be reported through
+`diagnostics.report_unsupported` — never dropped silently.
+
+## Merge requests
+
+- Branch from `main`; keep MRs focused (one feature/fix).
+- Plain commit messages: what changed and why, imperative subject line.
+- CI must be green; goldens regenerated intentionally (explain drift in the MR).
+- Architectural decisions get an ADR in [`docs/adr/`](docs/adr/).
+
+## Releases
+
+Maintainers tag `vX.Y.Z` on `main`; CI builds, publishes to the package
+registry, pushes the Docker image and creates the GitLab release with
+generated notes. Versions come from the tag (`setuptools_scm`) — never edit a
+version string by hand.

linkml_xsd-0.2.0/Dockerfile

@@ -0,0 +1,16 @@
+# linkml-to-xsd CLI image — for XML toolchains without a Python environment.
+#
+#   docker run --rm -v $PWD:/work registry.gitlab.com/glueswe/public/linkml:latest \
+#     /work/schema.yaml -o /work/schema.xsd
+#
+# CI builds this from the wheel produced by the `build` job (dist/ artifact);
+# for a local build run `python -m build` first.
+
+FROM python:3.14-slim
+
+COPY dist/*.whl /tmp/dist/
+RUN pip install --no-cache-dir /tmp/dist/*.whl && rm -rf /tmp/dist
+
+WORKDIR /work
+ENTRYPOINT ["gen-xsd"]
+CMD ["--help"]

linkml_xsd-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christian Gutknecht, Glue AG
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

linkml_xsd-0.2.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: linkml-xsd
+Version: 0.2.0
+Summary: Convert LinkML schemas to XSD 1.0/1.1 and Schematron.
+Author-email: Christian Gutknecht <christian.gutknecht@glue.ch>
+License: MIT
+Project-URL: Homepage, https://gitlab.com/glueswe/public/linkml
+Project-URL: Repository, https://gitlab.com/glueswe/public/linkml
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: lxml>=4.9
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: linkml-runtime>=1.8
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: hypothesis>=6.0; extra == "dev"
+Requires-Dist: xmlschema>=2.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: types-pyyaml; extra == "dev"
+Requires-Dist: lxml-stubs; extra == "dev"
+Requires-Dist: pre-commit>=3.0; extra == "dev"
+Dynamic: license-file
+
+# linkml-to-xsd
+
+[![pipeline](https://gitlab.com/glueswe/public/linkml/badges/main/pipeline.svg)](https://gitlab.com/glueswe/public/linkml/-/pipelines)
+[![coverage](https://gitlab.com/glueswe/public/linkml/badges/main/coverage.svg)](https://gitlab.com/glueswe/public/linkml/-/pipelines)
+[![release](https://gitlab.com/glueswe/public/linkml/-/badges/release.svg)](https://gitlab.com/glueswe/public/linkml/-/releases)
+[![python](https://img.shields.io/badge/python-3.10%E2%80%933.14-blue)](pyproject.toml)
+[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+> **Status 0.x** — the mapping is exercised by 200+ tests and at parity on a
+> real production schema, but the Python API may still change before 1.0.
+
+A Python library and CLI that converts [LinkML](https://linkml.io) schemas into
+[XML Schema (XSD)](https://www.w3.org/XML/Schema) — and, for constraints XSD
+cannot express, [Schematron](https://schematron.com). Built on
+[`linkml-runtime`](https://github.com/linkml/linkml-runtime)'s `SchemaView`, so
+`imports`, `mixins`, `slot_usage` and inlining are resolved by the reference
+implementation rather than re-guessed.
+
+## Features
+
+- **XSD 1.0** output: classes → `xs:complexType` + global element; `is_a` →
+  `xs:extension` (UPA-safe); mixins flattened; enums, user types with facets
+  (`pattern`, `minimum_value`, `maximum_value`); cardinality.
+- **References vs. inlining** follow LinkML semantics: a non-inlined class-range
+  slot with an identifier becomes a *reference*; `inlined`/`inlined_as_list`
+  produce nested elements.
+- **Identity constraints**: `identifier` → `xs:key`, `unique_keys` → `xs:unique`,
+  references → `xs:keyref` (real referential integrity).
+- **Value constraints**: `@default` from literal `ifabsent`, `@fixed` from
+  `equals_string`/`equals_number`.
+- **Documentation & metadata**: `description` → `xs:documentation`,
+  `class_uri`/`slot_uri`/`enum_uri`/`meaning` → `xs:appinfo`.
+- **XSD 1.1** (opt-in): class `rules` also emitted as `xs:assert`.
+- **Schematron**: class `rules` (precondition ⇒ postcondition) and boolean
+  combinators (`any_of`/`all_of`/`exactly_one_of`/`none_of`) as XPath assertions.
+- **Profiles**: the eCH-0296 / Akoma Ntoso annotation vocabulary
+  (`xml_element`, `xml_attribute`, `xml_namespace`, `xsd_mixed`,
+  `xsd_content_model`) via `--profile akn` — proven at parity on the real Fedlex
+  SR-101.
+- Example-XML generation and XSD validation helpers.
+
+## Installation
+
+From a checkout:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Released versions are published to PyPI and this project's GitLab package
+registry on every `vX.Y.Z` tag:
+
+```bash
+# PyPI (recommended)
+pip install linkml-xsd
+
+# GitLab package registry
+pip install linkml-xsd \
+  --index-url https://gitlab.com/api/v4/projects/83894258/packages/pypi/simple
+```
+
+Requires Python ≥ 3.10 (CI tests 3.10 and 3.14). Versions are derived
+from git tags (`setuptools_scm`) — no manual version bumps.
+
+**No Python at hand** (Java/XSLT toolchains)? Use the Docker image published
+on every release:
+
+```bash
+docker run --rm -v "$PWD":/work \
+  registry.gitlab.com/glueswe/public/linkml:latest /work/schema.yaml -o /work/schema.xsd
+```
+
+## Usage
+
+### CLI
+
+Two entry points: **`gen-xsd`** (the [linkml generator
+convention](https://linkml.io/linkml/generators/), like `gen-json-schema`; see
+[`docs/generators/xsd.md`](docs/generators/xsd.md)) and the richer `linkml2xsd`
+group (`convert` / `example` / `validate`).
+
+```bash
+# linkml-style generator CLI
+gen-xsd schema.yaml -o schema.xsd
+gen-xsd schema.yaml --xsd-version 1.1 --schematron schema.sch
+
+# Standard LinkML → XSD (targetNamespace derived from the schema id/default_prefix)
+linkml2xsd convert schema.yaml -o schema.xsd
+
+# eCH-0296 / Akoma Ntoso profile + a companion Schematron for rules
+linkml2xsd convert schema.yaml -o schema.xsd --profile akn --schematron schema.sch
+
+# Example XML instance / validate an instance against an XSD
+linkml2xsd example schema.yaml -o example.xml
+linkml2xsd validate example.xml --xsd schema.xsd
+```
+
+### Python API
+
+```python
+from linkml_to_xsd import XSDGenerator, SchematronGenerator, ConversionOptions
+
+options = ConversionOptions(profile="akn", xsd_version="1.1", emit_appinfo=True)
+xsd = XSDGenerator("schema.yaml", options=options).generate()
+
+sch_gen = SchematronGenerator("schema.yaml", options=options)
+sch = sch_gen.generate() if sch_gen.has_rules() else None
+```
+
+`XSDGenerator` accepts a file path, inline YAML, a dict, a `SchemaDefinition` or a
+`SchemaFrontend`.
+
+## Options (`ConversionOptions`)
+
+Every genuine mapping choice is a validated field with a default:
+
+| Option | Default | Effect |
+|--------|---------|--------|
+| `xsd_version` | `"1.0"` | `"1.1"` also emits `xs:assert` for rules |
+| `emit_schematron` | `False` | (API flag; the CLI uses `--schematron`) |
+| `inlining` | `"linkml"` | or `always_inline` / `always_reference` |
+| `reference_style` | `"identifier"` | or `uri` (`key`/`idref` planned) |
+| `emit_value_constraints` | `True` | facets / `@fixed` |
+| `emit_identity_constraints` | `True` | `xs:key`/`unique`/`keyref` |
+| `emit_documentation` / `emit_appinfo` | `True` / `False` | annotations |
+| `multilingual_documentation` | `False` | split `[en] … [de] …`-tagged descriptions into per-language `xs:documentation` |
+| `target_namespace` | `None` | override the derived namespace |
+| `profile` | `None` | e.g. `"akn"` |
+
+## Architecture
+
+```
+src/linkml_to_xsd/
+  config.py        # ConversionOptions — one toggle per mapping decision
+  frontend/        # SchemaFrontend over linkml-runtime SchemaView
+  emit/            # XSDGenerator (+ naming, typemap)
+  schematron/      # SchematronGenerator
+  rules.py         # shared rule → XPath compiler (Schematron + xs:assert)
+  profile/         # base (no-op) + akn (eCH-0296 / Akoma Ntoso)
+  cli.py  xml_generator.py
+```
+
+See [`docs/adr/`](docs/adr/) for architectural decisions (ADR 003 records the
+move to `SchemaView`) and [`docs/LINKML_XSD_MAPPING.md`](docs/LINKML_XSD_MAPPING.md)
+for the full LinkML ↔ XSD element mapping and current status.
+
+## Testing
+
+Multi-tier and documented in [`tests/README.md`](tests/README.md);
+[`docs/TEST_COVERAGE.md`](docs/TEST_COVERAGE.md) is the enforced feature × engine
+matrix.
+
+| Tier | Checks |
+|------|--------|
+| **Compliance** (`tests/compliance/*`) | one feature per case → XSD compiles, matches its golden, accepts/rejects the right instances |
+| **Coverage** | every case is feature-tagged; baseline features stay covered |
+| **Corpus** | real `kitchen_sink.yaml` + `meta.yaml` convert and compile |
+| **Property** (Hypothesis) | random supported schemas always compile |
+| **XSTS reference** | inventories XSD constructs LinkML can never emit |
+
+```bash
+pytest
+ruff check src tests && ruff format --check src tests
+mypy src/linkml_to_xsd/
+
+python tools/fetch_corpora.py [--xsts]   # opt-in corpora (git-ignored)
+python tools/gen_golden.py               # refresh golden XSDs after a change
+python tools/coverage_matrix.py          # regenerate docs/TEST_COVERAGE.md
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) — most improvements are data, not code:
+a new feature mapping is one compliance case + one option + one emitter change.
+
+## License
+
+MIT