Gen3SchemaDev 2.5.0__tar.gz → 2.6.0__tar.gz

{gen3schemadev-2.5.0 → gen3schemadev-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Gen3SchemaDev
-Version: 2.5.0
+Version: 2.6.0
 Summary: Tool for data modelling in Gen3
 License: Apache 2.0
 License-File: LICENSE
@@ -46,6 +46,8 @@ gen3schemadev fix-refs -y path/to/dictionary             # rewrite in place
 
 The command is idempotent and never touches bare refs, refs already inside `allOf`/`anyOf`/`oneOf`, the `properties: {$ref: ...}` merge construct, or `_definitions.yaml`/`_terms.yaml`/`_settings.yaml`.
 
+Both `fix-refs` and `validate` also warn about `description: null` placeholders anywhere in the dictionary (commonly in `_definitions.yaml`): the Gen3 metaschema requires descriptions to be strings, and such placeholders fail metaschema validation once exposed through bare or `allOf`-wrapped refs. Remove the null keys to resolve the warning.
+
 
 ## Deep dive into Gen3 Data Modelling
 *Special Thanks to Marion Shadbolt for providing the [source material](https://github.com/AustralianBioCommons/umccr-dictionary/tree/main/docs/schemas)*

{gen3schemadev-2.5.0 → gen3schemadev-2.6.0}/README.md

@@ -23,6 +23,8 @@ gen3schemadev fix-refs -y path/to/dictionary             # rewrite in place
 
 The command is idempotent and never touches bare refs, refs already inside `allOf`/`anyOf`/`oneOf`, the `properties: {$ref: ...}` merge construct, or `_definitions.yaml`/`_terms.yaml`/`_settings.yaml`.
 
+Both `fix-refs` and `validate` also warn about `description: null` placeholders anywhere in the dictionary (commonly in `_definitions.yaml`): the Gen3 metaschema requires descriptions to be strings, and such placeholders fail metaschema validation once exposed through bare or `allOf`-wrapped refs. Remove the null keys to resolve the warning.
+
 
 ## Deep dive into Gen3 Data Modelling
 *Special Thanks to Marion Shadbolt for providing the [source material](https://github.com/AustralianBioCommons/umccr-dictionary/tree/main/docs/schemas)*

{gen3schemadev-2.5.0 → gen3schemadev-2.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "Gen3SchemaDev"
-version = "2.5.0"
+version = "2.6.0"
 description = "Tool for data modelling in Gen3"
 authors = [
     {name = "JoshuaHarris391",email = "harjo391@gmail.com"}

{gen3schemadev-2.5.0 → gen3schemadev-2.6.0}/src/gen3schemadev/cli.py

@@ -20,7 +20,31 @@ from gen3schemadev.validators.metaschema_validator import validate_schema_with_m
 from importlib.metadata import version
 from gen3schemadev.ddvis import visualise_with_docker
 from gen3schemadev.validators.rule_validator import RuleValidator
-from gen3schemadev.refs import WRAPPED, SKIP_REASONS, fix_yaml_dir
+from gen3schemadev.refs import (
+    WRAPPED,
+    SKIP_REASONS,
+    fix_yaml_dir,
+    find_null_descriptions,
+    scan_dir_null_descriptions,
+)
+
+
+def print_null_description_warning(hits):
+    """
+    Print a warning block listing every null-valued 'description' key found
+    in the dictionary ("file: dotted.path" strings). No-op when hits is empty.
+    """
+    if not hits:
+        return
+    print(
+        "\nWARNING: found 'description: null' placeholders. The Gen3 metaschema "
+        "requires 'description' to be a string, and null placeholders in shared "
+        "definitions fail metaschema validation once exposed through bare or "
+        "allOf-wrapped $refs. Remove the null 'description' keys (removing adds "
+        "no shared description, so nothing leaks onto referencing properties):"
+    )
+    for hit in hits:
+        print(f"  - {hit}")
 
 
 def main():
@@ -242,6 +266,15 @@ def main():
         elif args.yamls:
             schema_dict = bundle_yamls(args.yamls)
 
+        # Pre-resolution diagnostic: report every null 'description' up front,
+        # because the metaschema stage fails on the first resolved node schema,
+        # far away from the definition that carries the null.
+        null_hits = []
+        for schema_name, schema in schema_dict.items():
+            for hit in find_null_descriptions(schema):
+                null_hits.append(f"{schema_name}: {hit}")
+        print_null_description_warning(null_hits)
+
         for schema_name, schema in schema_dict.items():
 
             if '.' in schema_name:
@@ -364,5 +397,9 @@ def main():
         print(f"\nSummary: {total_wrapped} properties {verb} in {files_changed} files; "
               f"{files_unchanged} files unchanged.")
 
+        # Wrapping is what exposes null 'description' placeholders in shared
+        # definitions to metaschema validation, so surface them here too.
+        print_null_description_warning(scan_dir_null_descriptions(args.yamldir))
+
 if __name__ == "__main__":
     main()

{gen3schemadev-2.5.0 → gen3schemadev-2.6.0}/src/gen3schemadev/refs.py

@@ -141,6 +141,64 @@ def fix_schema(schema: dict) -> "tuple":
     return new_schema, changes
 
 
+def find_null_descriptions(node, path: str = "") -> list:
+    """
+    Recursively find every ``description`` key whose value is null.
+
+    The Gen3 metaschema requires ``description`` to be a string, so a
+    ``description: null`` placeholder (common in generated shared
+    definitions) is invalid. With a direct ``$ref`` the resolver happens to
+    mask it — the referencing property's own description merges over the
+    definition's null — but a bare or allOf-wrapped ref exposes the null in
+    the resolved node schema, where metaschema validation fails far away
+    from the definition that caused it.
+
+    Returns a list of dotted paths to each offender, with list items shown
+    as ``[i]`` (e.g. ``"enum_yes_no.description"``,
+    ``"properties.status.anyOf[0].description"``). Non-dict/list input
+    yields an empty list.
+    """
+    hits = []
+    if isinstance(node, dict):
+        for key, value in node.items():
+            key_path = f"{path}.{key}" if path else str(key)
+            if key == "description" and value is None:
+                hits.append(key_path)
+            else:
+                hits.extend(find_null_descriptions(value, key_path))
+    elif isinstance(node, list):
+        for i, item in enumerate(node):
+            hits.extend(find_null_descriptions(item, f"{path}[{i}]"))
+    return hits
+
+
+def scan_dir_null_descriptions(yaml_dir: str) -> list:
+    """
+    Scan every YAML file under ``yaml_dir`` (recursively) for null-valued
+    ``description`` keys.
+
+    Unlike ``fix_yaml_dir``, underscore files (``_definitions.yaml``,
+    ``_terms.yaml``, ...) are INCLUDED — shared definitions are where the
+    null placeholders usually live, and where they do the most damage
+    because every referencing property inherits them on resolution.
+
+    Returns ``"relpath: dotted.path"`` strings, one per offender.
+    """
+    from gen3schemadev.utils import load_yaml
+
+    hits = []
+    for root, _dirs, files in os.walk(yaml_dir):
+        for fname in sorted(files):
+            if not (fnmatch.fnmatch(fname, "*.yaml") or fnmatch.fnmatch(fname, "*.yml")):
+                continue
+            path = os.path.join(root, fname)
+            rel_path = os.path.relpath(path, yaml_dir)
+            schema = load_yaml(path)
+            for hit in find_null_descriptions(schema):
+                hits.append(f"{rel_path}: {hit}")
+    return hits
+
+
 def fix_yaml_dir(yaml_dir: str, dry_run: bool = False) -> list:
     """
     Rewrite every YAML node schema under ``yaml_dir`` (recursively) so that