Tighten structured metadata schemas

Author: jmchilton

docs/commands/output_schema.rst

@@ -13,11 +13,18 @@ This section is auto-generated from the help text for the planemo command
 **Help**
 
 Export JSON Schemas for Planemo machine-readable outputs.
+
+Available schemas:
+
+cli-command-metadata: output from `planemo cli_metadata --command NAME`.
+cli-metadata: output from `planemo cli_metadata`.
+invocation-download-manifest: output from `planemo invocation_download --output_json PATH`.
+run-outputs: output from `planemo run --output_json PATH`.
+test-report: output from test report JSON writers such as `planemo test --test_output_json PATH`.
 **Options**::
 
 
-      --format [json]                 [default: json]
-      --schema [invocation-download-manifest|run-outputs|test-report]
+      --schema [cli-command-metadata|cli-metadata|invocation-download-manifest|run-outputs|test-report]
                                       Only export one schema.
       --help                          Show this message and exit.
     

planemo/cli_metadata.py

@@ -6,6 +6,11 @@
 from typing import Any
 
 import click
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+)
 
 from planemo import __version__
 from planemo.cli import (
@@ -18,6 +23,57 @@
 SCHEMA_VERSION = "0.1"
 
 
+class PlanemoClickTypeMetadata(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    name: str
+
+
+class PlanemoCliParamMetadata(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    kind: str
+    name: str | None
+    opts: list[str] = Field(default_factory=list)
+    secondary_opts: list[str] = Field(default_factory=list)
+    help: str | None = None
+    required: bool
+    human_readable_name: str
+    multiple: bool
+    nargs: int
+    type: PlanemoClickTypeMetadata
+    default: Any = None
+    is_flag: bool = False
+    flag_value: Any = None
+    envvar: Any = None
+    hidden: bool = False
+    prompt: str | bool | None = None
+    planemo_config: dict[str, Any] = Field(default_factory=dict)
+
+
+class PlanemoCommandMetadata(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    name: str
+    module: str
+    help: str | None = None
+    short_help: str | None = None
+    usage: str
+    internal: bool
+    hidden: bool = False
+    params: list[PlanemoCliParamMetadata] = Field(default_factory=list)
+
+
+class PlanemoCliMetadata(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    schema_version: str = SCHEMA_VERSION
+    program: str = "planemo"
+    planemo_version: str
+    commands: list[PlanemoCommandMetadata] = Field(default_factory=list)
+    aliases: dict[str, str] = Field(default_factory=dict)
+
+
 def iter_command_names(include_internal: bool = False) -> list[str]:
     """Return command names included in public CLI metadata."""
     commands = list_cmds()
@@ -26,38 +82,36 @@ def iter_command_names(include_internal: bool = False) -> list[str]:
     return commands
 
 
-def load_command_metadata(command_name: str) -> dict[str, Any]:
+def load_command_metadata(command_name: str) -> PlanemoCommandMetadata:
     """Load metadata for one Planemo command."""
     return serialize_click_command(command_name, name_to_command(command_name))
 
 
-def load_planemo_metadata(include_internal: bool = False) -> dict[str, Any]:
+def load_planemo_metadata(include_internal: bool = False) -> PlanemoCliMetadata:
     """Load metadata for the Planemo command line interface."""
-    return {
-        "schema_version": SCHEMA_VERSION,
-        "program": "planemo",
-        "planemo_version": __version__,
-        "commands": [load_command_metadata(command_name) for command_name in iter_command_names(include_internal)],
-        "aliases": dict(sorted(COMMAND_ALIASES.items())),
-    }
+    return PlanemoCliMetadata(
+        planemo_version=__version__,
+        commands=[load_command_metadata(command_name) for command_name in iter_command_names(include_internal)],
+        aliases=dict(sorted(COMMAND_ALIASES.items())),
+    )
 
 
-def serialize_click_command(command_name: str, command: click.Command) -> dict[str, Any]:
+def serialize_click_command(command_name: str, command: click.Command) -> PlanemoCommandMetadata:
     """Serialize one Click command into JSON-compatible metadata."""
     context = click.Context(command, info_name=command_name)
-    return {
-        "name": command_name,
-        "module": f"planemo.commands.cmd_{command_name}",
-        "help": command.help,
-        "short_help": command.short_help,
-        "usage": command.get_usage(context).removeprefix("Usage: "),
-        "internal": command_name in INTERNAL_COMMANDS,
-        "hidden": getattr(command, "hidden", False),
-        "params": [serialize_click_param(param) for param in command.params],
-    }
-
-
-def serialize_click_param(param: click.Parameter) -> dict[str, Any]:
+    return PlanemoCommandMetadata(
+        name=command_name,
+        module=f"planemo.commands.cmd_{command_name}",
+        help=command.help,
+        short_help=command.short_help,
+        usage=command.get_usage(context).removeprefix("Usage: "),
+        internal=command_name in INTERNAL_COMMANDS,
+        hidden=getattr(command, "hidden", False),
+        params=[serialize_click_param(param) for param in command.params],
+    )
+
+
+def serialize_click_param(param: click.Parameter) -> PlanemoCliParamMetadata:
     """Serialize one Click parameter into JSON-compatible metadata."""
     planemo_config = getattr(param, "planemo_config", {})
     metadata = {
@@ -81,10 +135,10 @@ def serialize_click_param(param: click.Parameter) -> dict[str, Any]:
     }
     if isinstance(param, click.Option):
         metadata["is_bool_flag"] = param.is_bool_flag
-    return metadata
+    return PlanemoCliParamMetadata.model_validate(metadata)
 
 
-def serialize_click_type(param_type: click.ParamType) -> dict[str, Any]:
+def serialize_click_type(param_type: click.ParamType) -> PlanemoClickTypeMetadata:
     """Serialize Click parameter type details where Click exposes them."""
     metadata: dict[str, Any] = {"name": param_type.name}
     if isinstance(param_type, click.Choice):
@@ -112,7 +166,7 @@ def serialize_click_type(param_type: click.ParamType) -> dict[str, Any]:
         for attr in ("exists", "file_okay", "dir_okay", "writable", "readable", "resolve_path", "allow_dash"):
             if hasattr(param_type, attr):
                 metadata[attr] = getattr(param_type, attr)
-    return _json_value(metadata)
+    return PlanemoClickTypeMetadata.model_validate(_json_value(metadata))
 
 
 def _json_value(value: Any) -> Any:

planemo/commands/cmd_cli_metadata.py

@@ -20,4 +20,4 @@ def cli(output_format, command_name, include_internal):
         metadata = load_command_metadata(command_name)
     else:
         metadata = load_planemo_metadata(include_internal=include_internal)
-    click.echo(json.dumps(metadata, indent=2, sort_keys=True))
+    click.echo(json.dumps(metadata.model_dump(mode="json"), indent=2, sort_keys=True))

planemo/commands/cmd_output_schema.py

@@ -11,8 +11,17 @@
 
 
 @click.command("output_schema")
-@click.option("--format", "output_format", default="json", type=click.Choice(["json"]), show_default=True)
 @click.option("--schema", "schema_name", type=click.Choice(sorted(SCHEMA_MODELS)), help="Only export one schema.")
-def cli(output_format, schema_name):
-    """Export JSON Schemas for Planemo machine-readable outputs."""
+def cli(schema_name):
+    """Export JSON Schemas for Planemo machine-readable outputs.
+
+    Available schemas:
+
+    \b
+    cli-command-metadata: output from `planemo cli_metadata --command NAME`.
+    cli-metadata: output from `planemo cli_metadata`.
+    invocation-download-manifest: output from `planemo invocation_download --output_json PATH`.
+    run-outputs: output from `planemo run --output_json PATH`.
+    test-report: output from test report JSON writers such as `planemo test --test_output_json PATH`.
+    """
     click.echo(json.dumps(load_output_schemas(schema_name), indent=2, sort_keys=True))

planemo/output_schemas.py

@@ -5,6 +5,10 @@
 from typing import Any
 
 from planemo import __version__
+from planemo.cli_metadata import (
+    PlanemoCliMetadata,
+    PlanemoCommandMetadata,
+)
 from planemo.output_models import (
     PlanemoInvocationDownloadManifest,
     PlanemoRunOutputs,
@@ -14,6 +18,8 @@
 SCHEMA_VERSION = "0.1"
 
 SCHEMA_MODELS = {
+    "cli-command-metadata": PlanemoCommandMetadata,
+    "cli-metadata": PlanemoCliMetadata,
     "invocation-download-manifest": PlanemoInvocationDownloadManifest,
     "run-outputs": PlanemoRunOutputs,
     "test-report": PlanemoTestReport,

tests/test_output_schema.py

@@ -21,23 +21,23 @@ def vlog(self, message, exception=False):
 
 class TestOutputSchema(CliTestCase):
     def test_output_schema_exports_test_report_schema(self):
-        result = self._check_exit_code(["output_schema", "--format", "json", "--schema", "test-report"])
+        result = self._check_exit_code(["output_schema", "--schema", "test-report"])
         metadata = json.loads(result.output)
 
         assert metadata["schema_version"] == "0.1"
         assert list(metadata["schemas"]) == ["test-report"]
         assert metadata["schemas"]["test-report"]["$schema"] == "https://json-schema.org/draft/2020-12/schema"
 
     def test_output_schema_exports_run_outputs_schema(self):
-        result = self._check_exit_code(["output_schema", "--format", "json", "--schema", "run-outputs"])
+        result = self._check_exit_code(["output_schema", "--schema", "run-outputs"])
         metadata = json.loads(result.output)
 
         assert list(metadata["schemas"]) == ["run-outputs"]
         assert metadata["schemas"]["run-outputs"]["$schema"] == "https://json-schema.org/draft/2020-12/schema"
 
     def test_output_schema_exports_invocation_download_manifest_schema(self):
         result = self._check_exit_code(
-            ["output_schema", "--format", "json", "--schema", "invocation-download-manifest"]
+            ["output_schema", "--schema", "invocation-download-manifest"]
         )
         metadata = json.loads(result.output)
 
@@ -47,6 +47,13 @@ def test_output_schema_exports_invocation_download_manifest_schema(self):
             == "https://json-schema.org/draft/2020-12/schema"
         )
 
+    def test_output_schema_exports_cli_metadata_schema(self):
+        result = self._check_exit_code(["output_schema", "--schema", "cli-metadata"])
+        metadata = json.loads(result.output)
+
+        assert list(metadata["schemas"]) == ["cli-metadata"]
+        assert metadata["schemas"]["cli-metadata"]["$schema"] == "https://json-schema.org/draft/2020-12/schema"
+
     def test_invocation_download_manifest_relative_paths(self):
         output_directory = os.path.join(os.getcwd(), "outputs")
         output_path = os.path.join(output_directory, "answer.txt")