Clarify input type aliases; move input_parameter_class out of generated file

Schema docs distinguish normalized gxformat2 spellings (data, collection,
string, int, float, boolean) from compatibility aliases (File, data_input,
data_collection, data_collection_input, text, integer). Updates GalaxyType,
WorkflowDataParameter, WorkflowIntegerParameter, WorkflowTextParameter, and
the optional/default field docs. Closes #200.

input_parameter_class and _INPUT_TYPE_TO_CLASS were hand-edited into the
generated gxformat2/schema/gxformat2.py in 1a2d9ed; any rerun of
build_schema.sh wiped them. Moved to gxformat2/schema/_input_parameter.py
(hand-written, regen-safe). Consumers in normalized/_format2.py and
normalized/_conversion.py updated.

Regenerated gxformat2/schema/v19_09.py, gxformat2.py, gxformat2_strict.py
to pick up the doc changes.

Author: jmchilton

gxformat2/normalized/_conversion.py

@@ -44,10 +44,10 @@
     FrameComment,
     FreehandComment,
     GalaxyWorkflow,
-    input_parameter_class,
     MarkdownComment,
     Report,
 )
+from ..schema._input_parameter import input_parameter_class
 from ..schema.gxformat2 import StepPosition as Format2StepPosition
 from ..schema.gxformat2 import (
     TextComment,

gxformat2/normalized/_format2.py

@@ -25,7 +25,6 @@
     FrameComment,
     FreehandComment,
     GalaxyWorkflow,
-    input_parameter_class,
     MarkdownComment,
     Report,
     StepPosition,
@@ -38,6 +37,7 @@
     WorkflowStepOutput,
     WorkflowStepType,
 )
+from gxformat2.schema._input_parameter import input_parameter_class
 from gxformat2.schema.gxformat2_strict import GalaxyWorkflow as StrictGalaxyWorkflow
 from gxformat2.yaml import ordered_load_path
 

gxformat2/schema/_input_parameter.py

@@ -0,0 +1,45 @@
+"""Hand-written helper for resolving Format2 input ``type`` strings to the
+corresponding pydantic model class.
+
+The discriminator map mirrors ``pydantic:discriminator_map`` on
+``Process.inputs`` in ``schema/v19_09/Process.yml``. Keep the two in sync.
+
+Lives outside the generated modules in this package so ``build_schema.sh``
+regeneration does not clobber it.
+"""
+
+from .gxformat2 import (
+    BaseInputParameter,
+    WorkflowBooleanParameter,
+    WorkflowCollectionParameter,
+    WorkflowDataParameter,
+    WorkflowFloatParameter,
+    WorkflowIntegerParameter,
+    WorkflowTextParameter,
+)
+
+_INPUT_TYPE_TO_CLASS: dict[str, type[BaseInputParameter]] = {
+    "data": WorkflowDataParameter,
+    "File": WorkflowDataParameter,
+    "data_input": WorkflowDataParameter,
+    "collection": WorkflowCollectionParameter,
+    "data_collection": WorkflowCollectionParameter,
+    "data_collection_input": WorkflowCollectionParameter,
+    "integer": WorkflowIntegerParameter,
+    "int": WorkflowIntegerParameter,
+    "text": WorkflowTextParameter,
+    "string": WorkflowTextParameter,
+    "float": WorkflowFloatParameter,
+    "boolean": WorkflowBooleanParameter,
+    "color": WorkflowTextParameter,
+}
+
+
+def input_parameter_class(type_value: str | None) -> type[BaseInputParameter]:
+    """Return the specific input parameter class for a Format2 type string.
+
+    Falls back to WorkflowDataParameter for unknown or None types.
+    """
+    if type_value is None:
+        return WorkflowDataParameter
+    return _INPUT_TYPE_TO_CLASS.get(type_value, WorkflowDataParameter)

gxformat2/schema/gxformat2.py

@@ -38,12 +38,15 @@ class PrimitiveType(str, Enum):
 
 
 class GalaxyType(str, Enum):
-    """Extends primitive types with the native Galaxy concepts such datasets and collections.
-integer: an alias for int type - matches syntax used by Galaxy tools
-text: an alias for string type - matches syntax used by Galaxy tools
-File: an alias for data - there are subtle differences between a plain file, the CWL concept of 'File', and the Galaxy concept of a dataset - this may have subtly difference semantics in the future
-data: a Galaxy dataset
-collection: a Galaxy dataset collection"""
+    """Extends primitive types with the native Galaxy concepts such as datasets and collections.
+Normalized gxformat2 workflow input declaration spellings are ``data``, ``collection``, ``string``, ``int``, ``float``, and ``boolean``. Other spellings are accepted as compatibility aliases on import but normalized gxformat2 output emits the normalized spellings.
+data: one Galaxy dataset input. Native Galaxy ``data_input`` converts to this spelling.
+File: accepted alias for ``data``, but normalized gxformat2 output emits ``data``. Note: workflow **test job** YAML uses ``type: File`` to mean 'stage this file as test input data', which is a separate concept from workflow input declaration.
+collection: one Galaxy dataset collection input. Native Galaxy ``data_collection_input`` converts to this spelling.
+string: normalized gxformat2 spelling for native Galaxy text workflow parameters.
+text: accepted alias for ``string`` because native Galaxy parameter state and Galaxy tool XML terminology use ``text``.
+int: normalized gxformat2 spelling for native Galaxy integer workflow parameters.
+integer: accepted alias for ``int`` because native Galaxy parameter state and Galaxy tool XML terminology use ``integer``."""
 
     null = "null"
     boolean = "boolean"
@@ -202,7 +205,7 @@ class BaseInputParameter(InputParameter, HasStepPosition):
     id: None | str = Field(default=None, description="The unique identifier for this object.")
     label: None | str = Field(default=None, description="A short, human-readable label of this object.")
     doc: None | str | list[str] = Field(default=None, description="A documentation string for this object, or an array of strings which should be concatenated.")
-    optional: bool | None = Field(default=None, description="If set to true, `WorkflowInputParameter` is not required to submit the workflow.")
+    optional: bool | None = Field(default=None, description="Controls whether Galaxy allows invocation of the workflow without a user-supplied value for this input. If ``true``, the input may be omitted at invocation time. ``optional`` and ``default`` are in...")
 
 class BaseDataParameter(BaseInputParameter):
     model_config = ConfigDict(populate_by_name=True, extra="forbid")
@@ -215,7 +218,10 @@ class BaseDataParameter(BaseInputParameter):
     format: None | list[str] = Field(default=None, description="Specify datatype extensions for valid input datasets.")
 
 class WorkflowDataParameter(BaseDataParameter):
-    """A data input parameter for a Galaxy workflow - represents a dataset."""
+    """A data input parameter for a Galaxy workflow. Represents one Galaxy dataset.
+Normalized gxformat2 output uses ``type: data``. ``type: File`` is accepted as
+an alias, but should not be confused with workflow test job syntax where
+``type: File`` means stage a file as test input data."""
 
     model_config = ConfigDict(populate_by_name=True, extra="forbid")
 
@@ -224,7 +230,7 @@ class WorkflowDataParameter(BaseDataParameter):
     doc: None | str | list[str] = Field(default=None, description="A documentation string for this object, or an array of strings which should be concatenated.")
     default: None | Any = Field(default=None, description="The default value to use for this parameter if the parameter is missing from the input object, or if the value of the parameter in the input object is `null`.  Default values are applied before eva...")
     position: None | StepPosition = Field(default=None)
-    optional: bool | None = Field(default=None, description="If set to true, `WorkflowInputParameter` is not required to submit the workflow.")
+    optional: bool | None = Field(default=None, description="Controls whether Galaxy allows invocation of the workflow without a user-supplied value for this input. If ``true``, the input may be omitted at invocation time. ``optional`` and ``default`` are in...")
     type_: Literal["data", "File"] | None = Field(default=None, alias="type", description="Specify valid types of data that may be assigned to this parameter.")
 
 class WorkflowCollectionParameter(BaseDataParameter):
@@ -237,7 +243,7 @@ class WorkflowCollectionParameter(BaseDataParameter):
     doc: None | str | list[str] = Field(default=None, description="A documentation string for this object, or an array of strings which should be concatenated.")
     default: None | Any = Field(default=None, description="The default value to use for this parameter if the parameter is missing from the input object, or if the value of the parameter in the input object is `null`.  Default values are applied before eva...")
     position: None | StepPosition = Field(default=None)
-    optional: bool | None = Field(default=None, description="If set to true, `WorkflowInputParameter` is not required to submit the workflow.")
+    optional: bool | None = Field(default=None, description="Controls whether Galaxy allows invocation of the workflow without a user-supplied value for this input. If ``true``, the input may be omitted at invocation time. ``optional`` and ``default`` are in...")
     type_: Literal["collection"] = Field(default="collection", alias="type", description="Must be ``collection``.")
     collection_type: None | str = Field(default=None, description="Collection type (defaults to `list` if `type` is `collection`). Nested collection types are separated with colons, e.g. `list:list:paired`.")
 
@@ -248,7 +254,9 @@ class MinMax(BaseModel):
     max: int | float | None = Field(default=None, description="Maximum allowed value (inclusive).")
 
 class WorkflowIntegerParameter(BaseInputParameter, MinMax):
-    """An integer input parameter for a Galaxy workflow."""
+    """A scalar integer workflow parameter. Normalized gxformat2 output uses
+``type: int``. ``type: integer`` is accepted for compatibility with native
+Galaxy parameter state and Galaxy tool XML terminology."""
 
     model_config = ConfigDict(populate_by_name=True, extra="forbid")
 
@@ -272,7 +280,9 @@ class WorkflowFloatParameter(BaseInputParameter, MinMax):
     type_: Literal["float"] = Field(default="float", alias="type", description="Must be ``float``.")
 
 class WorkflowTextParameter(BaseInputParameter):
-    """A text input parameter for a Galaxy workflow."""
+    """A scalar text workflow parameter. Normalized gxformat2 output uses
+``type: string``. ``type: text`` is accepted for compatibility with native
+Galaxy parameter state and Galaxy tool XML terminology."""
 
     model_config = ConfigDict(populate_by_name=True, extra="forbid")
 
@@ -307,7 +317,7 @@ class WorkflowInputParameter(BaseDataParameter, MinMax):
     doc: None | str | list[str] = Field(default=None, description="A documentation string for this object, or an array of strings which should be concatenated.")
     default: None | Any = Field(default=None, description="The default value to use for this parameter if the parameter is missing from the input object, or if the value of the parameter in the input object is `null`.  Default values are applied before eva...")
     position: None | StepPosition = Field(default=None)
-    optional: bool | None = Field(default=None, description="If set to true, `WorkflowInputParameter` is not required to submit the workflow.")
+    optional: bool | None = Field(default=None, description="Controls whether Galaxy allows invocation of the workflow without a user-supplied value for this input. If ``true``, the input may be omitted at invocation time. ``optional`` and ``default`` are in...")
     type_: GalaxyType | None | list[GalaxyType] = Field(default=None, alias="type", description="Specify valid types of data that may be assigned to this parameter.")
     collection_type: None | str = Field(default=None, description="Collection type (defaults to `list` if `type` is `collection`). Nested collection types are separated with colons, e.g. `list:list:paired`.")
 

gxformat2/schema/gxformat2_strict.py

@@ -3569,7 +3569,10 @@ def save(
 
 class WorkflowDataParameter(BaseDataParameter):
     """
-    A data input parameter for a Galaxy workflow - represents a dataset.
+    A data input parameter for a Galaxy workflow. Represents one Galaxy dataset.
+    Normalized gxformat2 output uses ``type: data``. ``type: File`` is accepted as
+    an alias, but should not be confused with workflow test job syntax where
+    ``type: File`` means stage a file as test input data.
 
     """
 
@@ -4957,7 +4960,9 @@ def save(
 
 class WorkflowIntegerParameter(BaseInputParameter, MinMax):
     """
-    An integer input parameter for a Galaxy workflow.
+    A scalar integer workflow parameter. Normalized gxformat2 output uses
+    ``type: int``. ``type: integer`` is accepted for compatibility with native
+    Galaxy parameter state and Galaxy tool XML terminology.
 
     """
 
@@ -6191,7 +6196,9 @@ def save(
 
 class WorkflowTextParameter(BaseInputParameter):
     """
-    A text input parameter for a Galaxy workflow.
+    A scalar text workflow parameter. Normalized gxformat2 output uses
+    ``type: string``. ``type: text`` is accepted for compatibility with native
+    Galaxy parameter state and Galaxy tool XML terminology.
 
     """
 
@@ -15376,12 +15383,15 @@ def save(
     "GalaxyType",
 )
 """
-Extends primitive types with the native Galaxy concepts such datasets and collections.
-integer: an alias for int type - matches syntax used by Galaxy tools
-text: an alias for string type - matches syntax used by Galaxy tools
-File: an alias for data - there are subtle differences between a plain file, the CWL concept of 'File', and the Galaxy concept of a dataset - this may have subtly difference semantics in the future
-data: a Galaxy dataset
-collection: a Galaxy dataset collection
+Extends primitive types with the native Galaxy concepts such as datasets and collections.
+Normalized gxformat2 workflow input declaration spellings are ``data``, ``collection``, ``string``, ``int``, ``float``, and ``boolean``. Other spellings are accepted as compatibility aliases on import but normalized gxformat2 output emits the normalized spellings.
+data: one Galaxy dataset input. Native Galaxy ``data_input`` converts to this spelling.
+File: accepted alias for ``data``, but normalized gxformat2 output emits ``data``. Note: workflow **test job** YAML uses ``type: File`` to mean 'stage this file as test input data', which is a separate concept from workflow input declaration.
+collection: one Galaxy dataset collection input. Native Galaxy ``data_collection_input`` converts to this spelling.
+string: normalized gxformat2 spelling for native Galaxy text workflow parameters.
+text: accepted alias for ``string`` because native Galaxy parameter state and Galaxy tool XML terminology use ``text``.
+int: normalized gxformat2 spelling for native Galaxy integer workflow parameters.
+integer: accepted alias for ``int`` because native Galaxy parameter state and Galaxy tool XML terminology use ``integer``.
 """
 WorkflowStepTypeLoader = _EnumLoader(
     (

gxformat2/schema/v19_09.py

@@ -37,12 +37,15 @@ $graph:
     - data
     - collection
   doc:
-    - "Extends primitive types with the native Galaxy concepts such datasets and collections."
-    - "integer: an alias for int type - matches syntax used by Galaxy tools"
-    - "text: an alias for string type - matches syntax used by Galaxy tools"
-    - "File: an alias for data - there are subtle differences between a plain file, the CWL concept of 'File', and the Galaxy concept of a dataset - this may have subtly difference semantics in the future"
-    - "data: a Galaxy dataset"
-    - "collection: a Galaxy dataset collection"
+    - "Extends primitive types with the native Galaxy concepts such as datasets and collections."
+    - "Normalized gxformat2 workflow input declaration spellings are ``data``, ``collection``, ``string``, ``int``, ``float``, and ``boolean``. Other spellings are accepted as compatibility aliases on import but normalized gxformat2 output emits the normalized spellings."
+    - "data: one Galaxy dataset input. Native Galaxy ``data_input`` converts to this spelling."
+    - "File: accepted alias for ``data``, but normalized gxformat2 output emits ``data``. Note: workflow **test job** YAML uses ``type: File`` to mean 'stage this file as test input data', which is a separate concept from workflow input declaration."
+    - "collection: one Galaxy dataset collection input. Native Galaxy ``data_collection_input`` converts to this spelling."
+    - "string: normalized gxformat2 spelling for native Galaxy text workflow parameters."
+    - "text: accepted alias for ``string`` because native Galaxy parameter state and Galaxy tool XML terminology use ``text``."
+    - "int: normalized gxformat2 spelling for native Galaxy integer workflow parameters."
+    - "integer: accepted alias for ``int`` because native Galaxy parameter state and Galaxy tool XML terminology use ``integer``."
 
 
 - name: WorkflowStepType
@@ -73,7 +76,13 @@ $graph:
       - "null"
       default: false
       doc: |
-        If set to true, `WorkflowInputParameter` is not required to submit the workflow.
+        Controls whether Galaxy allows invocation of the workflow without a
+        user-supplied value for this input. If ``true``, the input may be omitted
+        at invocation time. ``optional`` and ``default`` are independent: a
+        required input (``optional: false``) may still declare a ``default``,
+        and an optional input may have no ``default``. ``default`` supplies a
+        value when the invocation input is missing or ``null``; ``optional``
+        controls whether the missing case is even permitted.
 
 - name: BaseDataParameter
   type: record
@@ -93,7 +102,10 @@ $graph:
     - BaseDataParameter
   docParent: "#GalaxyWorkflow"
   doc: |
-    A data input parameter for a Galaxy workflow - represents a dataset.
+    A data input parameter for a Galaxy workflow. Represents one Galaxy dataset.
+    Normalized gxformat2 output uses ``type: data``. ``type: File`` is accepted as
+    an alias, but should not be confused with workflow test job syntax where
+    ``type: File`` means stage a file as test input data.
   fields:
     - name: type
       type:
@@ -169,7 +181,9 @@ $graph:
     - MinMax
   docParent: "#GalaxyWorkflow"
   doc: |
-    An integer input parameter for a Galaxy workflow.
+    A scalar integer workflow parameter. Normalized gxformat2 output uses
+    ``type: int``. ``type: integer`` is accepted for compatibility with native
+    Galaxy parameter state and Galaxy tool XML terminology.
   fields:
     - name: type
       type: string
@@ -208,7 +222,9 @@ $graph:
     - BaseInputParameter
   docParent: "#GalaxyWorkflow"
   doc: |
-    A text input parameter for a Galaxy workflow.
+    A scalar text workflow parameter. Normalized gxformat2 output uses
+    ``type: string``. ``type: text`` is accepted for compatibility with native
+    Galaxy parameter state and Galaxy tool XML terminology.
   fields:
     - name: type
       type: string