fix(models)

- Add additional manfiest model title, example, or description
- Begin refactoring models using Annotated field pattern

Author: tcjennings

script/render_jsonschema.py

@@ -6,7 +6,7 @@
 #     "json-schema-for-humans>=1.5.1",
 #     "lsst-cm-service",
 #     "lsst-utils",
-#     "pydantic==2.11.*",
+#     "pydantic==2.12.*",
 # ]
 #
 # [tool.uv.sources]

src/lsst/cmservice/models/manifests/bps.py

@@ -4,7 +4,7 @@
 
 from __future__ import annotations
 
-from typing import Any
+from typing import Annotated, Any
 
 from pydantic import Field
 
@@ -19,46 +19,72 @@ class BpsSpec(ManifestSpec):
     """
 
     model_config = SPEC_CONFIG
-    pipeline_yaml: str = Field(
-        description="The absolute path to a Pipeline YAML specification file with optional anchor. "
-        "The path must begin with a `/` or a `${...}` environment variable.",
-        pattern="^(/|\\$\\{.*\\})(.*)(\\.yaml)(#.*)?$",
-    )
+    pipeline_yaml: (
+        Annotated[
+            str,
+            Field(
+                title="Pipeline YAML File",
+                description="The absolute path to a Pipeline YAML specification file with optional anchor. "
+                "The path must begin with a `/` or a `${...}` environment variable.",
+                pattern="^(/|\\$\\{.*\\})(.*)(\\.yaml)(#.*)?$",
+                examples=[
+                    "${DRP_PIPE_DIR}/path/to/pipeline.yaml#anchor",
+                    "/absolute/path/to/file.yaml",
+                    "${CUSTOM_VAR}/file.yaml#anchor1,anchor2",
+                ],
+            ),
+        ]
+        | Annotated[
+            None,
+            Field(
+                title="No Pipeline YAML",
+                description="A BPS Manifest does not need to specify a pipeline YAML file, but one is "
+                "mandatory for a Step.",
+            ),
+        ]
+    ) = None
     variables: dict[str, str] | None = Field(
         default=None,
-        description="A mapping of name-value string pairs used to define addtional top-level BPS settings "
+        title="BPS Variables",
+        description="A mapping of name-value string pairs used to define additional top-level BPS settings "
         "or substitution variables. Note that the values are quoted in the output. For values that should "
         "not be quoted or otherwise used literally, see `literals`",
         examples=[{"operator": "lsstsvc1"}],
     )
     include_files: list[str] | None = Field(
         default_factory=list,
+        title="BPS Include Config Files",
         description="A list of include files added to the BPS submission file under the `includeConfigs`"
         " heading. This list is combined with `include_files` from other manifests.",
         examples=[["${CTRL_BPS_DIR}/python/lsst/ctrl/bps/etc/bps_default.yaml"]],
     )
     literals: dict[str, Any] | None = Field(
         default=None,
+        title="BPS Configuration Literals",
         description="A mapping of arbitrary key-value sections to be added as additional literal YAML to "
         "the BPS submission file. For setting arbitrary BPS substitution variables, use `variables`. ",
         examples=[
             {
-                "requestMemory": 2048,
-                "numberOfRetries": 5,
-                "retryUnlessExit": [1, 2],
-                "finalJob": {"command1": "echo HELLO WORLD"},
+                "literals": {
+                    "requestMemory": 2048,
+                    "numberOfRetries": 5,
+                    "retryUnlessExit": [1, 2],
+                    "finalJob": {"command1": "echo HELLO WORLD"},
+                }
             }
         ],
     )
     environment: dict[str, str] | None = Field(
         default=None,
+        title="BPS Environment Variables",
         description="A mapping of name-value string pairs used to defined additional values under the "
         "`environment` heading of the BPS submission file.",
         min_length=1,
-        examples=[{"LSST_S3_USE_THREADS": 1}],
+        examples=[{"environment": {"LSST_S3_USE_THREADS": 1}}],
     )
     payload: dict[str, str] | None = Field(
         default=None,
+        title="BPS Payload Configuration",
         description="A mapping of name-value string pairs used to define BPS payload options. "
         "Note that these values are generated from other configuration sources at runtime.",
     )
@@ -76,6 +102,7 @@ class BpsSpec(ManifestSpec):
     )
     clustering: dict[str, Any] | None = Field(
         default=None,
+        title="BPS Clustering Configuration",
         description="A mapping of labeled clustering directives, added as literal YAML under the `cluster` "
         "heading. The top-level `clusterAlgorithm` should be added to `literals`.",
         examples=[
@@ -91,6 +118,7 @@ class BpsSpec(ManifestSpec):
     )
     operator: str = Field(
         default="cmservice",
+        title="BPS Operator Name",
         description="The string name of a pilot or operator to reflect in the BPS configuration.",
     )
 

src/lsst/cmservice/models/manifests/butler.py

@@ -54,33 +54,38 @@ class ButlerCollectionsSpec(BaseModel):
         "any ancestor `step_output` collection."
         " This is used internally and generally does not need to be configured.",
         examples=["{campaign_public_output}/{step}/input"],
+        json_schema_extra={"readOnly": True},
     )
     step_output: str | None = Field(
         default=None,
         description="The *chained* output collection for a step, usually consisting of each step-group's "
         "`run` collection."
         " This is used internally and generally does not need to be configured.",
         examples=["{campaign_public_output}/{step}_output"],
+        json_schema_extra={"readOnly": True},
     )
     step_public_output: str | None = Field(
         default=None,
         description="The *chained* output collection that includes the `step_output` and additional step "
         "and/or campaign inputs."
         " This is used internally and generally does not need to be configured.",
         examples=["{campaign_public_output}/{step}"],
+        json_schema_extra={"readOnly": True},
     )
     group_output: str | None = Field(
         default=None,
         description="A collection name associated with the `payload.output` BPS setting."
         " This is used internally and generally does not need to be configured.",
         examples=["{campaign_public_output}/{step}/{group_nonce}", "u/{operator}/{payloadName}"],
+        json_schema_extra={"readOnly": True},
     )
     run: str | None = Field(
         default=None,
         description="The run collection created by a group's execution (the `payload.outputRun` BPS setting)."
         " This is used internally and generally does not need to be configured.",
         examples=["{out}/{step}/{group}/{job}"],
         validation_alias=AliasChoices("job_run", "run"),
+        json_schema_extra={"readOnly": True},
     )
 
 

src/lsst/cmservice/models/manifests/facility.py

@@ -17,11 +17,13 @@ class FacilitySpec(ManifestSpec):
     model_config = SPEC_CONFIG | {"title": "site_spec"}
     facility: Literal["USDF", "IN2P3", "LANC", "RAL"] = Field(
         default="USDF",
+        title="Processing Facility Name",
         description="The name of the processing facility.",
         examples=["USDF", "IN2P3"],
     )
     include_files: list[str] = Field(
         default_factory=list,
+        title="Facility-Specific BPS Include Files",
         description="A list of files to be added to the BPS submission as include files "
         "that are specific to the use of this Facility.",
         examples=[["${DRP_PIPE_DIR}/bps/caching/{instrument}/{site}/{caching}.yaml"]],

src/lsst/cmservice/models/manifests/lsst.py

@@ -18,53 +18,63 @@ class LsstSpec(ManifestSpec):
     model_config = SPEC_CONFIG
     lsst_version: str = Field(
         default="w_latest",
+        title="Stack Version",
         description="LSST Stack version or tag",
         examples=["w_latest", "d_latest", "w_2026_01"],
     )
     lsst_distrib_dir: str = Field(
+        title="LSST Distribution Directory",
         description="Absolute path to a stack distribution location",
         examples=["/sdf/group/rubin/sw/tag/<tag>", "/cvmfs/sw.lsst.eu/linux-x86_64/lsst_distrib/<tag>/"],
     )
     prepend: str | None = Field(
         default=None,
+        title="Stack Setup Prepend Commands",
         description="A newline-delimited string of shell actions to execute prior to stack setup.",
         examples=["echo Hello World", "echo Starting New Campaign\necho Hello World"],
     )
     custom_lsst_setup: str | None = Field(
         default=None,
+        title="Custom Stack Setup Commands",
         description="A newline-delimited string of optional commands to be added to any Bash script that "
         "sets up the LSST Stack, to be executed verbatim *after* EUPS setup but *before* the payload "
         "command. Can be used to customize the Stack with EUPS, for example.",
         examples=["setup --just --root=/path/to/custom/product"],
     )
     append: str | None = Field(
         default=None,
+        title="Stack Setup Append Commands",
         description="A newline-delimited string of shell actions to execute after the payload command.",
         examples=["echo Finished", "source /path/to/custom/script.sh"],
     )
     environment: Mapping | None = Field(
         default_factory=dict,
+        title="Stack Setup Environment Variables",
         description="A mapping of environment variables to set prior to stack setup",
         min_length=1,
-        examples=[{"LSST_USE_OPTIONAL_FEATURE": 1}],
+        examples=[{"environment": {"LSST_USE_OPTIONAL_FEATURE": 1}}],
     )
     ticket: str | None = Field(
         default=None,
+        title="Ticket Number",
         description="An optional JIRA ticket number associated with the campaign.",
-        examples=["DM-XXXXX"],
+        examples=[{"ticket": "DM-XXXXX"}],
     )
     description: str | None = Field(
         default=None,
+        title="Campaign Description",
         description="An optional description of the campaign.",
         examples=["An optional description of the campaign."],
     )
     campaign: str | None = Field(
         default=None,
+        title="Campaign Name",
         description="An optional name for the campaign.",
         examples=["CustomCampaign"],
     )
     project: str | None = Field(
         default=None,
+        title="Campaign Project or Epic",
         description="An optional project name or identifier associated with the campaign.",
         examples=["My special campaign", "Daily batch processing"],
     )