RubyLLM::Schema

A Ruby DSL for creating JSON schemas with a clean, Rails-inspired API. Perfect for defining structured data schemas for LLM function calling or structured outputs.

Simple Example

class PersonSchema < RubyLLM::Schema
  string :name, description: "Person's full name"
  number :age, description: "Age in years"
  boolean :active, required: false
  
  object :address do
    string :street
    string :city
    string :country, required: false
  end
  
  array :tags, of: :string, description: "User tags"
  
  array :contacts do
    object do
      string :email
      string :phone, required: false
    end
  end
  
  any_of :status do
    string enum: ["active", "pending", "inactive"]
    null
  end
end

# Usage
schema = PersonSchema.new
puts schema.to_json

Installation

Add this line to your application's Gemfile:

gem 'ruby_llm-schema'

And then execute:

bundle install

Or install it yourself as:

gem install ruby_llm-schema

Usage

Three approaches for creating schemas:

Class Inheritance

class PersonSchema < RubyLLM::Schema
  string :name, description: "Person's full name"
  number :age
  boolean :active, required: false
  
  object :address do
    string :street
    string :city
  end
  
  array :tags, of: :string
end

schema = PersonSchema.new
puts schema.to_json

Factory Method

PersonSchema = RubyLLM::Schema.create do
  string :name, description: "Person's full name"
  number :age
  boolean :active, required: false
  
  object :address do
    string :street
    string :city
  end
  
  array :tags, of: :string
end

schema = PersonSchema.new
puts schema.to_json

Global Helper

require 'ruby_llm/schema'
include RubyLLM::Helpers

person_schema = schema "PersonData", description: "A person object" do
  string :name, description: "Person's full name"
  number :age
  boolean :active, required: false
  
  object :address do
    string :street
    string :city
  end
  
  array :tags, of: :string
end

puts person_schema.to_json

Field Types

Primitive Types

string :name                          # Required string
string :title, required: false        # Optional string
string :status, enum: ["on", "off"]   # String with enum values
number :count                         # Required number
integer :id                           # Required integer
boolean :active                       # Required boolean
null :placeholder                     # Null type

Arrays

array :tags, of: :string              # Array of strings
array :scores, of: :number            # Array of numbers

array :items do                       # Array of objects
  object do
    string :name
    number :price
  end
end

Objects

object :user do
  string :name
  number :age
end

object :settings, description: "User preferences" do
  boolean :notifications
  string :theme, enum: ["light", "dark"]
end

Union Types (anyOf)

any_of :value do
  string
  number  
  null
end

any_of :identifier do
  string description: "Username"
  number description: "User ID"
end

Schema Definitions and References

class MySchema < RubyLLM::Schema
  define :location do
    string :latitude
    string :longitude
  end
  
  array :coordinates, of: :location
  
  object :home_location do
    reference :location
  end
end

JSON Output

schema = PersonSchema.new
schema.to_json_schema
# => {
#   name: "PersonSchema",
#   description: nil,
#   schema: {
#     type: "object",
#     properties: { ... },
#     required: [...],
#     additionalProperties: false,
#     strict: true
#   }
# }

puts schema.to_json  # Pretty JSON string

License

The gem is available as open source under the terms of the MIT License.