{"record":{"id":"58f5180ee9b41e1a","repo":"larksuite/cli","slug":"nil-capable-encoding-json-input-must-declare-nulla","errorCode":null,"errorMessage":"nil-capable encoding=json input must declare nullable or nonnullable","messagePattern":"nil-capable encoding=json input must declare nullable or nonnullable","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"shortcuts/common/typed_compile_args.go","lineNumber":336,"sourceCode":"\t\t\treturn fmt.Errorf(\"encoding repeated does not allow nullable/nonnullable\")\n\t\t}\n\tcase typedEncodingCommaOrRepeated:\n\t\tif kind != reflect.Slice && kind != reflect.Array {\n\t\t\treturn fmt.Errorf(\"encoding comma_or_repeated requires an array or slice\")\n\t\t}\n\t\telementKind := indirectType(field.valueType).Elem().Kind()\n\t\tif elementKind != reflect.String && !isIntegerKind(elementKind) {\n\t\t\treturn fmt.Errorf(\"encoding comma_or_repeated only supports string or integer arrays\")\n\t\t}\n\t\tif field.nullable != nil {\n\t\t\treturn fmt.Errorf(\"encoding comma_or_repeated does not allow nullable/nonnullable\")\n\t\t}\n\tcase typedEncodingJSON:\n\t\tif kind != reflect.Slice && kind != reflect.Array && kind != reflect.Struct && kind != reflect.Map && kind != reflect.Interface {\n\t\t\treturn fmt.Errorf(\"encoding json requires array, object, oneOf, or custom JSON input\")\n\t\t}\n\t\tif isNilCapable(field.valueType) && field.nullable == nil && !field.shapeExplicit && !shapeExplicitlyNullable(field.shape) {\n\t\t\treturn fmt.Errorf(\"nil-capable encoding=json input must declare nullable or nonnullable\")\n\t\t}\n\tdefault:\n\t\treturn fmt.Errorf(\"unknown CLI encoding %q\", field.cli.Encoding)\n\t}\n\tseenAliases := make(map[string]struct{})\n\tfor i, alias := range field.cli.Aliases {\n\t\tif !aliasNamePattern.MatchString(alias.Name) {\n\t\t\treturn fmt.Errorf(\"alias[%d] name %q is invalid\", i, alias.Name)\n\t\t}\n\t\tif alias.Name == field.name {\n\t\t\treturn fmt.Errorf(\"alias[%d] duplicates canonical flag --%s\", i, field.name)\n\t\t}\n\t\tif _, duplicate := seenAliases[alias.Name]; duplicate {\n\t\t\treturn fmt.Errorf(\"duplicate alias --%s\", alias.Name)\n\t\t}\n\t\tseenAliases[alias.Name] = struct{}{}\n\t\tswitch alias.Mode {\n\t\tcase typedAliasNormalize:","sourceCodeStart":318,"sourceCodeEnd":354,"githubUrl":"https://github.com/larksuite/cli/blob/7fd6ef3c07182257ce776cdc5a614e122d5bd4b3/shortcuts/common/typed_compile_args.go#L318-L354","documentation":"For encoding=json fields whose Go type can hold nil (slices, maps, pointers, interfaces), the author must state explicitly via `nullable` or `nonnullable` in the schema tag whether a null JSON value is allowed. The omission check is skipped when the shape was declared explicitly (shapeExplicit or an explicitly nullable shape), but a bare nil-capable type with no declaration fails validation.","triggerScenarios":"A field like []string or map[string]string with cli:\"encoding=json\" whose schema tag has neither `nullable` nor `nonnullable`, and no explicit Shape covering nullability; compileInput -> validateInputCLI fails.","commonSituations":"Adding encoding=json to an existing optional field without revisiting its schema tag; upgrading the typed-input framework where the explicit-nullability declaration became mandatory.","solutions":["Add `nullable` (accept explicit null) or `nonnullable` (reject null) to the schema tag.","Or declare an explicit Shape that already states nullability, satisfying shapeExplicit.","Make the type non-nil-capable (e.g. struct instead of map/slice) if null never applies."],"exampleFix":"// before\nFilter map[string]string `schema:\"optional\" cli:\"encoding=json\"`\n// after\nFilter map[string]string `schema:\"optional;nonnullable\" cli:\"encoding=json\"`","handlingStrategy":"validation","validationCode":"func jsonFieldDeclaresNullability(schemaTagStr string) error {\n\tif strings.Contains(schemaTagStr, \"nullable\") || strings.Contains(schemaTagStr, \"nonnullable\") {\n\t\treturn nil\n\t}\n\treturn fmt.Errorf(\"encoding=json nil-capable fields must declare nullable or nonnullable\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Whenever adding encoding=json, add nullable or nonnullable in the same edit.","Prefer nonnullable unless the API genuinely accepts explicit null.","Alternatively declare an explicit Shape that encodes nullability."],"tags":["cli","schema","nullable","authoring-time"],"backgroundTag":"invalid-cli-tag-encoding","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"}