What causes "oneOf variant definition should have a `title` field" in windmill-labs/windmill?

Add a unique string `title` to every schema in the `oneOf` array.

oneOf variant definition should have a `title` field

Error message

oneOf variant definition should have a `title` field

What it means

Windmill identifies each `oneOf` variant by its `title` to key validation rules and render variant selection in the UI. A variant schema in the `oneOf` array without a `title` field cannot be labeled, so `from_primitive` rejects the whole schema.

Source

Thrown at backend/windmill-common/src/schema.rs:93

                    let properties = properties
                        .as_object()
                        .ok_or(anyhow!("Field properties should be an object"))?;

                    for (key, v) in properties {
                        obj_rules.push((key.clone(), SchemaValidationRule::from_value(v)?))
                    }

                    schema_rules.push(SchemaValidationRule::IsObject(obj_rules));
                } else if let Some(one_of) = val.get("oneOf") {
                    let one_of = one_of
                        .as_array()
                        .ok_or(anyhow!("`oneOf` needs to be an array"))?;
                    let mut rules_map: HashMap<String, Vec<SchemaValidationRule>> = HashMap::new();

                    for variant in one_of {
                        let variant_label = variant
                            .get("title")
                            .ok_or(anyhow!(
                                "oneOf variant definition should have a `title` field"
                            ))?
                            .as_str()
                            .ok_or(anyhow!(
                                "oneOf variant definition `title` field should be a string"
                            ))?;
                        if !rules_map.contains_key(variant_label) {
                            rules_map.insert(
                                variant_label.to_string(),
                                SchemaValidationRule::from_value(variant)?,
                            );
                        } else {
                            return Err(anyhow!(
                                "oneOf definition has a duplicate variant `{variant_label}`"
                            ));
                        }
                    }

View on GitHub (pinned to e474e8803c)

Solutions

Add a unique string `title` to every schema in the `oneOf` array.
If the variant comes from a generator, configure it to emit titles or add them post-generation.
Replace `oneOf` with `anyOf`/`properties` if variant labels are not needed.

Example fix

// before
{ "oneOf": [ { "type": "object" } ] }
// after
{ "oneOf": [ { "title": "Option A", "type": "object" } ] }

Defensive patterns

Strategy: validation

Validate before calling

const s = JSON.parse(schemaRaw);
if (Array.isArray(s.oneOf)) {
  const missing = s.oneOf.filter(v => typeof v?.title !== "string");
  if (missing.length) throw new Error("Every oneOf variant needs a string `title`");
}

Type guard

function hasTitledVariants(s) {
  return !Array.isArray(s.oneOf) || s.oneOf.every(v => typeof v?.title === "string");
}

Try / catch

try {
  await deploy(schema);
} catch (e) {
  if (String(e.message).includes("should have a `title` field")) {
    throw new Error("Add a unique string title to each oneOf variant");
  } else throw e;
}

Prevention

Always add a title to every oneOf variant — Windmill uses it as the variant key and UI label.
When importing schemas from generators, post-process to inject titles.
Lint schemas in CI for required titles on oneOf members.

When it happens

Trigger: A `oneOf` array whose element schema lacks a top-level `"title"` string, e.g. `"oneOf": [{ "type": "object", "properties": {} }]` with no `title`.

Common situations: Schemas generated by external tools (OpenAPI generators, editors) that omit `title` on variants; stripping titles when copying schemas; minimal hand-written variants.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

AI-assisted analysis of windmill-labs/windmill@e474e8803c (2026-09-03). Data as JSON: /api/errors/87b954720d812e19. Report an issue: GitHub.