feat(go): send constrained output via ResponseJsonSchema, with LegacyResponseSchema opt-out

[cabljac]

Migrates the Go Gemini plugin from ResponseSchema, a limited OpenAPI 3.0 subset, to ResponseJsonSchema, which takes raw JSON Schema with $ref/$defs. Recursive Go output types currently collapse to a lossy {type: object, additionalProperties: true}; they now round-trip properly.

Fixes #5478.

Changes

• go/internal/base: InferJSONSchema reflects with references enabled. New InlineAcyclicDefs inlines non-recursive definitions, leaving only genuinely recursive types as $ref/$defs.
• go/plugins/googlegenai: path-scoped cycle guard in toGeminiSchema, shared with tool input schemas.
• go/plugins/googlegenai: constrained output uses ResponseJsonSchema by default, with a LegacyResponseSchema flag restoring the old path, mirroring JS.
• go/samples/recursive-structured: sample.

Refs by default with opt-in inlining means plugins whose APIs can't take $ref call InlineAcyclicDefs themselves. Inlining isn't cheaply reversible, so it belongs at the edge.

Worth a closer look

Enum output also moved to ResponseJsonSchema. The gate is Constrained && ResponseMIMEType != "", which catches text/x.enum; JS gates on jsonMode so enum stays on responseSchema there. Untested against the live API. Happy to narrow the gate to match JS.

Recursive schemas now reach plugins that can't express them. The root is a bare $ref, and other consumers don't handle that: MapToStruct into Anthropic's ToolInputSchemaParam drops it, EnforceStrict no-ops, MCP's server.go indexes properties directly so recursive tool inputs advertise none. Only googlegenai inlines. Flagging rather than burying it.

LegacyResponseSchema restores the wire field, not the old semantics. Validation stays strict while the model gets the laxer schema, and it doesn't cover tools, which still use toGeminiSchema. Migrating tools to ParametersJsonSchema felt like a separate change.

Incidental fixes

Enabling references surfaced latent issues in code that gained callers while this was in flight:

• requestInputSchema splices the config schema under the request's config slot, so a recursive config's $defs nested while its $ref resolved against the root, failing every request to that action. Now hoisted. stripRequired/tolerateNulls didn't descend into $defs either.
• inlineRefs replaced a $ref node wholesale, so a struct-typed field lost its description/title. Local keywords now win, per 2020-12.
• refName misparsed generics whose names embed an import path; status.Error.JSONSchema() returned a $ref resolving against the wrong root.

Separately, toGeminiSchema panicked on valid JSON Schema it can't express ("items": true, boolean property schemas, draft-07 tuples). Pre-existing on main, reachable from any caller-supplied schema, now returns errors.

Testing

Unit coverage on the inlining, cycle guard, generic names, annotation preservation, malformed subschemas, both response branches, and a request-path regression test for recursive configs. go test ./... green, vet and gofmt clean. No live call (needs GEMINI_API_KEY); enum on the new path untested either way.

Predates the typed-config migration (#5849, #5862, #5869, #5874) and was brought up to date with a merge, so read the diff against main rather than the commits.

[gemini-code-assist]

Code Review

This pull request transitions the Google AI and Vertex AI plugins to use the newer ResponseJsonSchema field by default for constrained outputs, enabling support for recursive and self-referential Go types via $ref and $defs. It introduces helper functions to inline acyclic definitions while preserving recursive cycles, adds a LegacyResponseSchema configuration option for backward compatibility, and includes robust tests and a recursive structured output sample. The review feedback highlights critical opportunities to improve robustness in go/plugins/googlegenai/schema.go by replacing unsafe type assertions on the items and properties schema fields with safe type assertions to prevent potential runtime panics.

[gemini-code-assist]

The type assertion v.(map[string]any) is unsafe and will panic if the items field in the schema is not a JSON object (for example, if it is a boolean or an array of schemas, which are valid in some JSON Schema drafts). Using a safe type assertion prevents potential runtime panics.

Suggested change

	items, err := toGeminiSchemaRec(originalSchema, v.(map[string]any), visited)
	m, ok := v.(map[string]any)
	if !ok {
	return nil, fmt.Errorf("items field is not a map")
	}
	items, err := toGeminiSchemaRec(originalSchema, m, visited)

[cabljac]

Applied in 7fc1a27, returning an error rather than panicking. Worth noting for anyone reading this thread: these assertions are pre-existing on main, not introduced here, and the same commit covers three more with the same problem that this review missed, the description/format/title string assertions at schema.go:145-153.

[gemini-code-assist]

The type assertions val.(map[string]any) and v.(map[string]any) are unsafe and will panic if the properties field or any of its property definitions are not JSON objects. Performing safe type assertions prevents runtime panics and improves robustness when handling malformed or unexpected schemas.

	if val, ok := genkitSchema["properties"]; ok {
		propertiesMap, ok := val.(map[string]any)
		if !ok {
			return nil, fmt.Errorf("properties field is not a map")
		}
		props := map[string]*genai.Schema{}
		for k, v := range propertiesMap {
			m, ok := v.(map[string]any)
			if !ok {
				return nil, fmt.Errorf("property %q is not a map", k)
			}
			p, err := toGeminiSchemaRec(originalSchema, m, visited)
			if err != nil {
				return nil, err
			}

[cabljac]

Covered by 7fc1a27, along with the items assertion above and the per-property value.