Add support for JSON Schema $defs, definitions, $ref, oneOf, anyOf and others in PropertyDefinition

[repko-artem]

This PR extends PropertyDefinition to support additional JSON Schema draft-07 elements:

• $defs (for schema definitions)
• definitions (old draft-07 keyword)
• $ref (schema references)
• anyOf (combining subschemas)
• oneOf (choosing a schema)
• const (constant value)
• min and max (range for possible values)
• title (the same as description, but shorter)
• some others related to https://platform.openai.com/docs/guides/structured-outputs?api-mode=chat&type-restrictions=number-restrictions#supported-properties

Also support array-like type of property to support optional props https://platform.openai.com/docs/guides/structured-outputs#all-fields-must-be-required like

"type": ["string", "null"]

These additions improve compatibility with more complex JSON Schema structures.

[repko-artem]

@dotnet-policy-service agree

[repko-artem]

This pull request introduces significant enhancements to JSON serialization and schema validation functionality in the OpenAI.SDK project. The changes include adding a custom JSON converter for handling single values or arrays, extending schema validation support with new properties, and improving the flexibility of the FunctionParameters model.

JSON Serialization Enhancements:

• Added a SingleOrArrayToListConverter class to handle JSON properties that can be either a single string or an array of strings, converting them to a list of strings for consistency.

Schema Validation Enhancements:

• Updated the FunctionParameters model to support additional schema validation properties, such as multipleOf, minimum, maximum, exclusiveMinimum, exclusiveMaximum, pattern, format, minItems, and maxItems, aligning with the JSON Schema 2020-12 specification.
• Added support for schema structuring and referencing with new properties like $defs, definitions, $ref, anyOf, and oneOf. These additions enable more complex and reusable schema definitions.

Model Improvements:

• Refactored the Type property in the FunctionParameters model to work with either a single string or a list of strings (TypeList), ensuring flexibility while maintaining backward compatibility. This allowed to support not-required properties in JSON schemas.
• Added a Constant property to represent the const keyword in JSON Schema, allowing validation against a fixed value.

Minor Adjustments:

• Removed an unnecessary BOM marker from the FunctionParameters.cs file.

[Copilot]

Pull Request Overview

This PR enhances JSON Schema support in PropertyDefinition by adding draft-07 elements, combining schema constructs, and improving type handling.

• Introduces TypeList with a custom converter for single-or-array "type" values.
• Adds JSON Schema keywords: const, numeric bounds (minimum, maximum, etc.), format, pattern, minItems/maxItems, $defs, definitions, $ref, anyOf, oneOf, and related documentation.
• Updates converter logic in Converters.cs to parse/serialize string or array types.

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
OpenAI.SDK/ObjectModels/SharedModels/FunctionParameters.cs	Added new schema-related properties and replaced default type handling with TypeList/Type.
OpenAI.SDK/ObjectModels/Converters.cs	Implemented SingleOrArrayToListConverter for JSON (de)serialization of "type" values.

Comments suppressed due to low confidence (3)

OpenAI.SDK/ObjectModels/SharedModels/FunctionParameters.cs:42

• The previous default of type = "object" was removed when replacing the old Type property, which may be a breaking change for clients expecting object by default. Consider initializing TypeList to ["object"] when no type is set or documenting this behavior clearly.

    public IList<string?>? TypeList { get; set; }

OpenAI.SDK/ObjectModels/Converters.cs:94

• This converter contains nontrivial logic for both reading and writing single values or arrays. Please add unit tests covering string, array, and null cases to ensure correct (de)serialization behavior.

public class SingleOrArrayToListConverter : JsonConverter<IList<string?>>

OpenAI.SDK/ObjectModels/SharedModels/FunctionParameters.cs:204

• New properties like anyOf and oneOf add conditional schema logic. Consider adding tests that serialize and deserialize scenarios with multiple subschemas to validate these fields.

    [JsonPropertyName("anyOf")]