schematist 0.1.0 → 1.1.0

data/lib/schematist/dsl/utilities.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Schematist
+  module DSL
+    module Utilities
+      # Schema definition and reference methods
+      def define(name, &)
+        sub_schema = Class.new(Schema)
+        sub_schema.class_eval(&)
+
+        definitions[name] = schema_for(sub_schema)
+      end
+
+      def object_keywords
+        @object_keywords ||= {}
+      end
+
+      # Constrains the names of properties matching a pattern, as JSON Schema patternProperties
+      def keys_matching(pattern, &block)
+        pattern = pattern.source if pattern.is_a?(Regexp)
+
+        object_keywords[:patternProperties] ||= {}
+        object_keywords[:patternProperties][pattern] = collect_schemas_from_block(&block).first
+      end
+
+      # Constrains every property name, as JSON Schema propertyNames
+      def keys(&block)
+        object_keywords[:propertyNames] = collect_schemas_from_block(&block).first
+      end
+
+      def reference(schema_name)
+        if schema_name == :root
+          {"$ref" => "#"}
+        else
+          {"$ref" => "#/$defs/#{schema_name}"}
+        end
+      end
+
+      private
+
+      # What a schema class means as a schema: whatever it declared itself to be, or an object
+      # built from its properties.
+      def schema_for(schema_class)
+        schema = schema_class.self_schema&.dup || {
+          type: "object",
+          properties: schema_class.properties,
+          required: schema_class.required_properties,
+          additionalProperties: schema_class.additional_properties
+        }
+
+        merge_schema_keywords(schema, schema_class)
+      end
+
+      # Declares a property when given a name, and what this schema is when not.
+      def add_property_or_self(name, definition, required:, requires: nil)
+        return self_schema(definition) && nil if name.nil?
+
+        add_property(name, definition, required: required, requires: requires)
+      end
+
+      # Merges everything a schema class collects beyond its properties: annotations, core keywords,
+      # key constraints, conditionals. Annotations are defaults, so an option passed to the enclosing
+      # builder wins over them.
+      def merge_schema_keywords(schema, schema_class)
+        schema.replace(schema_class.annotations.merge(schema))
+        schema.merge!(schema_class.core_keywords)
+        schema.merge!(schema_class.object_keywords)
+        merge_conditions(schema, schema_class)
+      end
+
+      def add_property(name, definition, required:, requires: nil)
+        property_name = name.to_sym
+
+        properties[property_name] = definition
+        if required
+          required_properties << property_name unless required_properties.include?(property_name)
+        else
+          required_properties.delete(property_name)
+        end
+
+        if requires
+          builder = ConditionalBuilder.new
+          builder.requires(*Array(requires))
+          dependencies[name.to_s] = builder
+        end
+
+        nil
+      end
+
+      def primitive_type?(type)
+        type.is_a?(Symbol) && PRIMITIVE_TYPES.include?(type)
+      end
+
+      def schema_class?(type)
+        (type.is_a?(Class) && type < Schema) || type.is_a?(Schema)
+      end
+    end
+  end
+end

data/lib/schematist/dsl.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Schematist
+  module DSL
+    include SchemaBuilders
+    include PrimitiveTypes
+    include ComplexTypes
+    include Conditionals
+    include Utilities
+  end
+end

data/lib/schematist/errors.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Schematist
+  # Base error class for all schema-related errors
+  class Error < StandardError; end
+
+  # Raised when an invalid schema type is specified
+  class InvalidSchemaTypeError < Error
+    def initialize(type)
+      super("Unknown schema type: #{type}")
+    end
+  end
+
+  # Raised when an invalid array type is specified
+  class InvalidArrayTypeError < Error; end
+
+  # Raised when an invalid object type is specified
+  class InvalidObjectTypeError < Error; end
+
+  # Raised when schema definition is invalid
+  class InvalidSchemaError < Error; end
+
+  # Raised when schema validation fails
+  class ValidationError < Error; end
+
+  # Raised when maximum limits are exceeded
+  class LimitExceededError < Error; end
+end

data/lib/schematist/helpers.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Schematist
+  module Helpers
+    def schema(name = nil, description: nil, &block)
+      schema_class = Schema.create(&block)
+      schema_class.new(name, description: description)
+    end
+  end
+end

data/lib/schematist/json_output.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Schematist
+  module JsonOutput
+    DRAFT_2020_12 = "https://json-schema.org/draft/2020-12/schema"
+
+    # A Draft 2020-12 JSON Schema document, string-keyed and ready for any JSON Schema validator
+    def to_json_schema
+      validate! # Validate schema before generating JSON
+
+      document = schema_body
+      class_description = document.delete(:description)
+      header = {
+        "$schema" => DRAFT_2020_12,
+        title: document.delete(:title) || @name,
+        description: @description || class_description
+      }.compact
+
+      json_compatible(resolve_runtime_values(header.merge(document)))
+    end
+
+    def to_json(*_args)
+      validate! # Validate schema before generating JSON string
+      JSON.pretty_generate(to_json_schema)
+    end
+
+    private
+
+    def schema_body
+      schema_hash = self.class.send(:schema_for, self.class)
+
+      # Only include $defs if there are definitions
+      schema_hash["$defs"] = self.class.definitions unless self.class.definitions.empty?
+
+      schema_hash
+    end
+
+    # JSON Schema documents are string-keyed. Symbols survive a Ruby comparison but not a JSON round trip.
+    def json_compatible(value)
+      case value
+      when Hash
+        value.to_h { |key, nested_value| [key.to_s, json_compatible(nested_value)] }
+      when Array
+        value.map { |nested_value| json_compatible(nested_value) }
+      when Symbol
+        value.to_s
+      else
+        value
+      end
+    end
+
+    # Values declared as procs are resolved here, so one schema class can render differently per instance
+    def resolve_runtime_values(value)
+      case value
+      when Proc
+        resolve_runtime_values(value.arity.zero? ? instance_exec(&value) : value.call(self))
+      when Hash
+        value.transform_values { |nested_value| resolve_runtime_values(nested_value) }
+      when Array
+        value.map { |nested_value| resolve_runtime_values(nested_value) }
+      else
+        value
+      end
+    end
+  end
+end

data/lib/schematist/schema.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module Schematist
+  class Schema
+    extend DSL
+    include JsonOutput
+
+    class << self
+      def create(&block)
+        schema_class = Class.new(Schema)
+        schema_class.class_eval(&block)
+        schema_class
+      end
+
+      def properties
+        @properties ||= {}
+      end
+
+      def required_properties
+        @required_properties ||= []
+      end
+
+      def definitions
+        @definitions ||= {}
+      end
+
+      def name(name = nil)
+        @schema_name = name if name
+        return @schema_name if defined?(@schema_name)
+
+        super()
+      end
+
+      def annotations
+        @annotations ||= {}
+      end
+
+      def title(*args)
+        annotation(:title, *args)
+      end
+
+      def description(*args)
+        annotation(:description, *args)
+      end
+
+      def default(*args)
+        annotation(:default, *args)
+      end
+
+      def examples(*args)
+        annotation(:examples, *args)
+      end
+
+      def deprecated(*args)
+        annotation(:deprecated, *args)
+      end
+
+      def read_only(*args)
+        annotation(:read_only, *args)
+      end
+
+      def write_only(*args)
+        annotation(:write_only, *args)
+      end
+
+      def core_keywords
+        @core_keywords ||= {}
+      end
+
+      def id(*args)
+        core_keyword(:id, *args)
+      end
+
+      def anchor(*args)
+        core_keyword(:anchor, *args)
+      end
+
+      def comment(*args)
+        core_keyword(:comment, *args)
+      end
+
+      def dynamic_anchor(*args)
+        core_keyword(:dynamic_anchor, *args)
+      end
+
+      def dynamic_ref(*args)
+        core_keyword(:dynamic_ref, *args)
+      end
+
+      def vocabulary(*args)
+        core_keyword(:vocabulary, *args)
+      end
+
+      # The schema this class is, when it is not an object built from properties. Set by
+      # calling a type without a name: `string enum: %w[a b]` rather than `string :status`.
+      def self_schema(definition = nil)
+        @self_schema = definition if definition
+        @self_schema
+      end
+
+      def min_properties(value = nil)
+        object_keyword(:minProperties, value)
+      end
+
+      def max_properties(value = nil)
+        object_keyword(:maxProperties, value)
+      end
+
+      def unevaluated_properties(value = nil)
+        object_keyword(:unevaluatedProperties, value)
+      end
+
+      def unevaluated_items(value = nil)
+        object_keyword(:unevaluatedItems, value)
+      end
+
+      def additional_properties(value = nil)
+        return @additional_properties ||= false if value.nil?
+
+        @additional_properties = value
+      end
+
+      def validate!
+        validator = Validator.new(self)
+        validator.validate!
+      end
+
+      def valid?
+        validator = Validator.new(self)
+        validator.valid?
+      end
+
+      private
+
+      def object_keyword(keyword, value)
+        return object_keywords[keyword] if value.nil?
+
+        object_keywords[keyword] = value
+      end
+
+      def annotation(name, *args)
+        read_or_write(annotations, ANNOTATIONS.fetch(name), *args)
+      end
+
+      def core_keyword(name, *args)
+        read_or_write(core_keywords, CORE_KEYWORDS.fetch(name), *args)
+      end
+
+      def read_or_write(store, keyword, *args)
+        return store[keyword] if args.empty?
+
+        store[keyword] = args.first
+      end
+    end
+
+    def initialize(name = nil, description: nil)
+      @name = name || self.class.name || "Schema"
+      @description = description
+    end
+
+    def validate!
+      self.class.validate!
+    end
+
+    def valid?
+      self.class.valid?
+    end
+
+    def method_missing(method_name, ...)
+      if respond_to_missing?(method_name)
+        self.class.send(method_name, ...)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      %i[string number integer boolean array tuple object any_of one_of all_of none_of raw null].include?(method_name) || super
+    end
+  end
+end

data/lib/schematist/validator.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Schematist
+  class Validator
+    # Node states for DFS-based topological sort
+    WHITE = :white  # No mark (unvisited)
+    GRAY = :gray    # Temporary mark (currently being processed)
+    BLACK = :black  # Permanent mark (completely processed)
+
+    def initialize(schema_class)
+      @schema_class = schema_class
+    end
+
+    def validate!
+      validate_circular_references!
+      # Future validations can be added here
+    end
+
+    def valid?
+      validate!
+      true
+    rescue ValidationError
+      false
+    end
+
+    private
+
+    def validate_circular_references!
+      definitions = @schema_class.definitions
+      return if definitions.empty?
+
+      # Initialize all nodes as WHITE (no mark)
+      marks = Hash.new { WHITE }
+
+      # Visit each unmarked node
+      definitions.each_key do |node|
+        visit(node, definitions, marks) if marks[node] == WHITE
+      end
+    end
+
+    # DFS visit function
+    def visit(node, definitions, marks)
+      # If node has a permanent mark, return
+      return if marks[node] == BLACK
+
+      # If node has a temporary mark, we found a cycle
+      raise ValidationError, "Circular reference detected involving '#{node}'" if marks[node] == GRAY
+
+      # Mark node with temporary mark
+      marks[node] = GRAY
+
+      # Visit all adjacent nodes (dependencies). A definition is any schema, not only an
+      # object with properties, so the whole thing is searched for references.
+      extract_references(definitions[node]).each do |adjacent_node|
+        visit(adjacent_node, definitions, marks)
+      end
+
+      # Mark node with permanent mark
+      marks[node] = BLACK
+    end
+
+    def extract_references(property)
+      references = []
+
+      case property
+      when Hash
+        if property["$ref"]
+          # Extract definition name from reference like "#/$defs/user"
+          ref_name = property["$ref"].split("/").last&.to_sym
+          references << ref_name if ref_name
+        else
+          # Recursively check nested properties
+          property.each_value do |value|
+            references.concat(extract_references(value))
+          end
+        end
+      when Array
+        property.each do |item|
+          references.concat(extract_references(item))
+        end
+      end
+
+      references
+    end
+  end
+end

data/lib/schematist/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Schematist
-  VERSION = '0.1.0'
+  VERSION = '1.1.0'
 end

data/lib/schematist.rb

@@ -1,4 +1,46 @@
 # frozen_string_literal: true
 
-require_relative 'schematist/version'
-require 'ruby_llm/schema'
+require "json"
+
+require_relative "schematist/version"
+require_relative "schematist/errors"
+
+module Schematist
+  PRIMITIVE_TYPES = %i[string number integer boolean null].freeze
+
+  # Annotations describe a schema for humans and tools. They carry no validation weight.
+  ANNOTATIONS = {
+    title: :title,
+    description: :description,
+    default: :default,
+    examples: :examples,
+    deprecated: :deprecated,
+    read_only: :readOnly,
+    write_only: :writeOnly
+  }.freeze
+
+  # Core keywords identify a schema and point at other schemas.
+  CORE_KEYWORDS = {
+    id: "$id",
+    anchor: "$anchor",
+    comment: "$comment",
+    dynamic_anchor: "$dynamicAnchor",
+    dynamic_ref: "$dynamicRef",
+    vocabulary: "$vocabulary"
+  }.freeze
+end
+
+# Every file defines the constant its path implies. The DSL modules come before dsl.rb,
+# which includes them, and the DSL before schema.rb, which extends it.
+require_relative "schematist/dsl/schema_builders"
+require_relative "schematist/dsl/primitive_types"
+require_relative "schematist/dsl/complex_types"
+require_relative "schematist/dsl/conditional_builder"
+require_relative "schematist/dsl/conditional_context"
+require_relative "schematist/dsl/conditionals"
+require_relative "schematist/dsl/utilities"
+require_relative "schematist/dsl"
+require_relative "schematist/json_output"
+require_relative "schematist/validator"
+require_relative "schematist/helpers"
+require_relative "schematist/schema"

data/lib/tasks/release.rake

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+namespace :release do
+  desc 'Prepare for release'
+  task :prepare do
+    sh 'overcommit --run'
+  end
+end

metadata

@@ -1,32 +1,19 @@
 --- !ruby/object:Gem::Specification
 name: schematist
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.1.0
 platform: ruby
 authors:
+- Daniel Friis
 - Carmine Paolino
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: ruby_llm-schema
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-description: Schematist is the next home of ruby_llm-schema. Installing schematist
-  installs ruby_llm-schema and requiring schematist loads it. The expanded JSON Schema
-  (draft 2020-12) toolkit lands here in a future release.
+dependencies: []
+description: A compact Ruby DSL for building standards-oriented JSON Schema documents
+  from Ruby.
 email:
+- d@friis.me
 - carmine@paolino.me
 executables: []
 extensions: []
@@ -35,13 +22,29 @@ files:
 - LICENSE
 - README.md
 - lib/schematist.rb
+- lib/schematist/dsl.rb
+- lib/schematist/dsl/complex_types.rb
+- lib/schematist/dsl/conditional_builder.rb
+- lib/schematist/dsl/conditional_context.rb
+- lib/schematist/dsl/conditionals.rb
+- lib/schematist/dsl/primitive_types.rb
+- lib/schematist/dsl/schema_builders.rb
+- lib/schematist/dsl/utilities.rb
+- lib/schematist/errors.rb
+- lib/schematist/helpers.rb
+- lib/schematist/json_output.rb
+- lib/schematist/schema.rb
+- lib/schematist/validator.rb
 - lib/schematist/version.rb
-homepage: https://github.com/crmne/ruby_llm-schema
+- lib/tasks/release.rake
+homepage: https://github.com/crmne/schematist#readme
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/crmne/ruby_llm-schema
-  source_code_uri: https://github.com/crmne/ruby_llm-schema
+  homepage_uri: https://github.com/crmne/schematist#readme
+  source_code_uri: https://github.com/crmne/schematist
+  changelog_uri: https://github.com/crmne/schematist/releases
+  bug_tracker_uri: https://github.com/crmne/schematist/issues
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -59,5 +62,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.16
 specification_version: 4
-summary: A Ruby DSL for building JSON Schema documents.
+summary: A simple Ruby DSL for creating JSON schemas.
 test_files: []