Skip to content

[BUG] required is dropped for a required nested-model field when that nested model's last-declared field is optional #4379

Description

@BlueX888

Checks

  • I have updated to the lastest minor and patch version of Strands
  • I have checked the documentation and this is not expected behavior
  • I have searched ./issues and there are no duplicates of my issue

SDK Language

Python

Strands Version

1.55.1 — checkout of main at 08ed4cfd3eb42ae9f668595e675d5f196eee7e44 (git describe = python/v1.55.1-20-g08ed4cfd).

I re-checked the current main (e7fd22b6, which contains python/v1.56.0): strands-py/src/strands/tools/structured_output/ is byte-identical between the two revisions, so the bug is still present on the latest main.

Language Runtime Version

Python 3.12.14 (pydantic 2.13.5)

Operating System

macOS 26.6.2 (arm64)

Installation Method

git clone

Steps to Reproduce

from pydantic import BaseModel

from strands.tools.structured_output.structured_output_utils import convert_pydantic_to_tool_spec


class Inner(BaseModel):
    """Inner."""

    a: int
    b: str = "default"  # optional, declared last


class Outer(BaseModel):
    """Outer."""

    inner: Inner  # required nested model


produced = convert_pydantic_to_tool_spec(Outer)["inputSchema"]["json"]
print("produced required      :", produced.get("required"))
print("expected required      :", ["inner"])


# Same model, only the declaration order inside Inner differs.
class Inner2(BaseModel):
    """Inner."""

    b: str = "default"  # optional, declared first
    a: int


class Outer2(BaseModel):
    """Outer."""

    inner: Inner2


produced2 = convert_pydantic_to_tool_spec(Outer2)["inputSchema"]["json"]
print("reordered required     :", produced2.get("required"))

Run against main at 08ed4cfd with a checkout of strands-py/ on PYTHONPATH.

Expected Behavior

Outer.inner is a required field (inner: Inner, no default), so the emitted tool inputSchema.json should carry "required": ["inner"], matching what the same model produces when the last field declared inside Inner happens to be required.

Basis:

  • JSON Schema semantics: required lists the properties that must be present, and inner is required on Outer regardless of what Inner declares internally.
  • The function's own docstring says "Handles required vs. optional fields properly", and the comment at structured_output_utils.py:70 says "Track which properties are actually required after processing".
  • The sibling function _process_schema_object in the same file (line 206) computes is_required = prop_name in required_fields per property and emits result["required"] = required_props — the correct behaviour for the same situation.
  • The repo's own test strands-py/tests/strands/tools/test_structured_output.py::test_convert_pydantic_with_refs (line 374) asserts top-level "required": ["contact"] for a required nested model Contact.

Actual Behavior

The key required is omitted from the top-level schema entirely, so the model is told inner is optional. The nested Inner schema itself is emitted correctly.

Reproduction output (verbatim):

produced required      : None
expected required      : ['inner']
reordered required     : ['inner']

full Outer spec: {
  "type": "object",
  "properties": {
    "inner": {
      "type": "object",
      "description": "The inner",
      "properties": {
        "a": {
          "title": "A",
          "type": "integer"
        },
        "b": {
          "default": "default",
          "title": "B",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "a"
      ]
    }
  },
  "title": "Outer",
  "description": "Outer."
}

Only the declaration order of the fields inside Inner differs between the first and third lines of that output, and it flips required between absent and ["inner"].

An independent verifier reproduced the same behaviour across a matrix of shapes (verbatim):

$ strands_venv/bin/python /tmp/verify_so_matrix.py
nested last=optional   -> required = None
nested last=required   -> required = ['inner']
two nested (opt,req)   -> required = ['b']
leaf only              -> required = ['x']
$ /tmp/verify_so_e2e.py (Agent path, tool_specs handed to model.stream)
tool_specs handed to model.stream -> Outer.required = []
  (full spec ends: "title": "Outer", "description": "Outer.", "required": [])

A second independent verifier (verbatim):

produced required      : None
expected required      : ['inner']
reordered required     : ['inner']

The same wrong behaviour is reachable through the public StructuredOutputTool path:

convert_pydantic_to_tool_spec -> None
StructuredOutputTool.tool_spec.required = None
full: {"type": "object", "properties": {"inner": {"type": "object", "description": "The inner", "properties": {"a": {"title": "A", "type": "integer"}, "b": {"default": "default", "title": "B", "type": ["string", "null"]}}, "required": ["a"]}}, "title": "Outer", "description": "Outer."}

A contract probe over the existing repo test model shows the regression boundary: test_convert_pydantic_with_refs' shape asserts as the test expects, and the same model with one optional field appended to Contact (declared last) flips to no required at all:

repo test shape -> ['contact']
appended optional on Contact -> None

Additional Context

Reachability: convert_pydantic_to_tool_spec is exported from strands.tools (strands/tools/__init__.py:17). It is called by StructuredOutputTool.__init__ -> _get_tool_spec, and directly by the structured-output configs for Bedrock (strands/models/bedrock.py:1711), Anthropic (strands/models/anthropic.py:802) and LiteLLM (strands/models/litellm.py:443). The malformed schema is what is sent to the model as the structured-output tool's input schema, so the model is told a field the caller declared as required may be omitted.

Possible Solution

In _flatten_schema, the nested-property loop should not reuse the outer is_required. Compute the nested sub-property's required-ness into a separate local (e.g. nested_is_required) and pass that to _process_property, leaving the outer is_required from line 44 intact for the check at line 71. A regression test that declares a required nested model whose last field is optional would cover it.

I'm happy to open a small PR with that change plus the test if that's welcome, or happy to be assigned.

Related Issues

None found. I searched the open and closed issues for this repo for "structured output required", "required field dropped", "convert_pydantic_to_tool_spec" and the internal helper names, and found no existing report or fix.

Activity

  1. BlueX888 commented on Sep 17, 2026

    @BlueX888
    ContributorAuthor

    Reproduced this. Root cause: strands-py/src/strands/tools/structured_output/structured_output_utils.py:57 — the nested-property loop reuses the outer is_required local, so after the loop it holds the required-ness of the last nested sub-property, and the check at line 71 emits no top-level required list.

    Minimal reproduction:

    python - <<PY
    from pydantic import BaseModel
    from strands.tools.structured_output.structured_output_utils import convert_pydantic_to_tool_spec
    
    class Inner(BaseModel):
        a: int
        b: str = "default"  # optional, declared last
    
    class Outer(BaseModel):
        inner: Inner
    
    print("produced required :", convert_pydantic_to_tool_spec(Outer)["inputSchema"]["json"].get("required"))
    PY
    

    Observed output:

    produced required : None
    expected required : ["inner"]
    (reordering Inner so its last declared field is required flips this to ["inner"])
    

    Happy to open a PR with this fix, or to be assigned if you prefer to take it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area-structured-outputRelated to the structured output apibugSomething isn't workingpythonPull requests that update python code

    Type

    Fields

    Language

    Python

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions