[QUESTION] extracting json_schema structured data from responses api

[James-Timeoutdoors]

How can we help?

The structured data information in the open api docs has examples of how to use it for Curl, javascript and python but not .net

https://platform.openai.com/docs/guides/structured-outputs?example=structured-data&lang=curl

I'm struggling to see how to use the ResponseCreationOptions to create json_schema. Is it supported yet?

[stephentoub]

@James-Timeoutdoors, do you mean you have a .NET type and you're asking how to get a schema for it?

You can use the support in Microsoft.Extensions.AI.Abstractions to do that, and the exposed conversion routines in Microsoft.Extensions.AI.OpenAI make it easy to turn that into something you can directly store into a ResponseCreationOptions, e.g. this line will create an M.E.AI ChatResponseFormat for my custom CalendarEvent type, and will then create an OpenAI ResponseTextFormat from it:

ChatResponseFormat.ForJsonSchema<CalendarEvent>().AsOpenAIResponseTextFormat()

So with an example like:

#pragma warning disable OPENAI001
using Microsoft.Extensions.AI;
using OpenAI;
using OpenAI.Responses;

var responses = new OpenAIClient(Environment.GetEnvironmentVariable("AI:OpenAI:ApiKey"))
    .GetOpenAIResponseClient("gpt-4o-mini");

ResponseCreationOptions rco = new()
{
    TextOptions = new()
    {
        TextFormat = ChatResponseFormat.ForJsonSchema<CalendarEvent>().AsOpenAIResponseTextFormat(),
    }
};

var result = await responses.CreateResponseAsync(    
    "Create a calendar event for a team meeting on July 10th, 2024 at 10 AM with participants Alice, Bob, and Charlie.",
    rco);

Console.WriteLine(result.Value.GetOutputText());

class CalendarEvent
{
    public string Name { get; set; }
    public string Date { get; set; }
    public List<string>? Participants { get; set; }
}

That outputs:

{"name":"Team Meeting","date":"2024-07-10T10:00:00","participants":["Alice","Bob","Charlie"]}

If you're going through IChatClient instead, you can either just store the ChatResponseFormat into your ChatOptions.ResponseFormat, or you can use the GetResponseAsync<T> extension method to automate this for you, including the deserialization back into a CalendarEvent, e.g. this:

#pragma warning disable OPENAI001
using Microsoft.Extensions.AI;
using OpenAI;

var client = new OpenAIClient(Environment.GetEnvironmentVariable("AI:OpenAI:ApiKey"))
    .GetOpenAIResponseClient("gpt-4o-mini")
    .AsIChatClient();

var result = await client.GetResponseAsync<CalendarEvent>(
    "Create a calendar event for a team meeting on July 10th, 2024 at 10 AM with participants Alice, Bob, and Charlie.");

Console.WriteLine($"Event Name: {result.Result.Name}");
Console.WriteLine($"Event Date: {result.Result.Date}");
Console.WriteLine($"Participants: {string.Join(", ", result.Result.Participants ?? [])}");

class CalendarEvent
{
    public string Name { get; set; }
    public string Date { get; set; }
    public List<string>? Participants { get; set; }
}

outputs:

Event Name: Team Meeting
Event Date: 2024-07-10T10:00:00
Participants: Alice, Bob, Charlie

[jsquire]

Hi @James-Timeoutdoors. Thanks for reaching out and for your inquiry. To compliment Stephen's MEAI example, here's what a call would look like using only the OpenAI client library:

// Create the schema.
var schema = BinaryData.FromString("""
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "position": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9
    },
    "token": {
      "type": "integer",
      "minimum": 2,
      "maximum": 8
    },
  },
  "additionalProperties": false,
  "required": [
    "position",
    "token"
  ]
}
""");

// Set instructions that describe the rules of the game.
var instructions = """
    You are playing Numeric Tic-Tac-Toe.

    RULES:
    - 3x3 board (positions 0-8, row-major order)
    - Board format: 9 pipe-separated values, where 0 = empty
    - You may place tokens only on an empty position, represented by 0.
    - You may only use each token once per game.
    - Win condition: Three numbers in a line (row, column, or diagonal) sum to exactly 15

    RESPONSE FORMAT (JSON only):
    {
      "position": <0-8>,
      "token": <your chosen number>
    }

    IMPORTANT: Respond ONLY with valid JSON. No additional text.
""";

// Prompt for a turn
var prompt = ResponseItem.CreateUserMessageItem($$"""
    You are playing a turn for Odd and should make your move based on the following game state:

    Board:  0|0|0|0|0|0|0|0|0
    Your available tokens: 1,3,5,7,9
    Opponent's available tokens: 2,4,6,8
""");

// For a real scenario, you'd want to capture the conversation history, but for
// this example, we're just showing the opening move.
var client = new OpenAIResponseClient("gpt-5", "<< YOUR API KEY >>");

var responseOptions = new ResponseCreationOptions
{
    Instructions = instructions,
    TextOptions = new ResponseTextOptions
    {
        TextFormat = ResponseTextFormat.CreateJsonSchemaFormat("response", schema)
    }
};

OpenAIResponse response = await client.CreateResponseAsync([ prompt ], responseOptions);

[James-Timeoutdoors]

Hi both, thanks for this!

It was
TextOptions = new ResponseTextOptions
{
TextFormat = ResponseTextFormat.CreateJsonSchemaFormat("response", schema)
}
that I was missing. I don't know if it could be better signposted in docs or examples?