schema tag must declare exactly one of required or optional

Error message

schema tag must declare exactly one of required or optional

What it means

Thrown by parseSchemaTag when the schema tag string is empty. Every schema tag must state exactly one of required or optional; an empty tag is ambiguous and rejected at compile time. This is a registration-time error surfaced while compiling struct fields.

Source

Thrown at shortcuts/common/typed_compile_args.go:400

	defaultValue typedInputDefault
	enum         []string
	format       string
	minLength    *int
	maxLength    *int
	minimum      *float64
	maximum      *float64
	minItems     *int
	maxItems     *int
}

func schemaHasShapeConstraints(schema schemaTag) bool {
	return len(schema.enum) > 0 || schema.format != "" || hasStringConstraints(schema) || hasNumberConstraints(schema) || hasItemConstraints(schema)
}

func parseSchemaTag(raw string, valueType reflect.Type, input bool) (schemaTag, error) {
	var result schemaTag
	if raw == "" {
		return result, fmt.Errorf("schema tag must declare exactly one of required or optional")
	}
	seen := make(map[string]struct{})
	for _, token := range strings.Split(raw, ";") {
		if token == "" || token != strings.TrimSpace(token) {
			return result, fmt.Errorf("schema contains blank or untrimmed token %q", token)
		}
		key, value, hasValue := strings.Cut(token, "=")
		if _, duplicate := seen[key]; duplicate {
			return result, fmt.Errorf("schema token %q is duplicated", key)
		}
		seen[key] = struct{}{}
		switch key {
		case "required":
			if hasValue {
				return result, fmt.Errorf("schema token required does not accept a value")
			}
			result.required = true
		case "optional":

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Add `required` to the schema tag if the field must be supplied
Add `optional` if the field may be omitted
Remove the empty schema tag entirely if no constraints are needed

Example fix

// before
Name string `cli:"--name;schema:\"\""`
// after
Name string `cli:"--name;schema:\"required\""`

Defensive patterns

Strategy: validation

Validate before calling

if tag == "" {
    return fmt.Errorf("schema tag must declare required or optional")
}
if !strings.Contains(tag, "required") && !strings.Contains(tag, "optional") {
    return fmt.Errorf("schema tag must declare required or optional")
}

Prevention

Never leave schema tag placeholders empty in templates
Always write required or optional as the first token
Add a compile-time smoke test that compiles all argument structs

When it happens

Trigger: A field tagged `cli:"--name;schema:\"\""` or a schema tag that evaluates to the empty string; parseSchemaTag is called from collectArgFields, compileStructShape, and tests with raw == "".

Common situations: Template-generated tags leaving the schema placeholder empty; a refactor that removed all tokens but kept the tag key; hand-editing a tag down to nothing.

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 larksuite/cli@7fd6ef3c07 (2026-09-04). Data as JSON: /api/errors/d8d195933956a6fb. Report an issue: GitHub.