docs: clarify dict structured output schemas

Author: MukundaKatta

README.md

@@ -919,6 +919,11 @@ However you define your schema, don't duplicate it in your input prompt,
 including by giving examples of expected JSON output. If you do, the generated
 output might be lower in quality.
 
+When defining schemas with Python type hints, `dict[str, AllowedType]`
+describes an object with arbitrary string keys whose values all share the same
+schema. To describe an object with a fixed set of named fields, use a Pydantic
+model or provide an explicit JSON Schema with `properties`.
+
 #### JSON Schema support
 
 Schemas can be provided as standard JSON schema.

codegen_instructions.md

@@ -383,6 +383,10 @@ for message in chat.get_history():
 ### Structured Outputs (Pydantic)
 
 Enforce a specific JSON schema using standard Python type hints or Pydantic models.
+When using Python type hints, `dict[str, AllowedType]` describes an object with
+arbitrary string keys whose values all use the same schema. Use a Pydantic model
+or an explicit JSON Schema with `properties` for objects with a fixed set of
+named fields.
 
 ```python
 from google import genai

docs/_sources/index.rst.txt

@@ -952,6 +952,11 @@ However you define your schema, don't duplicate it in your input prompt,
 including by giving examples of expected JSON output. If you do, the generated
 output might be lower in quality.
 
+When defining schemas with Python type hints, ``dict[str, AllowedType]``
+describes an object with arbitrary string keys whose values all share the same
+schema. To describe an object with a fixed set of named fields, use a Pydantic
+model or provide an explicit JSON Schema with ``properties``.
+
 JSON Schema support
 ^^^^^^^^^^^^^^^^^^^