{"record":{"id":"c3854b4a71455aa4","repo":"agentscope-ai/agentscope","slug":"the-defs-key-def-key-conflicts-with-existing","errorCode":null,"errorMessage":"The $defs key `{def_key}` conflicts with existing definition in function schema of `{self.tool.name}`.","messagePattern":"The \\$defs key `(.+?)` conflicts with existing definition in function schema of `(.+?)`\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/agentscope/tool/_types.py","lineNumber":142,"sourceCode":"            for def_key, def_value in extended_schema[\"$defs\"].items():\n                def_value_copy = deepcopy(def_value)\n                _remove_title_field(\n                    def_value_copy,\n                )  # pylint: disable=protected-access\n\n                if def_key in merged_params[\"$defs\"]:\n                    # Check if the two definitions are from the same BaseModel\n                    # by comparing their content\n                    # Create copies and remove title fields for comparison\n\n                    existing_def_copy = deepcopy(\n                        merged_params[\"$defs\"][def_key],\n                    )\n                    _remove_title_field(existing_def_copy)\n\n                    if existing_def_copy != def_value_copy:\n                        # The definitions are different, raise an error\n                        raise ValueError(\n                            f\"The $defs key `{def_key}` conflicts with \"\n                            f\"existing definition in function schema of \"\n                            f\"`{self.tool.name}`.\",\n                        )\n                    # The definitions are the same (from the same BaseModel),\n                    # skip merging this key\n                    continue\n\n                merged_params[\"$defs\"][def_key] = def_value_copy\n\n        return function_schema\n\n\n# The function types that can be registered as tools in AgentScope.\nFunction: TypeAlias = (\n    # Sync function\n    Callable[..., ToolChunk]\n    |","sourceCodeStart":124,"sourceCodeEnd":160,"githubUrl":"https://github.com/agentscope-ai/agentscope/blob/e90f1c7592896cc95f6e5ee506194f533378247d/src/agentscope/tool/_types.py#L124-L160","documentation":"Raised in ToolMetadata.get_tool_schema when merging $defs (JSON-Schema definitions from nested pydantic models) and the same $defs key exists on both sides with different definitions. Identical definitions are merged silently; divergent ones mean two different types share a definition name and the merged schema would be ambiguous.","triggerScenarios":"Extending a tool schema with an extended_model whose nested pydantic models produce a $defs entry (e.g. 'Inner') that differs from an 'Inner' definition already present in the function's schema — same class name, different fields/types.","commonSituations":"Two pydantic models with the same class name but different fields used across the function signature and the extended model; refactored model classes shadowing old names; vendored/duplicated model definitions.","solutions":["Rename one of the colliding nested model classes so their $defs keys differ","Make the two models actually identical (import the same class instead of redefining it)","If a nested model changed shape, update both usages to reference the single current definition"],"exampleFix":"# before\nclass Inner(BaseModel):\n    a: int          # used by the tool function\nclass Inner(BaseModel):\n    b: str          # redefined elsewhere, used by extended model -> conflict\n# after\nclass InnerA(BaseModel):\n    a: int\nclass InnerB(BaseModel):\n    b: str\n# no $defs key collision when merging","handlingStrategy":"validation","validationCode":"fn_defs = set(func_schema.get('$defs', {}))\next_defs = set(ExtendedModel.model_json_schema().get('$defs', {}))\noverlap = fn_defs & ext_defs\nassert not overlap or all(fn_defs[k] == ext_defs[k] for k in overlap), f'conflicting $defs: {overlap}'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never redefine pydantic model classes with duplicate names; import shared models from one module","Rename refactored nested models instead of shadowing existing class names"],"tags":["schema","defs","merge","pydantic","naming"],"backgroundTag":"schema-defs-conflict","analyzedSha":"e90f1c7592896cc95f6e5ee506194f533378247d","analyzedAt":"2026-08-28T18:24:12.087Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}