add SchemaRaw option for strict json response format

[h0rv]

Describe the change

Added the ability to pass a raw JSON Schema ([]byte) to ResponseFormat for strict mode (structured output).

This is done to be more dynamic with the JSON schema, as there is many features that are there and may be added to the API that would be out of scope for this client to support. For example: https://platform.openai.com/docs/guides/structured-outputs/definitions-are-supported.

These JSON spec features are provided by other Go libraries, and would not make sense to add to this client (unless wanting to add a json schema package it as a dependency).

Provide OpenAI documentation link

https://platform.openai.com/docs/guides/structured-outputs/definitions-are-supported

Describe your solution

I added a solution to pass in a raw JSON schema and overrode the marshalling method to be compatibile with the existing way and support this way while blocking it if the struct and raw schema are both defined.

Tests

I added an integration test to pass the raw JSON schema throught the new field.

Issue: #814

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 99.02%. Comparing base (774fc9d) to head (e2224ea).
Report is 45 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #824      +/-   ##
==========================================
+ Coverage   98.46%   99.02%   +0.56%     
==========================================
  Files          24       26       +2     
  Lines        1364     1432      +68     
==========================================
+ Hits         1343     1418      +75     
+ Misses         15        8       -7     
  Partials        6        6              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[monstercameron]

Good on you for submitting this change, this is exactly what I need to proceed with my POC.

[gspeicher]

@monstercameron @h0rv can you review this comment as an alternative to adding a SchemaRaw field? PR #819 changes Schema to be of type json.Marshaler, which should give you the flexibility to use whatever you want in place of the baked-in jsonschema package.

[AlexanderHott]

+1

[sashabaranov]

Hey all, we've just merged #819 with Schema improvements — please let me know if it works for you!

[h0rv]

@sashabaranov I am trying to test with 1.29.0 but am seeing this error:

Error: unsupported type: map

Any reason maps aren't supported? I am using a struct to JSON Schema library which has some mapped fields like this and its not in the actual struct.

It looks like structs are mapping to JSON Objects, and I think maps should be mapped to a JSON Object too.

[sashabaranov]

@h0rv Good point, we are totally open for a PR with map support! :D cc @eiixy

[gspeicher]

EDIT: just use Schema: json.RawMessage(mySchema) instead of defining a custom type, as adroitly suggested by @eiixy below!

As an alternative, if you already have your schema in a string and want to avoid having to transform it to a jsonschema.Schema object altogether, you should be able to do something like this:

// StringSchema is a custom type that wraps a string for use as a structured response schema
type StringSchema string

// MarshalJSON implements the json.Marshaler interface for StringSchema
func (m StringSchema) MarshalJSON() ([]byte, error) {
	return []byte(m), nil
}

var mySchema = "<your schema here>"

resp, err := client.CreateChatCompletion(ctx, openai.ChatCompletionRequest{
                // ...
		ResponseFormat: &openai.ChatCompletionResponseFormat{
			Type: openai.ChatCompletionResponseFormatTypeJSONSchema,
			JSONSchema: &openai.ChatCompletionResponseFormatJSONSchema{
				Name:   "my_schema",
				Schema: StringSchema(mySchema),
				Strict: true,
			}
		}
})

That was from the hip so you may need to fix as needed but you get the idea.

[eiixy]

When converting map types to JSON Schema, the main challenges are:

• Uncertain Types: map values can be of any type, making it difficult to define a JSON Schema.
• Undefined Structure: The structure of map fields can be dynamic or unknown.
• Validation Complexity: Validating dynamic and undefined map types is complex.

You can directly use json.RawMessage(mySchema)

[h0rv]

Thanks the replies - I will try using the the string schema directly.

[gspeicher]

You can directly use json.RawMessage(mySchema)

Oh nice, I was not aware of that gem. This is much better than implementing your own as I suggested above. Thanks for calling this out! Perhaps it should go in the documentation...

[h0rv]

Awesome - was able to get it working and add support for strict mode with instructor. Just added the feature in the latest release.

Example: https://github.com/instructor-ai/instructor-go/blob/b63ca60f159b7c7cb9517aec12082b27a6cec0e5/examples/auto_ticketer/main.go#L106-L129

[h0rv]

I'm going to close this as its not required with the last PR. Thanks for the help everyone!