What causes "%s field %s (%s): optional Data field must use omitempty" in larksuite/cli?

Add `omitempty` to the field's json tag

%s field %s (%s): optional Data field must use omitempty

Error message

%s field %s (%s): optional Data field must use omitempty

What it means

A field marked `schema:"optional"` in a Data struct lacks `omitempty`. Optional output fields must be omitted from the payload when unset; without omitempty the encoder would always emit the zero value, so the compiler enforces the tag combination.

Source

Thrown at shortcuts/common/typed_compile_data.go:238

				return typedObjectShape{}, fmt.Errorf("%s field %s has unsupported json option %q", path, field.Name, option)
			}
		}
		if previous, exists := seen[name]; exists {
			return typedObjectShape{}, fmt.Errorf("%s field %s JSON name %q duplicates field %s", path, field.Name, name, previous)
		}
		seen[name] = field.Name
		schema, err := parseSchemaTag(field.Tag.Get("schema"), field.Type, input)
		if err != nil {
			return typedObjectShape{}, fmt.Errorf("%s field %s (%s): %w", path, field.Name, name, err)
		}
		if !input && schema.defaultValue.Set {
			return typedObjectShape{}, fmt.Errorf("%s field %s (%s): Data field cannot declare default", path, field.Name, name)
		}
		if schema.required && omitempty {
			return typedObjectShape{}, fmt.Errorf("%s field %s (%s): required Data field cannot use omitempty", path, field.Name, name)
		}
		if schema.optional && !omitempty {
			return typedObjectShape{}, fmt.Errorf("%s field %s (%s): optional Data field must use omitempty", path, field.Name, name)
		}
		if isNilCapable(field.Type) && schema.nullable == nil {
			return typedObjectShape{}, fmt.Errorf("%s field %s (%s): nil-capable field must declare nullable or nonnullable", path, field.Name, name)
		}
		description := strings.TrimSpace(field.Tag.Get("doc"))
		if input && description == "" {
			return typedObjectShape{}, fmt.Errorf("%s field %s (%s): description is required via doc", path, field.Name, name)
		}
		fieldShape, err := shapeForType(field.Type, schema, input, active)
		if err != nil {
			return typedObjectShape{}, fmt.Errorf("%s field %s (%s): %w", path, field.Name, name, err)
		}
		shape.Fields = append(shape.Fields, typedValueField{Name: name, Description: description, Required: schema.required, Shape: fieldShape})
	}
	return shape, nil
}

func validateShape(shape typedValueShape, path string) error {

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Add `omitempty` to the field's json tag
Or change the schema tag back to `required` if the field is actually mandatory

Example fix

// before
Note string `json:"note" schema:"optional" doc:"..."`
// after
Note string `json:"note,omitempty" schema:"optional" doc:"..."`

Defensive patterns

Strategy: validation

Validate before calling

if strings.Contains(f.Tag.Get("schema"), "optional") && !strings.Contains(f.Tag.Get("json"), "omitempty") {
    return fmt.Errorf("field %s: optional must use omitempty", f.Name)
}

Prevention

Always write the json tag and schema tag together for optional fields
Use a snippet/template that includes omitempty for optional fields

When it happens

Trigger: Compiling a Data struct (input=false) where a field has `schema:"optional"` but its json tag has no omitempty, via compileStructShape.

Common situations: Adding the optional keyword to an existing always-serialized field; converting a required field to optional and forgetting the json tag; hand-writing both tags from memory.

Related errors

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