Deployment Parameter UI#

The Deployment Parameter UI is the system for rendering and editing flow run parameters in Prefect UI (ui-v2). It drives two main surfaces: the Custom Run form for triggering deployment runs with parameter overrides, and the Deployment Parameters table, a read-only view of a deployment's defined parameters. Both are powered by the deployment's parameter_openapi_schema field — an OpenAPI-compatible JSON Schema describing parameter names, types, defaults, and constraints 1.

Architecture#

Schema → Form pipeline#

The parameter_openapi_schema is stored on the Deployment object. The SchemaForm component acts as the top-level form renderer: it wraps SchemaFormProvider (context) around SchemaFormInputObject, which recursively renders per-property fields 2.

Each property is rendered via SchemaFormProperty, which handles label, description, errors, default-value initialization, and the per-field "kind" menu 3. The concrete input widget is chosen by SchemaFormInput, which dispatches on property.type and schema traits 4.

Input type dispatch#

SchemaFormInput selects the concrete input component based on schema conditions:

Enum / Literal dropdowns#

When a string (or other primitive) property has an enum field, SchemaFormInputString calls isWithPrimitiveEnum() and renders SchemaFormInputEnum instead of a textarea. SchemaFormInputEnum renders a searchable Combobox and supports both single-select and multi-select modes 5.

The enum field in the schema is produced server-side from Literal[...] Python type annotations—schema_converter.py's _convert_enum() and _convert_const() convert JSON Schema enum/const to Literal[...] Python types.

Custom Run Form#

The "Custom Run" page lives at custom-run-page.tsx. It mounts CreateFlowRunForm and passes overrideParameters 6.

CreateFlowRunForm:

• Renders LazySchemaForm with kinds={["json"]} for the parameters section 7
• Shows an Enforce Parameter Schema toggle, which gates server-side validation on form submit 8
• Provides additional options: message, tags, work queue, retries, job variables

useCreateFlowRunForm:

• Captures initial parameter values from overrideParameters ?? deployment.parameters ?? {} at mount time; subsequent deployment refetches do not overwrite in-flight edits 9
• Calls validateParametersForm before submitting only when enforce_parameter_schema is true 10
• Submits via createDeploymentFlowRun, posting parameters: parameterValues derived from the schema form 11

Quick Run (use-quick-run.tsx) skips the parameter form entirely and submits a SCHEDULED state payload with no parameter overrides 12.

Deployment Parameters Table#

DeploymentParametersTable is the read-only view on the deployment detail page. It reads deployment.parameter_openapi_schema.properties, sorts by the position field, and maps each property to rows showing:

• Key — parameter name
• Override — value set on the deployment
• Default — default from the OpenAPI schema
• Type — type from the schema

Rows are sortable by the position field set in the OpenAPI schema 13, and the table includes a client-side search filter.

"Prefect Kind" Input Modes#

Each property field has a context menu that lets users switch between input modes ("kinds"):

• Form Input (default) — type-appropriate widget
• JSON Input (json) — raw JSON editor
• Jinja Template (jinja) — Jinja string editor
• Select Variable (workspace_variable) — workspace variable combobox

Kinds available to a form instance are controlled by the kinds prop passed to SchemaForm. The custom run form passes kinds={["json"]} 14, meaning only "Use Form Input" and "Use JSON Input" are available in the OSS Server custom run UI. The workspace_variable kind requires it to be explicitly added to the kinds array 15.

Validation#

Schema values are validated server-side via POST /ui/schemas/validate. The useSchemaForm hook wires up debounced re-validation after the first explicit validation attempt, and exposes a validateForm({ schema }) callback for imperative validation.

Default Value Handling#

SchemaFormProperty auto-populates a field's default value (from the default schema property) on mount when the passed value is undefined. This behaviour can be disabled by passing skipDefaultValueInitialization={true} to SchemaForm.

A known bug in the Prefect 2.x UI caused custom parameter values to be overridden by defaults when running a flow with a parameter named name 16; this was resolved in the 3.x UI.

Key Source Files#