What causes "json.RawMessage requires an explicit Shape" in larksuite/cli?

Replace the json.RawMessage field with a concrete struct that models the actual JSON content.

json.RawMessage requires an explicit Shape

Error message

json.RawMessage requires an explicit Shape

What it means

During command registration the typed Data compiler walks the Go struct fields of a shortcut's Output.Data to derive a JSON ValueShape. json.RawMessage deliberately has no static schema — its content is arbitrary JSON — so the compiler refuses to guess one. It throws this error so the developer supplies an explicit Output.Data.Shape (or a narrower typed struct) instead.

Source

Thrown at shortcuts/common/typed_compile_data.go:138

			return nil, fmt.Errorf("integer field has incompatible schema constraint")
		}
		shape = integerShape
	case reflect.Float32, reflect.Float64:
		numberShape := typedNumberShape{Minimum: schema.minimum, Maximum: schema.maximum}
		for _, raw := range schema.enum {
			v, err := parseFiniteFloatBits(raw, baseType.Bits())
			if err != nil {
				return nil, fmt.Errorf("enum value %q is not a finite number", raw)
			}
			numberShape.Enum = append(numberShape.Enum, v)
		}
		if hasStringConstraints(schema) || hasItemConstraints(schema) || schema.format != "" {
			return nil, fmt.Errorf("number field has incompatible schema constraint")
		}
		shape = numberShape
	case reflect.Slice, reflect.Array:
		if baseType == jsonRawMessageType {
			return nil, fmt.Errorf("json.RawMessage requires an explicit Shape")
		}
		if baseType.Elem().Kind() == reflect.Uint8 {
			return nil, fmt.Errorf("byte slice or array %s requires an explicit Shape", baseType)
		}
		if len(schema.enum) > 0 || hasStringConstraints(schema) || hasNumberConstraints(schema) || schema.format != "" {
			return nil, fmt.Errorf("array field has incompatible schema constraint")
		}
		elementSchema := schemaTag{required: true}
		elementShape, err := shapeForType(baseType.Elem(), elementSchema, input, active)
		if err != nil {
			return nil, fmt.Errorf("array item: %w", err)
		}
		shape = typedArrayShape{Items: elementShape, MinItems: schema.minItems, MaxItems: schema.maxItems}
	case reflect.Struct:
		if implementsCustomEncoding(baseType) {
			return nil, fmt.Errorf("custom JSON type %s requires an explicit Shape", baseType)
		}
		if len(schema.enum) > 0 || hasStringConstraints(schema) || hasNumberConstraints(schema) || hasItemConstraints(schema) || schema.format != "" {

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Replace the json.RawMessage field with a concrete struct that models the actual JSON content.
If the content is genuinely arbitrary, change Output.Data to `any` (empty interface) so anyJSONShape is used.
Provide an explicit Output.Data.Shape so the compiler does not derive one from the Go type.
Use an Overrides entry or a custom Shape for just that field, keeping other fields inferred.

Example fix

// before
type Data struct {
    Extra json.RawMessage `json:"extra"`
}

// after
type ExtraPayload struct {
    Kind string `json:"kind"`
    Size int    `json:"size"`
}
type Data struct {
    Extra ExtraPayload `json:"extra"`
}

Defensive patterns

Strategy: validation

Validate before calling

func usesRawMessage(t reflect.Type) bool {
    if t == reflect.TypeFor[json.RawMessage]() { return true }
    switch t.Kind() {
    case reflect.Struct:
        for i := 0; i < t.NumField(); i++ {
            if usesRawMessage(t.Field(i).Type) { return true }
        }
    case reflect.Slice, reflect.Array, reflect.Pointer:
        return usesRawMessage(t.Elem())
    }
    return false
}
// fail registration early if usesRawMessage(reflect.TypeFor[Data]())

Type guard

func isRawMessage(t reflect.Type) bool { return t == reflect.TypeFor[json.RawMessage]() }

Prevention

Never put json.RawMessage in typed Output.Data structs; use `any` Data or concrete types.
Keep passthrough DTOs and typed Data definitions in separate types.
Run the shortcut registration in a quick smoke test so compile errors surface in CI.

When it happens

Trigger: Declaring a shortcut Output.Data struct with a field of type json.RawMessage and compiling via compileData -> shapeForType when no explicit Output.Data.Shape is provided.

Common situations: Copying an API-response passthrough struct into typed Data; refactoring `interface{}` fields to json.RawMessage for safety; reusing an existing DTO that carries raw JSON blobs.

Related errors

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