{"record":{"id":"a1110377a7c1aa1d","repo":"microsoft/semantic-kernel","slug":"if-response-format-has-type-json-schema-json-s-a11103","errorCode":null,"errorMessage":"If response_format has type 'json_schema', 'json_schema' must be a valid dictionary.","messagePattern":"If response_format has type 'json_schema', 'json_schema' must be a valid dictionary\\.","errorType":"validation","errorClass":"ServiceInvalidExecutionSettingsError","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/connectors/ai/open_ai/prompt_execution_settings/open_ai_prompt_execution_settings.py","lineNumber":134,"sourceCode":"    @model_validator(mode=\"before\")\n    def validate_response_format_and_set_flag(cls, values: Any) -> Any:\n        \"\"\"Validate the response_format and set structured_json_response accordingly.\"\"\"\n        if not isinstance(values, dict):\n            return values\n        response_format = values.get(\"response_format\", None)\n\n        if response_format is None:\n            return values\n\n        if isinstance(response_format, dict):\n            if response_format.get(\"type\") == \"json_object\":\n                return values\n            if response_format.get(\"type\") == \"json_schema\":\n                json_schema = response_format.get(\"json_schema\")\n                if isinstance(json_schema, dict):\n                    values[\"structured_json_response\"] = True\n                    return values\n                raise ServiceInvalidExecutionSettingsError(\n                    \"If response_format has type 'json_schema', 'json_schema' must be a valid dictionary.\"\n                )\n        if isinstance(response_format, type):\n            if issubclass(response_format, BaseModel):\n                values[\"structured_json_response\"] = True\n            else:\n                values[\"structured_json_response\"] = True\n        else:\n            raise ServiceInvalidExecutionSettingsError(\n                \"response_format must be a dictionary, a subclass of BaseModel, a Python class/type, or None\"\n            )\n\n        return values\n\n\nclass OpenAIEmbeddingPromptExecutionSettings(PromptExecutionSettings):\n    \"\"\"Specific settings for the text embedding endpoint.\"\"\"\n","sourceCodeStart":116,"sourceCodeEnd":152,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/connectors/ai/open_ai/prompt_execution_settings/open_ai_prompt_execution_settings.py#L116-L152","documentation":"When the response_format dict has type 'json_schema', the OpenAI structured outputs API requires a 'json_schema' key containing a valid dictionary (the actual JSON Schema definition). The model_validator detects that response_format['type'] == 'json_schema' but response_format['json_schema'] is either missing or not a dict, and raises ServiceInvalidExecutionSettingsError.","triggerScenarios":"Passing response_format={'type': 'json_schema', 'json_schema': 'my_schema_string'} or response_format={'type': 'json_schema'} (missing key) to OpenAIChatPromptExecutionSettings. Common when building the dict dynamically or from a malformed config.","commonSituations":"Serializing a pydantic model to a response_format dict incorrectly (e.g. using model_json_schema() as the top-level value instead of nesting under 'json_schema'); passing the schema name string instead of the schema dict; malformed config files from manual editing.","solutions":["Structure the dict correctly: response_format={'type': 'json_schema', 'json_schema': {'name': 'my_schema', 'schema': {...actual_schema...}}}.","Pass a pydantic BaseModel subclass directly as response_format — the validator handles the conversion.","Validate the dict shape before assignment with a helper that checks json_schema key presence and type."],"exampleFix":"// before\nsettings.response_format = {'type': 'json_schema', 'json_schema': MyClass.model_json_schema()}\n// after\nsettings.response_format = {'type': 'json_schema', 'json_schema': {'name': 'my_class', 'schema': MyClass.model_json_schema()}}\n// or simply:\nsettings.response_format = MyClass  # pass the BaseModel subclass directly","handlingStrategy":"validation","validationCode":"def validate_json_schema_response_format(response_format: dict) -> None:\n    if response_format.get('type') == 'json_schema':\n        js = response_format.get('json_schema')\n        if not isinstance(js, dict):\n            raise ValueError(\n                \"response_format with type 'json_schema' requires 'json_schema' to be a dict, \"\n                f'got {type(js).__name__}'\n            )\n        if 'name' not in js:\n            raise ValueError(\"json_schema must contain a 'name' key\")","typeGuard":"def is_valid_json_schema_response_format(response_format: dict) -> bool:\n    if response_format.get('type') != 'json_schema':\n        return True\n    js = response_format.get('json_schema')\n    return isinstance(js, dict) and 'name' in js","tryCatchPattern":"from semantic_kernel.exceptions import ServiceInvalidExecutionSettingsError\n\ntry:\n    settings = OpenAIChatPromptExecutionSettings(response_format=rf)\nexcept ServiceInvalidExecutionSettingsError as e:\n    if 'json_schema' in str(e):\n        rf['json_schema'] = {'name': 'output', 'schema': rf.pop('json_schema')}\n        settings = OpenAIChatPromptExecutionSettings(response_format=rf)","preventionTips":["Pass a pydantic BaseModel subclass directly as response_format to let the SDK handle structuring.","If building the dict manually, always include 'name' and 'schema' keys under 'json_schema'.","Write a factory function that constructs valid response_format dicts to avoid ad-hoc bugs."],"tags":["openai","json-schema","structured-outputs","execution-settings","semantic-kernel"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}