ask-schema 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f5a9c41e5de3b5e4c3bdaad787059efa89197dc88048cb24b4f545a34adfd060
+  data.tar.gz: 2f3dc5d00239bf5364ffd0894feb138a060cca73359310aee1b576ac2f6a77bb
+SHA512:
+  metadata.gz: e05cfa19bd6d8160fb98c14b46a39dd5cc69970dacd1e571cb813c27b1f73454d73ce7bf74dfaa7e14ad1399ec0fd3f93bfe193aaf4e0939f6ccae59beeb0636
+  data.tar.gz: bc91c29e8bcea693ed199cccea34a6581f4289b2ddf1420634fc1b0b32e7828b591a7bc1addc28cd028a99fbd888b2e5ebf5e6a97a432e7985ac88b67e16ee4f

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaka Ruto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,350 @@
+# ask-schema
+
+A compact Ruby DSL for building standards-compliant JSON Schema documents. Zero dependencies.
+
+```ruby
+gem "ask-schema"
+```
+
+```ruby
+require "ask-schema"
+
+schema = Ask::Schema.create do
+  string :name, description: "Full name"
+  integer :age, description: "Age in years", minimum: 0
+  boolean :active, required: false
+end
+
+schema.new("user", description: "A user profile").to_json
+# => {
+#   "name": "user",
+#   "description": "A user profile",
+#   "schema": {
+#     "type": "object",
+#     "properties": {
+#       "name": { "type": "string", "description": "Full name" },
+#       "age": { "type": "integer", "description": "Age in years", "minimum": 0 },
+#       "active": { "type": "boolean" }
+#     },
+#     "required": ["name", "age"],
+#     "additionalProperties": false,
+#     "strict": true
+#   }
+# }
+```
+
+## Quick Start
+
+### Block-based DSL
+
+```ruby
+schema = Ask::Schema.create do
+  string :name, description: "The user's name"
+  integer :age, description: "Age in years"
+  boolean :active, required: false
+end
+
+instance = schema.new("user_profile", description: "A user profile")
+instance.to_json_schema
+# => { name: "user_profile", description: "A user profile", schema: { ... } }
+```
+
+### Class-based DSL
+
+```ruby
+class Address < Ask::Schema
+  string :street
+  string :city
+  string :zip
+  string :country, required: false
+end
+
+class User < Ask::Schema
+  string :name, description: "Full name"
+  string :email, format: "email"
+  integer :age
+  object :address, of: Address
+end
+
+User.new("user").to_json_schema
+```
+
+## Primitive Types
+
+Each primitive type supports standard JSON Schema constraints.
+
+### String
+
+```ruby
+string :username,
+  description: "Username",
+  enum: %w[admin user guest],
+  min_length: 3,
+  max_length: 50,
+  pattern: "^[a-zA-Z0-9_]+$",
+  format: "email"
+```
+
+### Number
+
+```ruby
+number :price,
+  description: "Price in USD",
+  minimum: 0,
+  maximum: 999999.99,
+  multiple_of: 0.01
+```
+
+### Integer
+
+```ruby
+integer :age,
+  minimum: 0,
+  maximum: 150
+```
+
+### Boolean
+
+```ruby
+boolean :active, description: "Is the user active?"
+```
+
+### Null
+
+```ruby
+null :deleted_at, description: "When the record was deleted"
+```
+
+## Complex Types
+
+### Object
+
+```ruby
+# Inline object
+object :address do
+  string :street
+  string :city
+  string :zip
+end
+
+# Reference to a defined schema
+define(:address) do
+  string :street
+  string :city
+end
+object :billing, of: :address
+
+# Reference to a Schema class
+object :shipping, of: Address
+```
+
+### Array
+
+```ruby
+# Array of primitive type
+array :tags, of: :string, description: "List of tags"
+
+# Array with min/max items
+array :prices, of: :number, min_items: 1, max_items: 100
+
+# Array with complex items (block)
+array :contacts do
+  object do
+    string :name
+    string :email
+  end
+end
+
+# Array with any_of items
+array :identifiers do
+  any_of do
+    string
+    integer
+  end
+end
+```
+
+### any_of / one_of
+
+```ruby
+any_of :contact do
+  string description: "Phone number"
+  object do
+    string :email
+  end
+end
+
+one_of :payment_method do
+  string :credit_card
+  string :paypal
+end
+```
+
+### Optional (nullable)
+
+```ruby
+optional :nickname do
+  string
+end
+# Produces: anyOf: [{ type: "string" }, { type: "null" }]
+```
+
+## Named Definitions and References
+
+Use `define` to create reusable named sub-schemas and `reference` (or `of:`) to reference them:
+
+```ruby
+class User < Ask::Schema
+  define(:address) do
+    string :street
+    string :city
+    string :zip
+  end
+
+  string :name
+  object :home_address, of: :address
+  object :work_address, of: :address
+end
+```
+
+Output includes proper `$defs` and `$ref`:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "name": { "type": "string" },
+    "home_address": { "$ref": "#/$defs/address" },
+    "work_address": { "$ref": "#/$defs/address" }
+  },
+  "$defs": {
+    "address": {
+      "type": "object",
+      "properties": { "street": { "type": "string" }, ... }
+    }
+  }
+}
+```
+
+## Conditionals
+
+### If/Then/Else
+
+```ruby
+schema = Ask::Schema.create do
+  integer :age
+  string :country
+
+  given(age: 18, country: "US") do
+    requires :license_number
+    validates :license_number, type: :string, pattern: /^[A-Z]{2}\d{6}$/
+    otherwise do
+      requires :country_name
+    end
+  end
+end
+```
+
+### Dependent Required
+
+```ruby
+dependent :shipping_address do
+  requires :name, :street, :city
+end
+```
+
+### Coercion rules
+
+| Ruby value | JSON Schema |
+|---|---|
+| `18` (scalar) | `{ const: 18 }` |
+| `["admin", "user"]` (Array) | `{ enum: ["admin", "user"] }` |
+| `/^[A-Z]+$/` (Regexp) | `{ pattern: "^[A-Z]+$" }` |
+| `{ minimum: 0 }` (Hash) | Passed through as-is |
+
+## Validation
+
+```ruby
+schema = Ask::Schema.create { string :name }
+schema.valid? # => true
+schema.validate! # => nil (or raises Ask::Schema::ValidationError)
+
+# Circular reference detection
+schema = Ask::Schema.create do
+  define(:a) { object :b, of: :b }
+  define(:b) { object :a, of: :a }
+end
+schema.valid? # => false
+schema.validate! # => raises Ask::Schema::ValidationError
+```
+
+## Output Formats
+
+```ruby
+instance.to_json_schema
+# => Hash with :name, :description, :schema keys
+
+instance.to_json
+# => Pretty-printed JSON string
+```
+
+## Configuration
+
+```ruby
+class StrictSchema < Ask::Schema
+  string :name
+  strict true              # defaults to true
+  additional_properties false  # defaults to false
+end
+```
+
+## Integration with ask-tools
+
+`ask-schema` powers tool parameter schemas in `ask-tools`:
+
+```ruby
+class WeatherTool < Ask::Tool
+  description "Get weather for a location"
+
+  params do
+    string :location, description: "City name"
+    string :unit, enum: %w[celsius fahrenheit]
+  end
+
+  def execute(location:, unit: "celsius")
+    # ...
+  end
+end
+```
+
+Under the hood, `Ask::Schema.create` is used to build the JSON Schema for tool parameters.
+
+## Error Types
+
+| Error | When |
+|---|---|
+| `Ask::Schema::InvalidArrayTypeError` | Invalid type for array `:of` |
+| `Ask::Schema::InvalidObjectTypeError` | Invalid type for object `:of` |
+| `Ask::Schema::ValidationError` | Schema validation fails (e.g., circular refs) |
+| `Ask::Schema::InvalidSchemaTypeError` | Unknown schema type specified |
+| `Ask::Schema::InvalidSchemaError` | Schema definition is invalid |
+| `Ask::Schema::LimitExceededError` | Maximum limits exceeded |
+
+## Development
+
+```
+bundle install
+bundle exec rake test
+```
+
+## Status
+
+**Phase 3** of the ask-rb ecosystem migration. This gem replaces `ruby_llm-schema`
+in the ask-rb stack. It should be built after `ask-core` and `ask-llm-providers`
+are stable.
+
+Current state: v0.1.0 — initial port complete with full feature parity.
+
+## License
+
+MIT

data/lib/ask/schema/dsl/complex_types.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Ask
+  class Schema
+    module DSL
+      # DSL methods for declaring complex (non-primitive) property types.
+      module ComplexTypes
+        # Declare an object property with inline or referenced sub-schema.
+        # @param name [Symbol] Property name
+        # @param description [String, nil] Property description
+        # @param required [Boolean] Whether the property is required (default: true)
+        # @param requires [Symbol, Array<Symbol>, nil] Dependent property requirements
+        # @param options [Hash] Additional options (of:, reference:)
+        # @param block [Proc] Inline property definitions
+        def object(name, description: nil, required: true, requires: nil, **options, &block)
+          add_property(name, object_schema(description: description, **options, &block), required: required, requires: requires)
+        end
+
+        # Declare an array property.
+        # @param name [Symbol] Property name
+        # @param description [String, nil] Property description
+        # @param required [Boolean] Whether the property is required (default: true)
+        # @param requires [Symbol, Array<Symbol>, nil] Dependent property requirements
+        # @param options [Hash] Additional options (of:, min_items:, max_items:)
+        # @param block [Proc] Block for complex item definitions
+        def array(name, description: nil, required: true, requires: nil, **options, &block)
+          add_property(name, array_schema(description: description, **options, &block), required: required, requires: requires)
+        end
+
+        # Declare a property accepting any of the listed schemas.
+        # @param name [Symbol] Property name
+        # @param description [String, nil] Property description
+        # @param required [Boolean] Whether the property is required (default: true)
+        # @param requires [Symbol, Array<Symbol>, nil] Dependent property requirements
+        # @param options [Hash] Additional options
+        # @param block [Proc] Block listing alternative schemas
+        def any_of(name, description: nil, required: true, requires: nil, **options, &block)
+          add_property(name, any_of_schema(description: description, **options, &block), required: required, requires: requires)
+        end
+
+        # Declare a property accepting exactly one of the listed schemas.
+        # @param name [Symbol] Property name
+        # @param description [String, nil] Property description
+        # @param required [Boolean] Whether the property is required (default: true)
+        # @param requires [Symbol, Array<Symbol>, nil] Dependent property requirements
+        # @param options [Hash] Additional options
+        # @param block [Proc] Block listing alternative schemas
+        def one_of(name, description: nil, required: true, requires: nil, **options, &block)
+          add_property(name, one_of_schema(description: description, **options, &block), required: required, requires: requires)
+        end
+
+        # Declare an optional (nullable) property using +anyOf+ with +null+.
+        #
+        # @example
+        #   optional :nickname do
+        #     string
+        #   end
+        #   # Produces: anyOf: [{ type: "string" }, { type: "null" }]
+        #
+        # @param name [Symbol] Property name
+        # @param description [String, nil] Property description
+        # @param block [Proc] Block defining the non-null type
+        def optional(name, description: nil, &block)
+          any_of(name, description: description) do
+            instance_eval(&block)
+            null
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ask/schema/dsl/conditionals.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+module Ask
+  class Schema
+    module DSL
+      # Conditional schema features: +if/then/else+, +dependentRequired+,
+      # and +dependentSchemas+ for JSON Schema conditional validation.
+      module Conditionals
+        # Collection of conditionals (if/then/else) defined on this schema.
+        # @return [Array<Hash>] The conditions
+        def conditions
+          @conditions ||= []
+        end
+
+        # Collection of dependencies (dependentRequired/dependentSchemas) defined.
+        # @return [Hash{String => ConditionalBuilder}] The dependencies
+        def dependencies
+          @dependencies ||= {}
+        end
+
+        # Declare that a property has dependencies on other properties.
+        #
+        # @example
+        #   dependent :shipping_address do
+        #     requires :name, :street, :city
+        #   end
+        #
+        # @param property [Symbol] The property that has dependencies
+        # @param block [Proc] Block declaring requirements via +requires+ and +validates+
+        def dependent(property, &block)
+          builder = ConditionalBuilder.new
+          builder.instance_eval(&block)
+
+          dependencies[property.to_s] = builder
+        end
+
+        # Declare a conditional (if/then/else) constraint.
+        #
+        # Values are automatically coerced: scalars become +const+, arrays become
+        # +enum+, and Regexps become +pattern+.
+        #
+        # @example
+        #   given(age: 18) do
+        #     requires :license_number
+        #     otherwise do
+        #       requires :guardian_name
+        #     end
+        #   end
+        #
+        # @param properties [Hash{Symbol => Object}] Property conditions
+        # @param block [Proc] Block declaring then/else requirements
+        # @raise [ArgumentError] If no conditions are provided
+        def given(**properties, &block)
+          raise ArgumentError, "given requires at least one property condition" if properties.empty?
+
+          if_schema = {
+            properties: properties.transform_keys(&:to_s).transform_values { |v| coerce_condition(v) },
+            required: properties.keys.map(&:to_s)
+          }
+
+          then_builder = ConditionalBuilder.new
+          else_builder = ConditionalBuilder.new
+
+          context = ConditionalContext.new(then_builder, else_builder)
+          context.instance_eval(&block)
+
+          condition = {if: if_schema, then: then_builder.to_schema}
+          condition[:else] = else_builder.to_schema unless else_builder.empty?
+
+          conditions << condition
+        end
+
+        private
+
+        # Merge any conditions and dependencies from a sub-schema into the schema hash.
+        def merge_conditions(schema, schema_class)
+          if schema_class.respond_to?(:conditions) && schema_class.conditions.any?
+            if schema_class.conditions.length == 1
+              schema.merge!(schema_class.conditions.first)
+            else
+              schema[:allOf] = schema_class.conditions
+            end
+          end
+
+          if schema_class.respond_to?(:dependencies) && schema_class.dependencies.any?
+            dependent_required = {}
+            dependent_schemas = {}
+
+            schema_class.dependencies.each do |property, builder|
+              if builder.validations_empty?
+                dependent_required[property] = builder.required_fields
+              else
+                dependent_schemas[property] = builder.to_schema
+              end
+            end
+
+            schema[:dependentRequired] = dependent_required if dependent_required.any?
+            schema[:dependentSchemas] = dependent_schemas if dependent_schemas.any?
+          end
+
+          schema
+        end
+
+        # Coerce a Ruby value into a JSON Schema condition.
+        # @param value [Object] The condition value
+        # @return [Hash] JSON Schema condition fragment
+        def coerce_condition(value)
+          case value
+          when Array then {enum: value}
+          when Regexp then {pattern: value.source}
+          when Hash then value
+          else {const: value}
+          end
+        end
+      end
+
+      # Execution context for +given+ blocks, providing +requires+, +validates+,
+      # and +otherwise+ DSL methods.
+      class ConditionalContext
+        # @param then_builder [ConditionalBuilder] Builder for the "then" clause
+        # @param else_builder [ConditionalBuilder] Builder for the "else" clause
+        def initialize(then_builder, else_builder)
+          @then_builder = then_builder
+          @else_builder = else_builder
+        end
+
+        # Mark fields as required when the condition is met.
+        # @param fields [Array<Symbol>] Field names to require
+        def requires(*fields)
+          @then_builder.requires(*fields)
+        end
+
+        # Add validation constraints for a field.
+        # @param field [Symbol] Field name
+        # @param options [Hash] Validation constraints
+        # @option options [Symbol] :type Expected JSON type
+        # @option options [Object] :const Expected constant value
+        # @option options [Array] :enum Allowed values
+        # @option options [Object] :not_value Disallowed value (maps to +not+)
+        # @option options [Integer] :min_length Minimum string length
+        # @option options [Integer] :max_length Maximum string length
+        # @option options [String, Regexp] :pattern Regex pattern
+        # @option options [Numeric] :minimum Minimum number
+        # @option options [Numeric] :maximum Maximum number
+        def validates(field, **options)
+          @then_builder.validates(field, **options)
+        end
+
+        # Define the "else" clause for when the condition is not met.
+        # @param block [Proc] Block declaring requirements
+        def otherwise(&block)
+          @else_builder.instance_eval(&block)
+        end
+      end
+
+      # Builder for collecting requirements and validations within a conditional clause.
+      class ConditionalBuilder
+        # Mark fields as required.
+        # @param fields [Array<Symbol, String>] Field names
+        def requires(*fields)
+          required.concat(fields.map(&:to_s))
+        end
+
+        # Map of validated option names to JSON Schema key names.
+        VALIDATES_KEY_MAP = {
+          type: :type,
+          const: :const,
+          enum: :enum,
+          not_value: :not,
+          min_length: :minLength,
+          max_length: :maxLength,
+          pattern: :pattern,
+          minimum: :minimum,
+          maximum: :maximum
+        }.freeze
+
+        # Add validation constraints for a field.
+        #
+        # @param field [Symbol] Field name
+        # @param options [Hash] Validation constraints (see {ConditionalContext#validates})
+        # @raise [ArgumentError] If an unknown option is provided
+        def validates(field, **options)
+          constraints = {}
+
+          options.each do |key, value|
+            schema_key = VALIDATES_KEY_MAP[key]
+            raise ArgumentError, "unknown validates option: #{key.inspect}" unless schema_key
+
+            case key
+            when :type then constraints[:type] = value.to_s
+            when :not_value then constraints[:not] = {const: value}
+            when :pattern then constraints[:pattern] = value.is_a?(Regexp) ? value.source : value
+            else constraints[schema_key] = value
+            end
+          end
+
+          validations[field.to_s] = constraints
+        end
+
+        # Convert to a JSON Schema fragment.
+        # @return [Hash] Schema fragment with +required+ and +properties+
+        def to_schema
+          schema = {}
+
+          schema[:required] = required if required.any?
+          schema[:properties] = validations if validations.any?
+
+          schema
+        end
+
+        # Check if the builder has no requirements or validations.
+        # @return [Boolean]
+        def empty?
+          required.empty? && validations.empty?
+        end
+
+        # Get the required field names (duped).
+        # @return [Array<String>]
+        def required_fields
+          required.dup
+        end
+
+        # Check if no validations have been defined.
+        # @return [Boolean]
+        def validations_empty?
+          validations.empty?
+        end
+
+        private
+
+        # @return [Array<String>] Accumulated required fields
+        def required
+          @required ||= []
+        end
+
+        # @return [Hash{String => Hash}] Accumulated field validations
+        def validations
+          @validations ||= {}
+        end
+      end
+    end
+  end
+end