microsoft/semantic-kernel · error · ArgumentException

Property 'schema' is not initialized in JSON schema response

Error message

Property 'schema' is not initialized in JSON schema response format.

What it means

When building a ChatResponseFormat for structured outputs, the connector looks for a json_schema object containing a 'schema' property. If type is 'json_schema' but the nested json_schema object lacks a 'schema' key, ArgumentException is thrown — the schema definition is mandatory for structured-output mode. The 'name' and 'strict' properties are optional.

Source

Thrown at dotnet/src/Connectors/Connectors.OpenAI/Helpers/OpenAIChatResponseFormatBuilder.cs:39

        {
            DisallowAdditionalProperties = true,
            RequireAllProperties = true,
            MoveDefaultKeywordToDescription = true,
        }
    };

    /// <summary>
    /// Gets instance of <see cref="ChatResponseFormat"/> object for JSON schema format for structured outputs from <see cref="JsonElement"/>.
    /// </summary>
    internal static ChatResponseFormat GetJsonSchemaResponseFormat(JsonElement responseFormatElement)
    {
        const string DefaultSchemaName = "JsonSchema";

        if (responseFormatElement.TryGetProperty("type", out var typeProperty) &&
            typeProperty.GetString()?.Equals("json_schema", StringComparison.Ordinal) is true &&
            responseFormatElement.TryGetProperty("json_schema", out var jsonSchemaProperty))
        {
            string schema = jsonSchemaProperty.TryGetProperty("schema", out var schemaProperty) ? schemaProperty.ToString() : throw new ArgumentException("Property 'schema' is not initialized in JSON schema response format.");
            string? schemaName = jsonSchemaProperty.TryGetProperty("name", out var nameProperty) ? nameProperty.GetString() : DefaultSchemaName;
            bool? isStrict = jsonSchemaProperty.TryGetProperty("strict", out var isStrictProperty) && isStrictProperty.ValueKind == JsonValueKind.True ? true : null;

            BinaryData schemaBinaryData = new(Encoding.UTF8.GetBytes(schema));

            return ChatResponseFormat.CreateJsonSchemaFormat(schemaName, schemaBinaryData, jsonSchemaIsStrict: isStrict);
        }

        return ChatResponseFormat.CreateJsonSchemaFormat(
            DefaultSchemaName,
            new BinaryData(Encoding.UTF8.GetBytes(responseFormatElement.ToString())));
    }

    /// <summary>
    /// Gets instance of <see cref="ChatResponseFormat"/> object for JSON schema format for structured outputs from type.
    /// </summary>
    internal static ChatResponseFormat GetJsonSchemaResponseFormat(Type formatObjectType)
    {

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Ensure the json_schema object includes a 'schema' property whose value is the full JSON Schema definition object.
2. Validate the structure before passing: type must be 'json_schema', and json_schema.schema must be present and non-empty.
3. If you don't need strict structured outputs, use a simpler response format instead.

Example fix

// before — missing schema body
var format = JsonSerializer.SerializeToElement(new {
    type = "json_schema",
    json_schema = new { name = "MyResponse" }  // no schema!
});

// after — include the schema definition
var format = JsonSerializer.SerializeToElement(new {
    type = "json_schema",
    json_schema = new {
        name = "MyResponse",
        schema = new {
            type = "object",
            properties = new { answer = new { type = "string" } },
            required = new[] { "answer" }
        }
    }
});

void ValidateJsonSchemaFormat(JsonElement element)
{
    if (element.TryGetProperty("type", out var t) &&
        t.GetString() == "json_schema" &&
        element.TryGetProperty("json_schema", out var js) &&
        !js.TryGetProperty("schema", out _))
    {
        throw new ArgumentException("json_schema response format requires a 'schema' property.");
    }
}

try { var format = OpenAIChatResponseFormatBuilder.GetJsonSchemaResponseFormat(element); }
catch (ArgumentException ex) when (ex.Message.Contains("schema"))
{
    // Log and provide a fallback schema or use a non-schema response format
    logger.LogError("JSON schema response format missing 'schema' property: {Msg}", ex.Message);
    throw;
}

When it happens

Trigger: Providing a response format JSON element with {"type":"json_schema","json_schema":{"name":"MySchema"}} but no actual "schema" field defining the JSON Schema. Common when building the format programmatically and forgetting the schema body.

Common situations: Constructing a JSON-schema response format from partial configuration where only name/strict are set. Migrating from a response_format that used a bare schema at the top level to the nested json_schema envelope. Schema validation libraries producing a different property name.

Related errors

• If response_format has type 'json_schema', 'json_schema' mus
• The option keys 'name' and 'type' are required for a paramet
• If response_format has type 'json_schema', 'json_schema' mus
• Encountered unexpected response_format type: {resp_type}. Al
• response_format must be a dictionary, a subclass of BaseMode

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/ce4888f0f6778d6e. Report an issue: GitHub.