Enhance JSONSchema documentation and visibility of types

[1amageek]

Description:

This pull request introduces the following improvements to the JSONSchema class:

1. Detailed Documentation:

   • Added comprehensive comments to the JSONSchema class and its components.
   • Describes features, usage, and the supported schema types.

2. Public Accessors:

   • Made the SchemaType enum public, enabling external access to supported schema types.
   • Added public properties type and description for the JSONSchema class, providing external visibility to the schema's type and description.

3. Enhanced Enum Definition:

   • Updated SchemaType with support for Codable and Sendable.

Changes:

• Improved documentation for JSONSchema and SchemaType:

  /// A class that represents a JSON Schema definition.
  ///
  /// `JSONSchema` is a flexible representation of a JSON Schema. It supports multiple schema types,
  /// including arrays, booleans, enums, integers, nulls, numbers, objects, and strings. The schema
  /// includes detailed metadata and type-specific information.
  ///
  /// ## Features
  /// - Supports various schema types.
  /// - Provides detailed descriptions for schema elements.
  /// - Implements `Codable` and `Sendable` for serialization and concurrency safety.
  public final class JSONSchema: Codable, Sendable {
      /// Enumeration of the supported JSON Schema types.
      public enum SchemaType: String, Codable, Sendable {
          case array
          case boolean
          case `enum`
          case string
      }
  
      /// The type of the schema.
      public let type: SchemaType
  
      /// An optional description providing additional information about the schema.
      public let description: String?
  }

[1amageek]

@kevinhermawan hi.

Background:
The current issue is that there is no de facto standard for defining JSONSchema. Each vendor uses a different approach, which is far from ideal. In my opinion, JSONSchema should be more flexible to accommodate these differences.

Current Problem:
As it stands, I need to write additional conversion code to map JSONSchema to each vendor's specific Schema. For example, consider Google's definition:

public class Schema {
  /// The data type.
  let type: DataType

  /// The format of the data.
  let format: String?

  /// A brief description of the parameter.
  let description: String?

  /// Indicates if the value may be null.
  let nullable: Bool?

  /// Possible values of the element of type ``DataType/string`` with "enum" format.
  let enumValues: [String]?

  /// Schema of the elements of type ``DataType/array``.
  let items: Schema?

  /// Properties of type ``DataType/object``.
  let properties: [String: Schema]?

  /// Required properties of type ``DataType/object``.
  let requiredProperties: [String]?
}

func convertJSONSchema(_ schema: JSONSchema) throws -> GoogleGenerativeAI.Schema {
    let type = convertSchemaType(schema.type)
    
    var properties: [String: GoogleGenerativeAI.Schema]?
    var items: GoogleGenerativeAI.Schema?
    var enumValues: [String]?
    
    // convert

In the current JSONSchema implementation, the necessary variables are defined as private, making direct mapping difficult and necessitating conversion. Note that this issue is not exclusive to Google—other vendors also have varied definitions, which poses a barrier to unified conversion.

Proposal:
By changing the access level of the variables in JSONSchema to public, it becomes possible to convert JSONSchema into each vendor’s Schema. This adjustment does not eliminate redundancy but allows for proper schema transformation across different implementations.