Schematist JSON Schema DSL for Ruby

Schematist provides a Rails-inspired DSL for defining JSON Schema (Draft 2020-12) in Ruby. You can define schemas using three different patterns: Class Inheritance, a Factory Method, or a Global Helper.

Class Inheritance

Inherit from Schematist::Schema to define a schema class.

Factory Method

Use Schematist::Schema.create to define a schema using a block.

Global Helper

Include Schematist::Helpers to use the schema method directly.

# Class Inheritance
class PersonSchema < Schematist::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 = Schematist::Schema.create do
  string :name
  number :age
end

# Global Helper
require 'schematist'
include Schematist::Helpers

person_schema = schema "PersonData", description: "A person object" do
  string :name
  number :age
end

Schema Definitions

You can use define to create reusable sub-schemas within a class or define block. Definitions can be any schema type.

References

To reuse schemas, you can:

• Use the of: option in arrays or objects.
• Use the reference: option in objects.
• Use the reference method inside an object block.
• Reference the root schema using reference: :root.

Nested Schemas

You can embed existing Schematist::Schema classes directly within objects or arrays for composition.

class MySchema < Schematist::Schema
  define :location do
    string :latitude
    string :longitude
  end

  array :coordinates, of: :location
  object :home_location, reference: :location

  object :user do
    reference :location
  end

  object :ui_schema do
    string :element, enum: ["input", "button"]
    string :label
    object :sub_schema, reference: :root
  end
end

# Embedding classes
class PersonSchema < Schematist::Schema
  string :name
  integer :age
end

class CompanySchema < Schematist::Schema
  object :ceo, of: PersonSchema
  array :employees, of: PersonSchema
  object :founder do
    PersonSchema.new
  end
end

A schema is a collection of properties. Every property requires a name and can optionally include a description and a required flag (which defaults to true).

Annotations

Annotations provide metadata for humans and tools (like title, description, default, examples, deprecated, read_only, and write_only) but do not affect validation.

• Short annotations: Passed as keyword arguments to the property method.
• Long annotations: Defined inside a block to annotate the enclosing schema (e.g., an object).

If the same annotation is provided both as a keyword and inside a block, the keyword argument takes precedence.

string :name, description: "Person's full name"
number :age, description: "Person's age", required: false
boolean :is_active, description: "Whether the person is active"
null :placeholder, description: "A placeholder property"

# Annotations as keywords
string :email, 
  title: "Email address", 
  description: "Primary contact email", 
  default: "user@example.com", 
  examples: ["alice@example.com"]

# Annotations in a block (annotating the object)
object :account do
  title "Account"
  description "Billing account metadata used for invoices."
  examples [{ id: "acct_123", status: "active" }]

  string :id
  string :status
end

If you are upgrading from the deprecated ruby_llm-schema gem to schematist, follow these steps:

1. Update Gemfile: Replace gem 'ruby_llm-schema' with gem 'schematist'.
2. Update Class Inheritance: Change RubyLLM::Schema to Schematist::Schema.
3. Update Helpers: Change include RubyLLM::Helpers to include Schematist::Helpers.
4. Update Error Names: RubyLLM::Schema::ValidationError is now Schematist::ValidationError.
5. Handle strict flag: The strict option has been removed from the schema object. You must now set this flag manually when building your provider request (e.g., in an OpenAI response_format payload).

# Gemfile
gem 'schematist'                      # was: gem 'ruby_llm-schema'

# Schema Definition
class PersonSchema < Schematist::Schema   # was: RubyLLM::Schema
end

# Using Helpers
include Schematist::Helpers               # was: RubyLLM::Helpers

RubyLLM tools can use Schematist schemas to define their expected parameters. This allows you to reuse argument shapes across different tools or parts of your application.

There are two ways to define parameters in a RubyLLM::Tool:

1. Shared Schema: Pass a Schematist schema class to the parameters method.
2. Inline Schema: Use a block with parameters do ... end to define the schema directly within the tool class.

# Using a shared schema class
class SearchParams < Schematist::Schema
  string :query, description: "Search query"
  integer :limit, required: false, description: "Maximum results"
end

class SearchDocuments < RubyLLM::Tool
  description "Searches internal documents"
  parameters SearchParams

  def execute(query:, limit: 10)
    DocumentSearch.call(query:, limit:)
  end
end

# Using an inline schema block
class Weather < RubyLLM::Tool
  description "Gets current weather"

  parameters do
    string :city, description: "City name"
    string :units, enum: %w[celsius fahrenheit], required: false
  end

  def execute(city:, units: "celsius")
    WeatherAPI.current(city:, units:)
  end
end

When using a block with a schema builder (like object_schema or array_schema), the block yields a context that allows you to declare nested schemas and set keywords.

Schema Block Yields

1. Nested Schemas: Declared using type methods (e.g., string, integer).
2. Keywords: Set on the enclosing node (e.g., contains, content_schema).
3. Annotations: Metadata that describes the schema.

Precedence

Annotations set inside a block are treated as defaults. Explicit options passed to the builder method or keyword annotations passed as arguments will override them.

Special Block Methods

• contains(min: nil, max: nil, &block): Defines the contains keyword for arrays.
• any_schema: Injects a true schema (accepts everything).
• no_schema: Injects a false schema (accepts nothing).
• raw(schema): Injects a raw schema object.
• content_schema(&block): Sets the contentSchema keyword.