{"record":{"id":"d8d195933956a6fb","repo":"larksuite/cli","slug":"schema-tag-must-declare-exactly-one-of-required-or","errorCode":null,"errorMessage":"schema tag must declare exactly one of required or optional","messagePattern":"schema tag must declare exactly one of required or optional","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"shortcuts/common/typed_compile_args.go","lineNumber":400,"sourceCode":"\tdefaultValue typedInputDefault\n\tenum         []string\n\tformat       string\n\tminLength    *int\n\tmaxLength    *int\n\tminimum      *float64\n\tmaximum      *float64\n\tminItems     *int\n\tmaxItems     *int\n}\n\nfunc schemaHasShapeConstraints(schema schemaTag) bool {\n\treturn len(schema.enum) > 0 || schema.format != \"\" || hasStringConstraints(schema) || hasNumberConstraints(schema) || hasItemConstraints(schema)\n}\n\nfunc parseSchemaTag(raw string, valueType reflect.Type, input bool) (schemaTag, error) {\n\tvar result schemaTag\n\tif raw == \"\" {\n\t\treturn result, fmt.Errorf(\"schema tag must declare exactly one of required or optional\")\n\t}\n\tseen := make(map[string]struct{})\n\tfor _, token := range strings.Split(raw, \";\") {\n\t\tif token == \"\" || token != strings.TrimSpace(token) {\n\t\t\treturn result, fmt.Errorf(\"schema contains blank or untrimmed token %q\", token)\n\t\t}\n\t\tkey, value, hasValue := strings.Cut(token, \"=\")\n\t\tif _, duplicate := seen[key]; duplicate {\n\t\t\treturn result, fmt.Errorf(\"schema token %q is duplicated\", key)\n\t\t}\n\t\tseen[key] = struct{}{}\n\t\tswitch key {\n\t\tcase \"required\":\n\t\t\tif hasValue {\n\t\t\t\treturn result, fmt.Errorf(\"schema token required does not accept a value\")\n\t\t\t}\n\t\t\tresult.required = true\n\t\tcase \"optional\":","sourceCodeStart":382,"sourceCodeEnd":418,"githubUrl":"https://github.com/larksuite/cli/blob/7fd6ef3c07182257ce776cdc5a614e122d5bd4b3/shortcuts/common/typed_compile_args.go#L382-L418","documentation":"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.","triggerScenarios":"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 == \"\".","commonSituations":"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.","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"],"exampleFix":"// before\nName string `cli:\"--name;schema:\\\"\\\"\"`\n// after\nName string `cli:\"--name;schema:\\\"required\\\"\"`","handlingStrategy":"validation","validationCode":"if tag == \"\" {\n    return fmt.Errorf(\"schema tag must declare required or optional\")\n}\nif !strings.Contains(tag, \"required\") && !strings.Contains(tag, \"optional\") {\n    return fmt.Errorf(\"schema tag must declare required or optional\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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"],"tags":["cli","schema","tags","validation"],"backgroundTag":"schema-validation-failed","analyzedSha":"7fd6ef3c07182257ce776cdc5a614e122d5bd4b3","analyzedAt":"2026-09-04T21:17:44.649Z","contentChangedAt":"2026-09-04T21:17:44.649Z","schemaVersion":2},"datasetVersion":"2026-09-12T02:17:10.037Z"}