larksuite/cli · error

schema token optional does not accept a value

Error message

schema token optional does not accept a value

What it means

Thrown by parseSchemaTag when the optional token carries a value, e.g. `optional=false`. Like required, optional is a bare marker with no value; exactly one of required/optional must be declared without a value.

Source

Thrown at shortcuts/common/typed_compile_args.go:420

	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":
			if hasValue {
				return result, fmt.Errorf("schema token optional does not accept a value")
			}
			result.optional = true
		case "nullable", "nonnullable":
			if hasValue {
				return result, fmt.Errorf("schema token %s does not accept a value", key)
			}
			if result.nullable != nil {
				return result, fmt.Errorf("schema cannot declare both nullable and nonnullable")
			}
			v := key == "nullable"
			result.nullable = &v
		case "default":
			if !hasValue || value == "" {
				return result, fmt.Errorf("schema default requires a JSON literal")
			}
			if !input {
				return result, fmt.Errorf("Data field cannot declare default")
			}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Write the bare token `optional`
2. Replace `optional=false` with `required`
3. Remove the `=value` suffix

Example fix

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

if key == "optional" && strings.Contains(token, "=") {
    return fmt.Errorf("optional must be a bare token; use required to negate")
}

When it happens

Trigger: A tag like `schema:"optional=true"`; parseSchemaTag finds key optional with hasValue true. Also note TestParseSchemaTagPreservesExplicitZeroFalseAndEmptyDefaults implies false/empty defaults are preserved elsewhere — but the optional token itself never accepts a value.

Common situations: Trying to express 'not optional' via optional=false instead of writing required; template engines emitting key=value for all boolean flags.

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

• schema token required does not accept a value
• schema token %s does not accept a value
• schema tag must declare exactly one of required or optional
• schema contains blank or untrimmed token %q
• schema token %q is duplicated

AI-assisted analysis of larksuite/cli@7fd6ef3c07 (2026-09-04). Data as JSON: /api/errors/507a30b74624b316. Report an issue: GitHub.