OpenAi JsonSchema

OpenAi-JsonSchema is a lightweight library for generating valid JSON Schema for OpenAI's Structured Outputs feature, ensuring compatibility with OpenAI's JSON Schema subset. It simplifies the creation of structured outputs for OpenAI models, following the schema generation guidelines provided by OpenAI.

Features

• Supports System.ComponentModel.DescriptionAttribute for generating descriptions in the JSON Schema.
• Handles Nullable<T> types (e.g., int?) and nullable reference types (e.g., string?).
• Supports a wide range of types, including primitives such as bool, int, double, and DateTime.
• Automatically manages $defs and $ref in the schema (e.g., "$ref": "#/$defs/MyType").
• Ensures compatibility with OpenAI's JSON Schema format for structured outputs.
• Polymorphism support using JsonPolymorphicAttribute and JsonDerivedTypeAttribute to generate schemas for polymorphic types.
• Supports JsonIgnoreAttribute and all other System.Text.Json attributes for flexible schema customization.

Installation

Install via NuGet:

Install-Package LarchSys.OpenAi.JsonSchema

Quick Start

The following example demonstrates how to generate a JSON Schema using the LarchSys.OpenAi.JsonSchema library.

// use Json Options to control PropertyName and Enum serialization:
var jsonOptions = new JsonSerializerOptions(JsonSerializerDefaults.Web) {
    PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower,
    Converters = { new JsonStringEnumConverter(JsonNamingPolicy.SnakeCaseLower) }
};

// use SchemaDefaults.OpenAi to enforce OpenAi rule set:
var options = new JsonSchemaOptions(SchemaDefaults.OpenAi, jsonOptions);

var resolver = new DefaultSchemaGenerator();
var schema = resolver.Generate<Document>(options);

var json = schema.ToJsonNode().ToJsonString(new JsonSerializerOptions() { WriteIndented = true });
output.WriteLine(json);
Assert.NotNull(json);

string response = ChatCompletionWithStructuredOutput(messages: [...], model: "...", schema: schema.ToJsonNode());
Assert.StartsWith("""{"id":""", response);

// deserialize with JsonOptions used for schema generation:
var result = JsonSerializer.Deserialize<Document>(response, jsonOptions);
Assert.NotNull(result);
Assert.NotNull(result.Name);

// Model definition with descriptions to include in schema:

[Description("A document")]
public record Document(
    [property: Description("Id of the document")] int Id,
    [property: Description("Document name")] string Name,
    [property: Description("Text lines of the document")] Line[] Lines,
    [property: Description("Next document in order")] Document? Next,
    [property: Description("Prev document in order")] Document? Prev
);

[Description("A line of text in a document")]
public record Line(
    [property: Description("Line number")] int Number,
    [property: Description("Line text")] string Text
);