linkml-xsd 0.2.0__py3-none-any.whl

linkml_to_xsd/__init__.py

@@ -0,0 +1,19 @@
+"""linkml-to-xsd: convert LinkML schemas to XSD (and example XML)."""
+
+from __future__ import annotations
+
+from .config import ConversionOptions
+from .emit import XSDGenerator
+from .frontend import SchemaFrontend
+from .schematron import SchematronGenerator
+from .xml_generator import XMLExampleGenerator
+from .xsdgen import XsdGenerator
+
+__all__ = [
+    "ConversionOptions",
+    "SchemaFrontend",
+    "SchematronGenerator",
+    "XMLExampleGenerator",
+    "XSDGenerator",
+    "XsdGenerator",
+]

linkml_to_xsd/cli.py

@@ -0,0 +1,81 @@
+"""Command-line interface for linkml-to-xsd."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+from lxml import etree
+
+from linkml_to_xsd.xml_generator import XMLExampleGenerator
+from linkml_to_xsd.xsdgen import cli as gen_xsd_cli
+
+
+@click.group()
+@click.version_option(package_name="linkml-xsd")
+def cli() -> None:
+    """Convert LinkML schemas to XSD and generate example XML."""
+
+
+# `linkml2xsd convert` is the same command as the standalone `gen-xsd` script —
+# one implementation, one option surface (avoids the two drifting apart).
+cli.add_command(gen_xsd_cli, name="convert")
+
+
+@cli.command()
+@click.argument("schema", type=click.Path(exists=True, path_type=Path))
+@click.option(
+    "--output",
+    "-o",
+    type=click.Path(path_type=Path),
+    help="Output XML file. If omitted, prints to stdout.",
+)
+@click.option(
+    "--root-class",
+    default=None,
+    help="Root class to use for the example. Defaults to a leaf class.",
+)
+@click.option(
+    "--target-namespace",
+    default=None,
+    help="Namespace for the XML. Default: the same as `convert` derives, so the "
+    "example validates against the generated XSD.",
+)
+def example(
+    schema: Path, output: Path | None, root_class: str | None, target_namespace: str | None
+) -> None:
+    """Generate an example XML instance from a LinkML schema."""
+    # The generator derives the namespace exactly like `convert`, so the
+    # example validates against the generated XSD out of the box.
+    generator = XMLExampleGenerator(schema_path=schema, target_namespace=target_namespace)
+    xml_text = generator.generate(root_class=root_class)
+
+    if output:
+        output.write_text(xml_text, encoding="utf-8")
+        click.echo(f"Wrote example XML to {output}")
+    else:
+        click.echo(xml_text)
+
+
+@cli.command()
+@click.argument("xml", type=click.Path(exists=True, path_type=Path))
+@click.option(
+    "--xsd",
+    required=True,
+    type=click.Path(exists=True, path_type=Path),
+    help="XSD file to validate against.",
+)
+def validate(xml: Path, xsd: Path) -> None:
+    """Validate an XML file against an XSD."""
+    with xsd.open("rb") as xsd_fh:
+        xmlschema_doc = etree.parse(xsd_fh)
+    xmlschema = etree.XMLSchema(xmlschema_doc)
+
+    with xml.open("rb") as xml_fh:
+        xml_doc = etree.parse(xml_fh)
+
+    try:
+        xmlschema.assertValid(xml_doc)
+        click.echo(f"{xml} is valid against {xsd}.")
+    except etree.DocumentInvalid as exc:
+        raise click.ClickException(f"Validation failed: {exc}") from exc

linkml_to_xsd/config.py

@@ -0,0 +1,123 @@
+"""Conversion options — one toggle per LinkML→XSD mapping decision.
+
+Every place where the mapping from LinkML to XSD is genuinely a *choice* (inline
+vs reference a class, XSD 1.0 + Schematron vs XSD 1.1 assertions, how to render
+identity constraints, …) is exposed here rather than hard-coded, so callers can
+pick a behaviour without forking the emitters. Defaults encode the project's
+recommended mapping; the CLI and the public API both accept a
+``ConversionOptions`` instance.
+
+The dataclass is frozen (options are a value, passed around, never mutated) and
+validates its ``Literal`` fields at construction so a bad CLI string fails fast
+with a clear message rather than deep inside an emitter.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, get_args, get_origin, get_type_hints
+
+#: How a slot whose range is a class is rendered in XSD.
+#: ``linkml`` honours LinkML's own inlining inference (a non-inlined slot to a
+#: class with an identifier becomes a *reference*); the other two force it.
+InliningPolicy = Literal["linkml", "always_inline", "always_reference"]
+
+#: How a *reference* (non-inlined class range) is expressed in XSD.
+#: ``identifier`` types the referencing element as the referenced class's
+#: identifier value (a soft reference); ``uri`` types it ``xs:anyURI``.
+#: ``key`` / ``idref`` (full XSD identity constraints) are the design target and
+#: currently fall back to the ``identifier`` rendering.
+ReferenceStyle = Literal["identifier", "uri", "key", "idref"]
+
+#: XSD flavour of the primary schema output. ``1.1`` unlocks ``xs:assert`` /
+#: ``xs:alternative`` for constraints XSD 1.0 cannot express; ``1.0`` routes
+#: those to Schematron instead (see ``emit_schematron``).
+XSDVersion = Literal["1.0", "1.1"]
+
+#: How a ``designates_type`` discriminator drives polymorphic typing.
+#: ``base`` (default, XSD 1.0): the element uses the base class type, the
+#: designator is a plain field. ``alternative``: emit ``xs:alternative``
+#: conditional type assignment picking the concrete subtype by the designator
+#: value (XSD 1.1 construct).
+TypeDesignatorStrategy = Literal["base", "alternative"]
+
+#: How an ``ArrayExpression`` slot is rendered. ``nested`` (default): one wrapper
+#: element per dimension (named by the dimension alias), with occurrence bounds
+#: from the dimension cardinalities. ``flat``: a single unbounded element — the
+#: shape is not enforced (also the automatic fallback for any-shape arrays,
+#: whose dimension count XSD cannot express).
+ArrayStrategy = Literal["nested", "flat"]
+
+#: Content model for a class's element children.
+ContentModel = Literal["sequence", "all"]
+
+#: XSD ``elementFormDefault`` / ``attributeFormDefault``.
+FormDefault = Literal["qualified", "unqualified"]
+
+#: What to do when a LinkML construct has no representation under the current
+#: options: silently skip, record a diagnostic, or raise.
+UnsupportedPolicy = Literal["ignore", "warn", "error"]
+
+
+@dataclass(frozen=True)
+class ConversionOptions:
+    """Immutable bundle of every LinkML→XSD mapping choice."""
+
+    # -- output targets ----------------------------------------------------
+    xsd_version: XSDVersion = "1.0"
+    #: Emit a companion Schematron (.sch) for constraints XSD (of the chosen
+    #: version) cannot express — boolean slot expressions, cross-field rules, …
+    emit_schematron: bool = False
+
+    # -- structural mapping of class-range slots ---------------------------
+    inlining: InliningPolicy = "linkml"
+    reference_style: ReferenceStyle = "identifier"
+    type_designator: TypeDesignatorStrategy = "base"
+    array_strategy: ArrayStrategy = "nested"
+    content_model: ContentModel = "sequence"
+
+    # -- constraints -------------------------------------------------------
+    #: ``minimum_value`` / ``maximum_value`` / ``pattern`` → XSD facets.
+    emit_value_constraints: bool = True
+    #: ``identifier`` / ``key`` / ``unique_keys`` → ``xs:key`` / ``xs:unique``.
+    emit_identity_constraints: bool = True
+    #: ``equals_expression`` / ``string_serialization`` → consistency checks
+    #: (Schematron asserts, and ``xs:assert`` in the 1.1 mode) for the
+    #: compilable subset of the expression language.
+    emit_computed_checks: bool = True
+
+    # -- metadata ----------------------------------------------------------
+    #: ``description`` / ``title`` / comments → ``xs:annotation/xs:documentation``.
+    emit_documentation: bool = True
+    #: ``meaning`` / ``*_uri`` / ``annotations`` → ``xs:annotation/xs:appinfo``.
+    emit_appinfo: bool = False
+    #: Recognise the ``[en] … [de] …`` multilingual-description workaround (no
+    #: native per-language string in LinkML) and split it into one
+    #: ``xs:documentation`` per language, tagged with ``xml:lang``, instead of
+    #: emitting the raw ``[xx]``-tagged text as a single blob.
+    multilingual_documentation: bool = False
+
+    # -- namespaces --------------------------------------------------------
+    #: Explicit override; otherwise derived from ``default_prefix`` / schema id.
+    target_namespace: str | None = None
+    element_form_default: FormDefault = "qualified"
+    attribute_form_default: FormDefault = "unqualified"
+
+    # -- profiles ----------------------------------------------------------
+    #: Opinionated annotation vocabulary to honour, e.g. ``"akn"`` for the
+    #: eCH-0296 / Akoma Ntoso ``xml_element`` / ``xsd_content_model`` set.
+    profile: str | None = None
+
+    # -- diagnostics -------------------------------------------------------
+    on_unsupported: UnsupportedPolicy = "warn"
+
+    def __post_init__(self) -> None:
+        # Validate every Literal-typed field against its allowed values so a bad
+        # CLI/API string fails here, not deep inside an emitter. get_type_hints
+        # resolves the string annotations (PEP 563) and the module-level aliases.
+        for name, hint in get_type_hints(type(self)).items():
+            if get_origin(hint) is Literal:
+                value = getattr(self, name)
+                allowed = get_args(hint)
+                if value not in allowed:
+                    raise ValueError(f"ConversionOptions.{name}={value!r} is not one of {allowed}")

linkml_to_xsd/diagnostics.py

@@ -0,0 +1,20 @@
+"""Unsupported-construct reporting, honouring ``ConversionOptions.on_unsupported``.
+
+A construct the converters cannot (or cannot yet) express must never vanish
+silently — a user would believe it is being validated when it is not. Every
+emitter routes such cases through :func:`report_unsupported`: ``warn`` (default)
+raises a ``UserWarning``, ``error`` aborts the conversion, ``ignore`` stays
+silent (an explicit opt-in to silence).
+"""
+
+from __future__ import annotations
+
+import warnings
+
+
+def report_unsupported(policy: str, message: str) -> None:
+    """Handle a construct with no representation under the current options."""
+    if policy == "error":
+        raise ValueError(message)
+    if policy == "warn":
+        warnings.warn(message, stacklevel=3)

linkml_to_xsd/emit/__init__.py

@@ -0,0 +1,11 @@
+"""Generic LinkML→XSD emit engine (SchemaView-backed).
+
+``XSDGenerator`` is the entry point; the mapping details live in ``generator``,
+``typemap`` and ``naming``.
+"""
+
+from __future__ import annotations
+
+from .generator import XSDGenerator
+
+__all__ = ["XSDGenerator"]