How Spring AI Now Supports OpenAI Structured JSON Output – A Quick Guide

Last night Spring AI released an important update.

Following OpenAI's new structured output feature that enforces AI responses to conform to a predefined JSON schema, Spring AI now fully supports OpenAI's structured output.

Usage Example

With Spring AI, developers can easily build requests and parse OpenAI's structured output:

String jsonSchema = """ 
  {
      "type": "object",
      "properties": {
          "steps": {
              "type": "array",
              "items": {
                  "type": "object",
                  "properties": {
                      "explanation": { "type": "string" },
                      "output": { "type": "string" }
                  },
                  "required": ["explanation", "output"],
                  "additionalProperties": false
              }
          },
          "final_answer": { "type": "string" }
      },
      "required": ["steps", "final_answer"],
      "additionalProperties": false
  }
  """; 

Prompt prompt = new Prompt("how can I solve 8x + 7 = -23",
OpenAiChatOptions.builder()
    .withModel(ChatModel.GPT_4_O_MINI)
    .withResponseFormat(new ResponseFormat(ResponseFormat.Type.JSON_SCHEMA, jsonSchema))
    .build());

ChatResponse response = this.openAiChatModel.call(prompt);

By specifying ResponseFormat in OpenAiChatOptions, OpenAI can return JSON.

Spring AI also provides BeanOutputConverter to convert the JSON output into Java beans, for example:

record MathReasoning(
  @JsonProperty(required = true, value = "steps") Steps steps,
  @JsonProperty(required = true, value = "final_answer") String finalAnswer) {
    record Steps(
        @JsonProperty(required = true, value = "items") Items[] items) {
        record Items(
            @JsonProperty(required = true, value = "explanation") String explanation,
            @JsonProperty(required = true, value = "output") String output) {}
    }
}

var outputConverter = new BeanOutputConverter<>(MathReasoning.class);
var jsonSchema = outputConverter.getJsonSchema();

Prompt prompt = new Prompt("how can I solve 8x + 7 = -23",
OpenAiChatOptions.builder()
    .withModel(ChatModel.GPT_4_O_MINI)
    .withResponseFormat(new ResponseFormat(ResponseFormat.Type.JSON_SCHEMA, jsonSchema))
    .build());

ChatResponse response = this.openAiChatModel.call(prompt);
String content = response.getResult().getOutput().getContent();

MathReasoning mathReasoning = outputConverter.convert(content);

If you have integrated Spring AI's OpenAI Spring Boot Starter, you can also configure the default JSON response format automatically via application properties:

spring.ai.openai.api-key=YOUR_API_KEY
spring.ai.openai.chat.options.model=gpt-4o-mini

spring.ai.openai.chat.options.response-format.type=JSON_SCHEMA
spring.ai.openai.chat.options.response-format.name=MySchemaName
spring.ai.openai.chat.options.response-format.schema={"type":"object","properties":{"steps":{"type":"array","items":{"type":"object","properties":{"explanation":{"type":"string"},"output":{"type":"string"}},"required":["explanation","output"],"additionalProperties":false}},"final_answer":{"type":"string"}},"required":["steps","final_answer"],"additionalProperties":false}
spring.ai.openai.chat.options.response-format.strict=true

That's the end of the share, thank you for reading!