{"record":{"id":"fa16364d2c997794","repo":"larksuite/cli","slug":"s-field-s-s-description-is-required-via-doc","errorCode":null,"errorMessage":"%s field %s (%s): description is required via doc","messagePattern":"(.+?) field (.+?) \\((.+?)\\): description is required via doc","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"shortcuts/common/typed_compile_data.go","lineNumber":245,"sourceCode":"\t\tschema, err := parseSchemaTag(field.Tag.Get(\"schema\"), field.Type, input)\n\t\tif err != nil {\n\t\t\treturn typedObjectShape{}, fmt.Errorf(\"%s field %s (%s): %w\", path, field.Name, name, err)\n\t\t}\n\t\tif !input && schema.defaultValue.Set {\n\t\t\treturn typedObjectShape{}, fmt.Errorf(\"%s field %s (%s): Data field cannot declare default\", path, field.Name, name)\n\t\t}\n\t\tif schema.required && omitempty {\n\t\t\treturn typedObjectShape{}, fmt.Errorf(\"%s field %s (%s): required Data field cannot use omitempty\", path, field.Name, name)\n\t\t}\n\t\tif schema.optional && !omitempty {\n\t\t\treturn typedObjectShape{}, fmt.Errorf(\"%s field %s (%s): optional Data field must use omitempty\", path, field.Name, name)\n\t\t}\n\t\tif isNilCapable(field.Type) && schema.nullable == nil {\n\t\t\treturn typedObjectShape{}, fmt.Errorf(\"%s field %s (%s): nil-capable field must declare nullable or nonnullable\", path, field.Name, name)\n\t\t}\n\t\tdescription := strings.TrimSpace(field.Tag.Get(\"doc\"))\n\t\tif input && description == \"\" {\n\t\t\treturn typedObjectShape{}, fmt.Errorf(\"%s field %s (%s): description is required via doc\", path, field.Name, name)\n\t\t}\n\t\tfieldShape, err := shapeForType(field.Type, schema, input, active)\n\t\tif err != nil {\n\t\t\treturn typedObjectShape{}, fmt.Errorf(\"%s field %s (%s): %w\", path, field.Name, name, err)\n\t\t}\n\t\tshape.Fields = append(shape.Fields, typedValueField{Name: name, Description: description, Required: schema.required, Shape: fieldShape})\n\t}\n\treturn shape, nil\n}\n\nfunc validateShape(shape typedValueShape, path string) error {\n\tif shape == nil {\n\t\treturn fmt.Errorf(\"%s is nil\", path)\n\t}\n\tswitch value := shape.(type) {\n\tcase anyJSONShape:\n\tcase typedStringShape:\n\t\tif value.MinLength != nil && *value.MinLength < 0 || value.MaxLength != nil && *value.MaxLength < 0 {","sourceCodeStart":227,"sourceCodeEnd":263,"githubUrl":"https://github.com/larksuite/cli/blob/7fd6ef3c07182257ce776cdc5a614e122d5bd4b3/shortcuts/common/typed_compile_data.go#L227-L263","documentation":"Every field of an Input struct (input=true) must provide a human-readable description via a non-empty `doc:` tag. The compiler uses it to generate schema/help text for agents and users; an undocumented input field is rejected at compile time.","triggerScenarios":"Compiling an Input struct where a field's `doc:` tag is missing, empty, or whitespace-only (`strings.TrimSpace` yields \"\"), via compileStructShape.","commonSituations":"Adding a new input field and skipping documentation; leaving `doc:\"\"` as a TODO; tags placed on the wrong line/field after refactor; using only a json tag copied from a Data struct (docs required only for inputs).","solutions":["Add a meaningful `doc:\"...\"` tag describing the field's purpose and expectations","Fill in an existing empty doc tag with real content (not spaces)","If the field is output-only, confirm you intended input=true compilation"],"exampleFix":"// before\nLimit int `json:\"limit\" schema:\"optional\"`\n// after\nLimit int `json:\"limit\" schema:\"optional\" doc:\"Maximum number of items to return (1-100)\"`","handlingStrategy":"validation","validationCode":"if isInput && strings.TrimSpace(f.Tag.Get(\"doc\")) == \"\" {\n    return fmt.Errorf(\"field %s: doc tag required for input fields\", f.Name)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Write the doc: tag whenever you add an input field — treat it as part of the field","Never leave doc:\"\" placeholders; describe units, ranges, and expectations","Keep Data-struct docs optional but Input-struct docs mandatory in review checklists"],"tags":["go","struct-tags","documentation","schema-compile","input-shape"],"backgroundTag":"missing-doc-tag","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"}