linkml 1.9.5rc1__tar.gz → 1.9.5rc2__tar.gz

{linkml-1.9.5rc1 → linkml-1.9.5rc2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: linkml
-Version: 1.9.5rc1
+Version: 1.9.5rc2
 Summary: Linked Open Data Modeling Language
 Author: Deepak Unni
 Author-email: Chris Mungall <cjmungall@lbl.gov>, Sierra Moxon <smoxon@lbl.gov>, Harold Solbrig <solbrig@jhu.edu>, Sujay Patil <spatil@lbl.gov>, Harshad Hegde <hhegde@lbl.gov>, Mark Andrew Miller <MAM@lbl.gov>, Gaurav Vaidya <gaurav@renci.org>, Kevin Schaper <kevin@tislab.org>

{linkml-1.9.5rc1 → linkml-1.9.5rc2}/docs/code/utils.rst

@@ -1,14 +1,6 @@
 Utils
 =====
 
-linkml.utils.converter module
------------------------------
-
-.. automodule:: linkml.utils.converter
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
 linkml.utils.datautils module
 -----------------------------
 

{linkml-1.9.5rc1 → linkml-1.9.5rc2}/docs/data/conversion.rst

@@ -121,8 +121,8 @@ python classes
 Command Line
 ------------
 
-.. currentmodule:: linkml.utils.converter
+.. currentmodule:: linkml.converter.cli
 
-.. click:: linkml.utils.converter:cli
+.. click:: linkml.converter.cli:cli
     :prog: linkml-convert
     :nested: full

{linkml-1.9.5rc1 → linkml-1.9.5rc2}/docs/generators/owl.rst

@@ -70,13 +70,36 @@ Mapping
 Enums and PermissibleValues
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Enums and PermissibleValues are treated as *classes* by default. An enum has a *definition* added using
-an OWL ``UnionOf`` construct.
+Enums and PermissibleValues provide flexible OWL representation options. By default, permissible values
+are treated as *classes* and an enum has a *definition* added using an OWL ``UnionOf`` construct.
 
-* Use ``--default-permissible-value-type`` to change the default type
-* Use ``--enum-iri-separator`` to change the separator character in the enum IRI which is ``#`` by default
+CLI Options for Controlling Enum/PV Generation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You can make an enum represent individuals by adding an ``implements`` slot assignment:
+* ``--default-permissible-value-type`` - Sets the default OWL type for permissible values
+
+  - ``owl:Class`` (default) - PVs become OWL classes, enum uses ``owl:unionOf``
+  - ``owl:NamedIndividual`` - PVs become named individuals, enum uses ``owl:oneOf``
+  - ``rdfs:Literal`` - PVs become RDF literals, enum uses ``owl:oneOf``
+
+* ``--enum-iri-separator`` - Changes the separator character in enum IRIs (default: ``#``)
+
+Example CLI usage:
+
+.. code-block:: bash
+
+    # Generate enum PVs as named individuals
+    gen-owl --default-permissible-value-type owl:NamedIndividual schema.yaml
+
+    # Generate enum PVs as literals
+    gen-owl --default-permissible-value-type rdfs:Literal schema.yaml
+
+Schema Annotations for Fine-Grained Control
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can control enum and permissible value representation directly in your schema using ``implements`` annotations.
+
+**Enum-level control** - Apply to all permissible values in an enum:
 
 .. code-block:: yaml
 
@@ -87,7 +110,100 @@ You can make an enum represent individuals by adding an ``implements`` slot assi
         description: The type of home planet
         permissible_values:
           Earth:
+            description: Third planet from the sun
           Venus:
+            description: Second planet from the sun
+
+**Per-permissible-value control** - Override specific permissible values:
+
+.. code-block:: yaml
+
+    enums:
+      MixedRepresentationType:
+        description: Enum with mixed PV representations
+        permissible_values:
+          concept_term:
+            description: A concept represented as a class
+            implements:
+              - owl:Class
+          instance_value:
+            description: A specific instance
+            implements:
+              - owl:NamedIndividual
+          literal_value:
+            description: A literal value
+            implements:
+              - rdfs:Literal
+
+**Using URIs vs. text for permissible values:**
+
+.. code-block:: yaml
+
+    enums:
+      StatusEnum:
+        permissible_values:
+          active:
+            meaning: ex:ActiveStatus    # Will use URI for OWL representation
+            description: Currently active
+          inactive:
+            description: Not active     # Will use text-based representation
+
+OWL Output Patterns
+~~~~~~~~~~~~~~~~~~~
+
+The choice of permissible value type affects the generated OWL structure:
+
+**owl:Class (default):**
+
+.. code-block:: turtle
+
+    :StatusEnum a owl:Class ;
+        owl:unionOf ( :active :inactive ) .
+    :active a owl:Class .
+    :inactive a owl:Class .
+
+**owl:NamedIndividual:**
+
+.. code-block:: turtle
+
+    :StatusEnum a owl:Class ;
+        owl:oneOf ( :active :inactive ) .
+    :active a owl:NamedIndividual .
+    :inactive a owl:NamedIndividual .
+
+**rdfs:Literal:**
+
+.. code-block:: turtle
+
+    :StatusEnum a owl:Class ;
+        owl:oneOf ( "active" "inactive" ) .
+
+Mixed Types in One Enum
+~~~~~~~~~~~~~~~~~~~~~~~
+
+When permissible values in the same enum have different ``implements`` annotations,
+the behavior depends on the URI/meaning configuration:
+
+* **All PVs have URIs**: Mixed types are supported
+* **Some PVs lack URIs**: The enum may skip certain representation patterns that would be inconsistent
+* **No PVs have URIs**: All PVs use the same default type
+
+Advanced Usage
+~~~~~~~~~~~~~~
+
+**Using with different URI patterns:**
+
+.. code-block:: yaml
+
+    enums:
+      ConceptEnum:
+        permissible_values:
+          term_a:
+            meaning: MONDO:0001234
+            implements: [owl:Class]
+          term_b:
+            meaning: http://example.org/TermB
+            implements: [owl:NamedIndividual]
 
 
 Tips

{linkml-1.9.5rc1 → linkml-1.9.5rc2}/docs/generators/rust.rst

@@ -29,6 +29,65 @@ It additionally generates a trait for every struct to provide polymorphic access
 For all classes having subclasses, an extra enum is generated to represent an object of the class or a subtype.
 All the enums implement the trait, so they can be (optionally) directly used without match statement.
 
+How to Generate a Rust Crate with Python Bindings
+-------------------------------------------------
+
+It is possible to generate a Rust Crate from a linkml schema complete with python bindings.
+
+The steps below walk through producing a PyO3-enabled crate from a LinkML schema and installing it in a Python
+environment. The commands were exercised against ``examples/PersonSchema/personinfo.yaml`` to verify they work end-to-end.
+
+To build a rust crate as a python lib, you need ``maturin``. Maturin can easily be installed using pip.
+A convenient way to build pip packages for multiple python versions and libc alternatives is the ``manylinux`` docker image.
+
+#. **Generate the crate** using the main ``linkml`` CLI. The ``--mode crate`` option is the default; ``--pyo3`` and
+   ``--serde`` ensure the generated ``Cargo.toml`` enables those features by default. Add ``--handwritten-lib`` when you
+   want a regeneration-friendly layout: generated sources land under ``src/generated`` while ``src/lib.rs`` becomes a shim
+   that is created only on the first run and then left untouched.
+
+   .. code-block:: bash
+
+      linkml generate rust \
+        --output personinfo_rust \
+        --pyo3 --serde --handwritten-lib \
+        --force \
+        examples/PersonSchema/personinfo.yaml
+
+   The output directory contains ``Cargo.toml`` (with ``[lib]`` configured for both ``cdylib`` and ``rlib`` when PyO3 is
+   requested), ``pyproject.toml`` with a ``maturin`` build-system section, and a ``src/generated`` tree that houses the
+   regenerated code. A small ``src/lib.rs`` file is emitted on the first run only and re-exported functions from
+   ``generated`` so you can regenerate safely.
+
+#. **Adjust what is exposed to Python** in ``src/lib.rs``. The file declares the PyO3 module and calls
+   ``generated::register_pymodule``; edit it to add your own functions/classes. Because the shim is only created on the
+   first run, later regenerations leave your changes intact.
+
+#. **Generate type stubs** so Python users get better typing support. With the ``stubgen`` feature enabled, run
+   ``cargo run --bin stub_gen --features stubgen`` from the crate directory; add ``-- --check`` when you want to verify
+   existing stubs instead of overwriting them.
+
+#. **Build and install the wheel** with ``maturin``. Running ``maturin develop`` compiles the extension and puts it in the
+   active virtual environment.
+
+   .. code-block:: bash
+
+      cd personinfo_rust
+      maturin develop
+
+   ``maturin build`` is an alternative when you want distributable wheels in ``target/wheels`` instead.
+
+#. **Import the module from Python** and try the generated YAML loader.
+
+   .. code-block:: python
+
+      import personinfo
+      # Update the path below to point at your data file.
+      container = personinfo.load_yaml_container("examples/PersonSchema/data/example_personinfo_data.yaml")
+      print(container.persons[0].name)
+
+When repeating the process, pass ``--force`` (as above) or delete the output directory to avoid collisions with previous
+runs.
+
 
 Feature Compliance
 ------------------
@@ -46,12 +105,11 @@ Supported
 - Temporal scalars: ``date`` and ``datetime`` map to ``chrono``'s ``NaiveDate`` and ``NaiveDateTime`` respectively.
 - Traits for polymorphic access to class hierarchies, along with enums for class-or-subtype containers.
 - PyO3 bindings for the generated structs (behind a Cargo feature flag).
-- Basic ``serde`` deserialization (behind a Cargo feature flag).
+- Basic ``serde`` deserialization and serialization, including normalisation (behind a Cargo feature flag).
 
 Partially Supported
 ~~~~~~~~~~~~~~~~~~~
 - Many scalar types (e.g. ``time``, URI-related types) currently fall back to ``String`` representations.
-- ``serde`` deserialization works; serialization still lacks the normalisation, and will not always produce correct yaml.
 - Testing covers unit-level behaviour with a dedicated Rust CI workflow; dynamic compilation and compliance suites are
   still pending.
 

linkml-1.9.5rc2/docs/generators/yarrrml.rst

@@ -0,0 +1,144 @@
+.. _generators/yarrrml:
+
+YARRRML
+=======
+
+`YARRRML <https://rml.io/yarrrml/>`_ is a YAML-friendly syntax for RML mappings.
+
+.. note::
+   Minimal generator. JSON-first. Good starting point for hand-tuning.
+
+Example Output
+--------------
+
+Given a simple schema:
+
+.. code-block:: yaml
+
+   classes:
+     Person:
+       attributes:
+         id: {identifier: true}
+         name: {}
+
+The generator produces YARRRML like:
+
+.. code-block:: yaml
+
+   mappings:
+     Person:
+       sources:
+         - - data.json~jsonpath
+           - $.items[*]
+       s: ex:$(id)
+       po:
+         - p: rdf:type
+           o: ex:Person
+         - p: ex:name
+           o: $(name)
+
+CSV / TSV sources
+-----------------
+
+Besides JSON, CSV/TSV is supported. The key differences:
+
+- No iterator is required for CSV/TSV (each row is a candidate).
+- ``sources`` must be expressed as a **list of lists** for compatibility with common engines (e.g. Morph-KGC):
+
+  .. code-block:: yaml
+
+     mappings:
+       Person:
+         sources:
+           - ['people.csv~csv']   # note the inner list
+         s: ex:$(id)
+         po:
+           - p: rdf:type
+             o: ex:Person
+           - p: ex:name
+             o: $(name)
+
+- Values come from columns via ``$(column_name)``. For object slots (non-inlined references), IRIs are emitted:
+
+  .. code-block:: yaml
+
+     - p: ex:employer
+       o:
+         value: $(employer)
+         type: iri
+
+- TSV works via the same formulation (``~csv``). Most engines auto-detect the tab separator for ``.tsv`` files. If an engine requires explicit delimiter/CSVW options, that is currently out of scope and can be handled manually in post-editing.
+
+Source inference
+----------------
+
+If you pass a file without a formulation suffix, the generator infers it:
+
+- ``*.json`` → ``~jsonpath``
+- ``*.csv`` / ``*.tsv`` → ``~csv``
+
+Examples:
+
+.. code:: bash
+
+   # JSON (iterator required)
+   linkml generate yarrrml schema.yaml > mappings.yml
+   linkml generate yarrrml schema.yaml --source data.json~jsonpath
+   linkml generate yarrrml schema.yaml --source data.json~jsonpath --iterator-template "$.{Class}[*]"
+
+   # CSV / TSV (no iterator)
+   linkml generate yarrrml schema.yaml --source people.csv
+   # or explicitly:
+   linkml generate yarrrml schema.yaml --source people.csv~csv
+   linkml generate yarrrml schema.yaml --source people.tsv~csv
+
+Overview
+--------
+
+- one mapping per LinkML class
+- prefixes come from the schema
+- subject from identifier slot (else key; else safe fallback)
+- ``po`` for class-induced slots (slot aliases respected)
+- emits ``rdf:type`` as a CURIE (e.g., ``ex:Person``)
+- JSON by default: ``sources: [[data.json~jsonpath, $.items[*]]]``
+- CSV/TSV: ``sources: [[path~csv]]`` (no iterator), values via ``$(column)``
+
+Command Line
+------------
+
+.. code:: bash
+
+   linkml generate yarrrml path/to/schema.yaml > mappings.yml
+   # CSV instead of JSON:
+   linkml generate yarrrml path/to/schema.yaml --source data.csv~csv
+   # class-based arrays (JSON):
+   linkml generate yarrrml path/to/schema.yaml --iterator-template "$.{Class}[*]"
+
+Docs
+----
+
+CLI
+^^^
+
+.. click:: linkml.generators.yarrrmlgen:cli
+    :prog: gen-yarrrml
+    :nested: short
+
+Code
+^^^^
+
+.. currentmodule:: linkml.generators.yarrrmlgen
+
+.. autoclass:: YarrrmlGenerator
+    :members: serialize
+
+Limitations
+-----------
+
+- JSON-first by default
+- One source per mapping
+- Classes without an identifier are skipped
+- Object slots: ``inlined: false`` → IRI; ``inlined: true`` → not materialized
+- Iterators not derived from JSON Schema
+- No per-slot JSONPath/CSV expressions or functions
+- CSV/TSV supported via ``--source``; delimiter/custom CSVW options are not yet exposed

{linkml-1.9.5rc1 → linkml-1.9.5rc2}/docs/howtos/index.rst

@@ -21,3 +21,4 @@ Some of these guides are works in progress
    generate-ai-prompts
    deprecating-elements
    ontologies-as-values
+   skip-logic

linkml-1.9.5rc2/docs/howtos/skip-logic.md

@@ -0,0 +1,175 @@
+# How to implement skip logic in LinkML
+
+This guide will show you how to implement skip logic in your LinkML schemas. Skip logic, also known as conditional branching or survey routing, is a feature that allows you to control which questions are shown to a user based on their previous answers. This is a common requirement in systems like REDCap, CEDAR, and other questionnaire-based data collection systems.
+
+## What is Skip Logic?
+
+In a questionnaire, some questions may only be relevant if a specific answer was given to a previous question. For example, a question about the due date of a pregnancy is only relevant if the respondent has indicated that they are pregnant. Skip logic allows you to hide or show questions based on these conditions, creating a more dynamic and user-friendly experience.
+
+## Modeling Questionnaires in LinkML
+
+You can model a questionnaire in LinkML by defining a class for the questionnaire itself, and then adding slots for each question. For example:
+
+```yaml
+id: https://w3id.org/linkml/examples/personinfo
+name: personinfo
+prefixes:
+  linkml: https://w3id.org/linkml/
+  personinfo: https://w3id.org/linkml/examples/personinfo/
+default_prefix: personinfo
+
+imports:
+  - linkml:types
+
+classes:
+  Person:
+    slots:
+      - is_pregnant
+      - due_date
+      - has_children
+      - number_of_children
+```
+
+In this schema, we have a `Person` class with four slots representing questions in a questionnaire.
+
+## Implementing Skip Logic with LinkML Rules
+
+LinkML's `rules` feature can be used to implement skip logic. Rules are composed of `preconditions` and `postconditions`. The `preconditions` define the conditions under which the rule applies, and the `postconditions` define the constraints that should be enforced when the preconditions are met.
+
+### Pattern 1: Making a field inapplicable
+
+In some cases, a question may not be applicable based on a previous answer. For example, if a person is not pregnant, the `due_date` question is not applicable. We can model this by making the `due_date` slot inapplicable if the `is_pregnant` slot is `false`.
+
+```yaml
+classes:
+  Person:
+    slots:
+      - is_pregnant
+      - due_date
+      - has_children
+      - number_of_children
+    rules:
+      - description: "If a person is not pregnant, the due date is not applicable."
+        preconditions:
+          slot_conditions:
+            is_pregnant:
+              equals_string: "no"
+        postconditions:
+          slot_conditions:
+            due_date:
+              inapplicable: true
+```
+
+With this rule, if a user enters "no" for `is_pregnant`, any value entered for `due_date` will be considered a validation error. The data validation engine would expect the `due_date` to be null or absent.
+
+### Pattern 2: Making a field conditionally required
+
+Another common pattern is to make a field required only if a certain condition is met. For example, the `due_date` should be required if the person is pregnant.
+
+```yaml
+classes:
+  Person:
+    slots:
+      - is_pregnant
+      - due_date
+      - has_children
+      - number_of_children
+    rules:
+      - description: "If a person is pregnant, the due date is required."
+        preconditions:
+          slot_conditions:
+            is_pregnant:
+              equals_string: "yes"
+        postconditions:
+          slot_conditions:
+            due_date:
+              required: true
+```
+
+In this case, if `is_pregnant` is "yes", the `due_date` slot must have a value.
+
+### Combining Rules
+
+You can combine these rules to create more complex logic. For example, we can combine the two rules above, and add similar logic for the `number_of_children` slot.
+
+```yaml
+id: https://w3id.org/linkml/examples/personinfo
+name: personinfo
+prefixes:
+  linkml: https://w3id.org/linkml/
+  personinfo: https://w3id.org/linkml/examples/personinfo/
+default_prefix: personinfo
+
+imports:
+  - linkml:types
+
+enums:
+  YesNoEnum:
+    permissible_values:
+      "yes":
+      "no":
+
+slots:
+  is_pregnant:
+    range: YesNoEnum
+    description: "Are you pregnant?"
+  due_date:
+    range: date
+    description: "What is your due date?"
+  has_children:
+    range: YesNoEnum
+    description: "Do you have children?"
+  number_of_children:
+    range: integer
+    description: "How many children do you have?"
+
+classes:
+  Person:
+    slots:
+      - is_pregnant
+      - due_date
+      - has_children
+      - number_of_children
+    rules:
+      - description: "Due date is required if pregnant, otherwise it's inapplicable."
+        preconditions:
+          slot_conditions:
+            is_pregnant:
+              equals_enum:
+                codeable_concept: "yes"
+        postconditions:
+          slot_conditions:
+            due_date:
+              required: true
+      - preconditions:
+          slot_conditions:
+            is_pregnant:
+              equals_enum:
+                codeable_concept: "no"
+        postconditions:
+          slot_conditions:
+            due_date:
+              inapplicable: true
+
+      - description: "Number of children is required if has_children is yes, otherwise it's inapplicable."
+        preconditions:
+          slot_conditions:
+            has_children:
+              equals_enum:
+                codeable_concept: "yes"
+        postconditions:
+          slot_conditions:
+            number_of_children:
+              required: true
+      - preconditions:
+          slot_conditions:
+            has_children:
+              equals_enum:
+                codeable_concept: "no"
+        postconditions:
+          slot_conditions:
+            number_of_children:
+              inapplicable: true
+```
+
+This complete example demonstrates how to use LinkML rules to implement skip logic in your schemas, ensuring that your data is valid and consistent. By using these patterns, you can create sophisticated and dynamic questionnaires that adapt to user input.

{linkml-1.9.5rc1 → linkml-1.9.5rc2}/linkml/cli/main.py

@@ -7,6 +7,7 @@ Gathers all the other linkml click entrypoints and puts them under ``linkml`` :)
 import click
 
 from linkml._version import __version__
+from linkml.converter.cli import cli as linkml_convert
 from linkml.generators.csvgen import cli as gen_csv
 from linkml.generators.dbmlgen import cli as gen_dbml
 from linkml.generators.docgen import cli as gen_doc
@@ -46,7 +47,6 @@ from linkml.generators.yamlgen import cli as gen_yaml
 from linkml.generators.yarrrmlgen import cli as gen_yarrrml
 from linkml.generators.yumlgen import cli as gen_yuml
 from linkml.linter.cli import main as linkml_lint
-from linkml.utils.converter import cli as linkml_convert
 from linkml.utils.execute_tutorial import cli as run_tutorial
 from linkml.utils.schema_fixer import main as linkml_schema_fixer
 from linkml.utils.sqlutils import main as linkml_sqldb

{linkml-1.9.5rc1 → linkml-1.9.5rc2}/linkml/generators/owlgen.py

@@ -229,7 +229,7 @@ class OwlSchemaGenerator(Generator):
         data = self.graph.serialize(format="turtle" if self.format in ["owl", "ttl"] else self.format)
         return data
 
-    def add_metadata(self, e: Definition, uri: URIRef) -> None:
+    def add_metadata(self, e: Union[Definition, PermissibleValue], uri: URIRef) -> None:
         """
         Add annotation properties.
 
@@ -866,6 +866,10 @@ class OwlSchemaGenerator(Generator):
             if impl.startswith("rdfs:"):
                 return RDFS[impl.split(":")[1]]
         if isinstance(default_value, str):
+            if default_value.startswith("owl:"):
+                return OWL[default_value.split(":")[1]]
+            if default_value.startswith("rdfs:"):
+                return RDFS[default_value.split(":")[1]]
             return URIRef(default_value)
         return default_value
 
@@ -873,6 +877,8 @@ class OwlSchemaGenerator(Generator):
         g = self.graph
         enum_uri = self._enum_uri(e.name)
         g.add((enum_uri, RDF.type, OWL.Class))
+
+        self.add_metadata(e, enum_uri)
         has_parent = False
         if e.is_a:
             self.graph.add((enum_uri, RDFS.subClassOf, self._enum_uri(e.is_a)))
@@ -916,6 +922,7 @@ class OwlSchemaGenerator(Generator):
                 )
             )
             if not isinstance(pv_node, Literal):
+                self.add_metadata(pv, pv_node)
                 g.add((pv_node, RDF.type, pv_owl_type))
                 g.add((pv_node, RDFS.label, Literal(pv.text)))
                 # TODO: make this configurable
@@ -936,6 +943,7 @@ class OwlSchemaGenerator(Generator):
                 if not has_parent and self.add_root_classes:
                     self.graph.add((pv_node, RDFS.subClassOf, URIRef(PermissibleValue.class_class_uri)))
         if all([pv is not None for pv in pv_uris]):
+            # every single PV in the enum is not-null
             all_is_class = all([owl_type == OWL.Class for owl_type in owl_types])
             all_is_individual = all([owl_type == OWL.NamedIndividual for owl_type in owl_types])
             all_is_literal = all([owl_type == RDFS.Literal for owl_type in owl_types])

{linkml-1.9.5rc1 → linkml-1.9.5rc2}/linkml/generators/rustgen/build.py

@@ -1,3 +1,5 @@
+from pydantic import Field
+
 from linkml.generators.common.build import (
     BuildResult,
     SchemaResult,
@@ -84,6 +86,7 @@ class CrateResult(RustBuildResult, SchemaResult):
     file: RustFile
     extra_files: dict[str, RustTemplateModel]
     pyproject: RustPyProject
+    bin_files: dict[str, RustTemplateModel] = Field(default_factory=dict)
 
 
 class FileResult(RustBuildResult, SchemaResult):