schematist 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c43b42ba7351bde161abfd42fb394278baec7dc8207fba7a46fa73e7d3f455e0
-  data.tar.gz: 82a99d0c2c5c0facb2b3e8d44fbd3b99241d2294fc3f049f726b84c68bd37ef6
+  metadata.gz: 2acb271d17c754d0d444729086bc552a07c3bb3fd2e66af289bde8d9d5db5b22
+  data.tar.gz: 4469284644cddf477d91afee10b70960673546c3ad11e0b7554f0b5b09f4e5ef
 SHA512:
-  metadata.gz: c0a01457f987bdaead9aaa0143a1fc7ed1a3650929f3a546638bf27743b0501014b6e2563127dea7550d234275019a45e318d3cf3bd10f0cf0781f6f62916357
-  data.tar.gz: a7147cf4e9d7c9f78a602e98e2aef7f8607f7cae735a45777a59ad25d32e3cb172feff4da2848133fcdcb8cade91e02bb31fd2895d54bf3caa0e679474260ca4
+  metadata.gz: e4c561f755bf2d2a0b33a144817239f585aaad38f7274149597e8a3a129021a8ec1a41606ad51469509152c32210596031b7edfe108a00946d493b30e244566b
+  data.tar.gz: eb97a91efb9754f9fa0d652273a340e5cb8048f45f8b9271ee2537e5196372d3e3d13432ada2615b684fe78aa02b957ee58bb165a10f6f2c7d0c7a3f5e4e7695

data/README.md

@@ -5,7 +5,9 @@
 [![codecov](https://codecov.io/gh/crmne/schematist/branch/main/graph/badge.svg)](https://codecov.io/gh/crmne/schematist)
 [![Ruby Style Guide](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop/rubocop)
 
-A Ruby DSL for creating JSON schemas with a clean, Rails-inspired API.
+A general purpose JSON Schema DSL for Ruby with a clean, Rails-inspired API. Emits Draft 2020-12 schemas and depends on nothing.
+
+**Formerly `RubyLLM::Schema`.** Trapping a general purpose JSON Schema DSL inside another gem's namespace was a disservice to anyone looking for one, so 1.0 gave it its own name. See [Migrating from ruby_llm-schema](#migrating-from-ruby_llm-schema).
 
 Originally created by [Daniel Friis](https://github.com/danielfriis).
 
@@ -69,9 +71,9 @@ chat     = RubyLLM.chat
 response = chat.with_schema(PersonSchema)
                .ask("Generate a person named Alice who is 30 years old and lives in New York")
 
-# The response is automatically parsed from JSON
-puts response.content # => {"name" => "Alice", "age" => 30}
-puts response.content.class # => Hash
+# Content stays the raw JSON string, and #parsed gives you the Hash
+puts response.content # => "{\"name\":\"Alice\",\"age\":30}"
+puts response.parsed  # => {"name" => "Alice", "age" => 30}
 ```
 
 ### RubyLLM tools
@@ -85,8 +87,8 @@ class SearchParams < Schematist::Schema
 end
 
 class SearchDocuments < RubyLLM::Tool
-  desc "Searches internal documents"
-  params SearchParams
+  description "Searches internal documents"
+  parameters SearchParams
 
   def execute(query:, limit: 10)
     DocumentSearch.call(query:, limit:)
@@ -94,13 +96,13 @@ class SearchDocuments < RubyLLM::Tool
 end
 ```
 
-For tool-specific parameters, define the schema inline with `params do ... end`.
+For tool-specific arguments, define the schema inline with `parameters do ... end`.
 
 ```ruby
 class Weather < RubyLLM::Tool
-  desc "Gets current weather"
+  description "Gets current weather"
 
-  params do
+  parameters do
     string :city, description: "City name"
     string :units, enum: %w[celsius fahrenheit], required: false
   end
@@ -300,6 +302,7 @@ Number and integer types support the following properties:
 
 - `enum`: an array of allowed numeric values (e.g. `enum: [0, 1, 2]`)
 - `const`: the single allowed value (e.g. `const: 1`)
+- `format`: a format string (e.g. `format: "int64"`)
 - `multiple_of`: a multiple of the number (e.g. `multiple_of: 0.01`)
 - `minimum`: the minimum value of the number (e.g. `minimum: 0`)
 - `maximum`: the maximum value of the number (e.g. `maximum: 100`)
@@ -318,17 +321,19 @@ integer :level, enum: [0, 1, 2]
 ```ruby
 boolean :is_active
 boolean :accepted_terms, const: true
+boolean :flag, enum: [true]
 ```
 
-Boolean types only support `const`, the single allowed value.
+Booleans support `const` and `enum`.
 
 ### Null
 
 ```ruby
 null :placeholder
+null :nothing, enum: [nil]
 ```
 
-Null types doesn't support any additional properties.
+Nulls support `enum`.
 
 ### Arrays
 
@@ -361,7 +366,7 @@ end
 
 ### Tuples
 
-A tuple is a fixed-length array where each position has its own schema. It emits `prefixItems` along with matching `minItems` and `maxItems`.
+A tuple is an array where each position has its own schema. It emits `prefixItems`, and by default it is exactly as long as its prefix.
 
 ```ruby
 tuple :coordinates do
@@ -370,6 +375,20 @@ tuple :coordinates do
 end
 ```
 
+Give it somewhere for the rest to go and it stops being fixed length. `of:` types the tail, `unevaluated_items:` closes it off after the prefix, and an explicit `max_items:` sets its own bound.
+
+```ruby
+tuple :event, of: :string do        # prefixItems, then strings
+  string
+  integer
+end
+
+tuple :pair, unevaluated_items: false do
+  string
+  string
+end
+```
+
 ### Objects
 
 Objects types expect a block with the properties of the object.
@@ -482,7 +501,7 @@ array :values, of: :integer, unevaluated_items: false
 
 ### Runtime Values
 
-Any schema value can be a proc, resolved when the schema is rendered. That lets one schema class produce different documents per instance — useful when an enum comes from the database.
+Any schema value can be a proc, resolved when the schema is rendered. One schema class then produces a different document per instance, which is what you want when an enum comes from the database.
 
 ```ruby
 class RoleSchema < Schematist::Schema
@@ -523,6 +542,50 @@ any_of :value do
 end
 ```
 
+### Schemas That Aren't Objects
+
+A type with a name declares a property. Without a name it declares what the schema itself is. That is how a root, or a definition, becomes something other than an object.
+
+```ruby
+class Tags < Schematist::Schema
+  array of: :string, unique: true      # the whole schema is an array
+end
+
+class Id < Schematist::Schema
+  one_of do                            # the whole schema is a choice
+    string
+    integer
+  end
+end
+
+class Person < Schematist::Schema
+  raw({ "$ref" => "https://example.com/person.json" })
+end
+```
+
+The same rule applies inside `define`, so a definition can be any schema:
+
+```ruby
+define :status do
+  string enum: %w[draft sent]          # a reusable string
+end
+
+define :address do
+  string :street                       # named, so an object with properties
+end
+```
+
+Objects also take their keywords at the root:
+
+```ruby
+class Metadata < Schematist::Schema
+  string :name
+  min_properties 1
+  max_properties 10
+  unevaluated_properties false
+end
+```
+
 ### Schema Definitions and References
 
 You can define sub-schemas and reference them in other schemas, or reference the root schema to generate recursive schemas.
@@ -657,7 +720,7 @@ class PaymentSchema < Schematist::Schema
 end
 ```
 
-Use a `dependent` block when you also need validations — this upgrades the output to `dependentSchemas`:
+Use a `dependent` block when you also need validations. This upgrades the output to `dependentSchemas`:
 
 ```ruby
 dependent :credit_card do
@@ -703,6 +766,32 @@ end
 
 Conditions propagate through nested schemas via `of:`.
 
+A branch is a schema, so anything you can write in a schema you can write in a branch. `requires` and `validates` stay as shorthands for the two common cases.
+
+```ruby
+given kind: "business" do
+  requires :vat_id
+
+  object :tax_details do
+    string :vat_number
+  end
+
+  array :filings, of: :string
+
+  otherwise do
+    validates :vat_id, type: :string
+  end
+end
+```
+
+`given` matches on property values. Pass a schema explicitly when the condition is something else:
+
+```ruby
+given({ required: %w[tax_id] }) do
+  requires :summary
+end
+```
+
 ## JSON Output
 
 `to_json_schema` returns a Draft 2020-12 JSON Schema document with string keys, ready to hand to any JSON Schema validator.
@@ -722,13 +811,11 @@ schema.to_json_schema
 puts schema.to_json  # Pretty JSON string of the same document
 ```
 
-The schema name maps to `title`. Provider-only keys are not part of the document — `strict` was an OpenAI `response_format` flag, not a JSON Schema keyword, and has been removed. Set it where you build the request.
+The schema name maps to `title`. Provider-only keys are not part of the document. `strict` was an OpenAI `response_format` flag rather than a JSON Schema keyword, so it has been removed. Set it where you build the request.
 
 ### Migrating from ruby_llm-schema
 
-Schematist was called `ruby_llm-schema`. The old name put a general-purpose JSON Schema DSL inside another gem's namespace and implied it only made sense alongside an LLM client, which was never true.
-
-Update the gem, then the constants:
+`RubyLLM::Schema` is now `Schematist`. Update the gem, then the constants:
 
 ```ruby
 gem 'schematist'                      # was: gem 'ruby_llm-schema'
@@ -739,13 +826,13 @@ end
 include Schematist::Helpers               # was: RubyLLM::Helpers
 ```
 
-Errors moved up a level with the rename — `Schematist::ValidationError`, not `RubyLLM::Schema::ValidationError`. `strict` is gone; see below.
+Errors moved up a level with the rename: `Schematist::ValidationError`, not `RubyLLM::Schema::ValidationError`. `strict` is gone; see below.
 
 ### Migrating from the provider envelope
 
-`to_json_schema` used to return a provider envelope — `{name:, description:, schema:, strict:}`, the shape OpenAI's `response_format` expects. That envelope is gone. Building it is the provider client's job, not this gem's.
+`to_json_schema` returns the schema document itself. It used to return `{name:, description:, schema:, strict:}`, the shape OpenAI's `response_format` expects, and building that belongs in whatever talks to the provider.
 
-If you were reaching into `[:schema]` to get at the document, drop the digging — `to_json_schema` now returns the document itself. Note its keys are strings, not symbols:
+If you were reaching into `[:schema]` to get at the document, drop the digging. Note the keys are strings, not symbols:
 
 ```ruby
 schema.to_json_schema[:schema][:properties]   # before

data/lib/schematist/dsl/complex_types.rb

@@ -3,37 +3,39 @@
 module Schematist
   module DSL
     module ComplexTypes
-      def object(name, description: nil, required: true, requires: nil, **options, &block)
-        add_property(name, object_schema(description: description, **options, &block), required: required, requires: requires)
+      def object(name = nil, description: nil, required: true, requires: nil, **options, &block)
+        add_property_or_self(name, object_schema(description: description, **options, &block), required: required, requires: requires)
       end
 
-      def array(name, description: nil, required: true, requires: nil, **options, &block)
-        add_property(name, array_schema(description: description, **options, &block), required: required, requires: requires)
+      def array(name = nil, description: nil, required: true, requires: nil, **options, &block)
+        add_property_or_self(name, array_schema(description: description, **options, &block), required: required, requires: requires)
       end
 
-      def tuple(name, description: nil, required: true, requires: nil, **options, &block)
-        add_property(name, tuple_schema(description: description, **options, &block), required: required, requires: requires)
+      def tuple(name = nil, description: nil, required: true, requires: nil, **options, &block)
+        add_property_or_self(name, tuple_schema(description: description, **options, &block), required: required, requires: requires)
       end
 
-      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)
+      def any_of(name = nil, description: nil, required: true, requires: nil, **options, &block)
+        add_property_or_self(name, any_of_schema(description: description, **options, &block), required: required, requires: requires)
       end
 
-      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)
+      def one_of(name = nil, description: nil, required: true, requires: nil, **options, &block)
+        add_property_or_self(name, one_of_schema(description: description, **options, &block), required: required, requires: requires)
       end
 
-      def all_of(name, description: nil, required: true, requires: nil, **options, &block)
-        add_property(name, all_of_schema(description: description, **options, &block), required: required, requires: requires)
+      def all_of(name = nil, description: nil, required: true, requires: nil, **options, &block)
+        add_property_or_self(name, all_of_schema(description: description, **options, &block), required: required, requires: requires)
       end
 
-      def none_of(name, description: nil, required: true, requires: nil, **options, &block)
-        add_property(name, none_of_schema(description: description, **options, &block), required: required, requires: requires)
+      def none_of(name = nil, description: nil, required: true, requires: nil, **options, &block)
+        add_property_or_self(name, none_of_schema(description: description, **options, &block), required: required, requires: requires)
       end
 
       # Emits a schema fragment verbatim, for the corners of JSON Schema this DSL does not cover
-      def raw(name, schema, required: true, requires: nil)
-        add_property(name, schema, required: required, requires: requires)
+      def raw(name, schema = nil, required: true, requires: nil)
+        return self_schema(name) && nil if schema.nil? && name.is_a?(Hash)
+
+        add_property_or_self(name, schema, required: required, requires: requires)
       end
 
       def optional(name, description: nil, &block)

data/lib/schematist/dsl/conditional_builder.rb

@@ -2,11 +2,10 @@
 
 module Schematist
   module DSL
+    # A branch of a conditional. Backed by a schema class, so anything you can write in a schema
+    # you can write in a branch: nested objects, arrays, composition, references, raw fragments.
+    # `requires` and `validates` stay as shorthands for the two common cases.
     class ConditionalBuilder
-      def requires(*fields)
-        required.concat(fields.map(&:to_s))
-      end
-
       VALIDATES_KEY_MAP = {
         type: :type,
         const: :const,
@@ -19,6 +18,15 @@ module Schematist
         maximum: :maximum
       }.freeze
 
+      def initialize
+        @schema_class = Class.new(Schema)
+      end
+
+      # Requires properties without saying anything else about them
+      def requires(*fields)
+        required.concat(fields.map(&:to_s))
+      end
+
       def validates(field, **options)
         constraints = {}
 
@@ -38,28 +46,56 @@ module Schematist
       end
 
       def to_schema
-        schema = {}
+        return @schema_class.self_schema.dup if @schema_class.self_schema
 
-        schema[:required] = required if required.any?
-        schema[:properties] = validations if validations.any?
+        schema = {}
+        schema[:properties] = branch_properties if branch_properties.any?
+        schema[:required] = branch_required if branch_required.any?
+        schema[:additionalProperties] = @schema_class.additional_properties if additional_properties_set?
 
-        schema
+        @schema_class.send(:merge_schema_keywords, schema, @schema_class)
       end
 
       def empty?
-        required.empty? && validations.empty?
+        to_schema.empty?
       end
 
       def required_fields
-        required.dup
+        branch_required
       end
 
+      # A branch that only lists required properties becomes dependentRequired rather than
+      # dependentSchemas, which is the smaller thing to say when it is all you mean.
       def validations_empty?
-        validations.empty?
+        to_schema.keys == [:required]
+      end
+
+      # Everything else is the ordinary schema DSL, evaluated against the branch's schema class
+      def method_missing(name, ...)
+        return super unless @schema_class.respond_to?(name)
+
+        @schema_class.public_send(name, ...)
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @schema_class.respond_to?(name) || super
       end
 
       private
 
+      def branch_properties
+        declared = @schema_class.properties.transform_keys(&:to_s)
+        validations.merge(declared)
+      end
+
+      def branch_required
+        (@schema_class.required_properties.map(&:to_s) + required).uniq
+      end
+
+      def additional_properties_set?
+        @schema_class.instance_variable_defined?(:@additional_properties)
+      end
+
       def required
         @required ||= []
       end

data/lib/schematist/dsl/conditional_context.rb

@@ -8,16 +8,19 @@ module Schematist
         @else_builder = else_builder
       end
 
-      def requires(*fields)
-        @then_builder.requires(*fields)
+      def otherwise(&block)
+        @else_builder.instance_eval(&block)
       end
 
-      def validates(field, **options)
-        @then_builder.validates(field, **options)
+      # Everything else describes the then branch
+      def method_missing(name, ...)
+        return super unless @then_builder.respond_to?(name)
+
+        @then_builder.public_send(name, ...)
       end
 
-      def otherwise(&block)
-        @else_builder.instance_eval(&block)
+      def respond_to_missing?(name, include_private = false)
+        @then_builder.respond_to?(name) || super
       end
     end
   end

data/lib/schematist/dsl/conditionals.rb

@@ -18,10 +18,13 @@ module Schematist
         dependencies[property.to_s] = builder
       end
 
-      def given(**properties, &block)
-        raise ArgumentError, "given requires at least one property condition" if properties.empty?
+      # Matches on property values, or on any schema when one is passed explicitly:
+      #   given(status: "shipped") { ... }
+      #   given({required: %w[tax_id]}) { ... }
+      def given(condition = nil, **properties, &block)
+        raise ArgumentError, "given requires a condition" if condition.nil? && properties.empty?
 
-        if_schema = {
+        if_schema = condition || {
           properties: properties.transform_keys(&:to_s).transform_values { |v| coerce_condition(v) },
           required: properties.keys.map(&:to_s)
         }

data/lib/schematist/dsl/primitive_types.rb

@@ -3,24 +3,24 @@
 module Schematist
   module DSL
     module PrimitiveTypes
-      def string(name, description: nil, required: true, requires: nil, **options, &block)
-        add_property(name, string_schema(description: description, **options, &block), required: required, requires: requires)
+      def string(name = nil, description: nil, required: true, requires: nil, **options, &block)
+        add_property_or_self(name, string_schema(description: description, **options, &block), required: required, requires: requires)
       end
 
-      def number(name, description: nil, required: true, requires: nil, **options, &block)
-        add_property(name, number_schema(description: description, **options, &block), required: required, requires: requires)
+      def number(name = nil, description: nil, required: true, requires: nil, **options, &block)
+        add_property_or_self(name, number_schema(description: description, **options, &block), required: required, requires: requires)
       end
 
-      def integer(name, description: nil, required: true, requires: nil, **options, &block)
-        add_property(name, integer_schema(description: description, **options, &block), required: required, requires: requires)
+      def integer(name = nil, description: nil, required: true, requires: nil, **options, &block)
+        add_property_or_self(name, integer_schema(description: description, **options, &block), required: required, requires: requires)
       end
 
-      def boolean(name, description: nil, required: true, requires: nil, **options, &block)
-        add_property(name, boolean_schema(description: description, **options, &block), required: required, requires: requires)
+      def boolean(name = nil, description: nil, required: true, requires: nil, **options, &block)
+        add_property_or_self(name, boolean_schema(description: description, **options, &block), required: required, requires: requires)
       end
 
-      def null(name, description: nil, required: true, requires: nil, **options, &block)
-        add_property(name, null_schema(description: description, **options, &block), required: required, requires: requires)
+      def null(name = nil, description: nil, required: true, requires: nil, **options, &block)
+        add_property_or_self(name, null_schema(description: description, **options, &block), required: required, requires: requires)
       end
     end
   end

data/lib/schematist/dsl/schema_builders.rb

@@ -23,12 +23,13 @@ module Schematist
         }.compact, annotations, schema_block)
       end
 
-      def number_schema(description: nil, minimum: nil, maximum: nil, greater_than: nil, less_than: nil, multiple_of: nil, enum: nil, const: nil, **annotations, &block)
+      def number_schema(description: nil, minimum: nil, maximum: nil, greater_than: nil, less_than: nil, multiple_of: nil, enum: nil, const: nil, format: nil, **annotations, &block)
         schema_block = collect_schema_block(&block) if block
 
         annotate({
           type: "number",
           description: description,
+          format: format,
           minimum: minimum,
           maximum: maximum,
           exclusiveMinimum: greater_than,
@@ -39,12 +40,13 @@ module Schematist
         }.compact, annotations, schema_block)
       end
 
-      def integer_schema(description: nil, minimum: nil, maximum: nil, greater_than: nil, less_than: nil, multiple_of: nil, enum: nil, const: nil, **annotations, &block)
+      def integer_schema(description: nil, minimum: nil, maximum: nil, greater_than: nil, less_than: nil, multiple_of: nil, enum: nil, const: nil, format: nil, **annotations, &block)
         schema_block = collect_schema_block(&block) if block
 
         annotate({
           type: "integer",
           description: description,
+          format: format,
           minimum: minimum,
           maximum: maximum,
           exclusiveMinimum: greater_than,
@@ -55,16 +57,16 @@ module Schematist
         }.compact, annotations, schema_block)
       end
 
-      def boolean_schema(description: nil, const: nil, **annotations, &block)
+      def boolean_schema(description: nil, enum: nil, const: nil, **annotations, &block)
         schema_block = collect_schema_block(&block) if block
 
-        annotate({type: "boolean", description: description, const: const}.compact, annotations, schema_block)
+        annotate({type: "boolean", description: description, enum: enum, const: const}.compact, annotations, schema_block)
       end
 
-      def null_schema(description: nil, **annotations, &block)
+      def null_schema(description: nil, enum: nil, **annotations, &block)
         schema_block = collect_schema_block(&block) if block
 
-        annotate({type: "null", description: description}.compact, annotations, schema_block)
+        annotate({type: "null", description: description, enum: enum}.compact, annotations, schema_block)
       end
 
       def object_schema(description: nil, of: nil, reference: nil, min_properties: nil, max_properties: nil, unevaluated_properties: nil, **annotations, &block)
@@ -96,57 +98,67 @@ module Schematist
         }.compact, annotations, schema_block)
       end
 
-      def tuple_schema(description: nil, **annotations, &block)
+      def tuple_schema(description: nil, of: nil, min_items: nil, max_items: nil, unevaluated_items: nil, **annotations, &block)
         schema_block = collect_schema_block(&block)
         schemas = schema_block.schemas
+        tail = determine_array_items(of) if of
+
+        # A tuple is exactly its prefix unless you give it somewhere for the rest to go
+        closed = tail.nil? && unevaluated_items.nil? && max_items.nil?
 
         annotate({
           type: "array",
           description: description,
           prefixItems: schemas,
-          minItems: schemas.length,
-          maxItems: schemas.length
+          items: tail,
+          minItems: min_items || schemas.length,
+          maxItems: closed ? schemas.length : max_items,
+          unevaluatedItems: unevaluated_items
         }.compact, annotations, schema_block)
       end
 
-      def any_of_schema(description: nil, unevaluated_properties: nil, **annotations, &block)
+      def any_of_schema(description: nil, unevaluated_properties: nil, unevaluated_items: nil, **annotations, &block)
         schema_block = collect_schema_block(&block)
 
         annotate({
           description: description,
           anyOf: schema_block.schemas,
-          unevaluatedProperties: unevaluated_properties
+          unevaluatedProperties: unevaluated_properties,
+          unevaluatedItems: unevaluated_items
         }.compact, annotations, schema_block)
       end
 
-      def one_of_schema(description: nil, unevaluated_properties: nil, **annotations, &block)
+      def one_of_schema(description: nil, unevaluated_properties: nil, unevaluated_items: nil, **annotations, &block)
         schema_block = collect_schema_block(&block)
 
         annotate({
           description: description,
           oneOf: schema_block.schemas,
-          unevaluatedProperties: unevaluated_properties
+          unevaluatedProperties: unevaluated_properties,
+          unevaluatedItems: unevaluated_items
         }.compact, annotations, schema_block)
       end
 
-      def all_of_schema(description: nil, unevaluated_properties: nil, **annotations, &block)
+      def all_of_schema(description: nil, unevaluated_properties: nil, unevaluated_items: nil, **annotations, &block)
         schema_block = collect_schema_block(&block)
 
         annotate({
           description: description,
           allOf: schema_block.schemas,
-          unevaluatedProperties: unevaluated_properties
+          unevaluatedProperties: unevaluated_properties,
+          unevaluatedItems: unevaluated_items
         }.compact, annotations, schema_block)
       end
 
-      def none_of_schema(description: nil, unevaluated_properties: nil, **annotations, &block)
+      def none_of_schema(description: nil, unevaluated_properties: nil, unevaluated_items: nil, **annotations, &block)
         schema_block = collect_schema_block(&block)
         schemas = schema_block.schemas
 
         annotate({
           description: description,
           not: schemas.size == 1 ? schemas.first : {anyOf: schemas},
-          unevaluatedProperties: unevaluated_properties
+          unevaluatedProperties: unevaluated_properties,
+          unevaluatedItems: unevaluated_items
         }.compact, annotations, schema_block)
       end
 
@@ -162,6 +174,8 @@ module Schematist
       end
 
       def build_object_schema(description, &block)
+        raise InvalidObjectTypeError, "An object needs a block or an `of:` schema to describe it." unless block
+
         sub_schema = Class.new(Schema)
         result = sub_schema.class_eval(&block)
 
@@ -173,15 +187,10 @@ module Schematist
           schema_class_to_inline_schema(result).merge(description ? {description: description} : {})
         # Block didn't return reference or schema, so we build an inline object schema
         else
-          schema = {
-            type: "object",
-            properties: sub_schema.properties,
-            required: sub_schema.required_properties,
-            additionalProperties: sub_schema.additional_properties,
-            description: description
-          }.compact
-
-          merge_schema_keywords(schema, sub_schema)
+          schema = schema_for(sub_schema)
+          # The keyword wins over an annotation set inside the block
+          schema[:description] = description if description
+          schema
         end
       end
 

data/lib/schematist/dsl/utilities.rb

@@ -8,16 +8,7 @@ module Schematist
         sub_schema = Class.new(Schema)
         sub_schema.class_eval(&)
 
-        schema = {
-          type: "object",
-          properties: sub_schema.properties,
-          required: sub_schema.required_properties,
-          additionalProperties: sub_schema.additional_properties
-        }
-
-        merge_schema_keywords(schema, sub_schema)
-
-        definitions[name] = schema
+        definitions[name] = schema_for(sub_schema)
       end
 
       def object_keywords
@@ -47,6 +38,26 @@ module Schematist
 
       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.

data/lib/schematist/json_output.rb

@@ -27,18 +27,11 @@ module Schematist
     private
 
     def schema_body
-      schema_hash = {
-        type: "object",
-        properties: self.class.properties,
-        required: self.class.required_properties,
-        additionalProperties: self.class.additional_properties
-      }
+      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?
 
-      self.class.send(:merge_schema_keywords, schema_hash, self.class)
-
       schema_hash
     end
 

data/lib/schematist/schema.rb

@@ -91,6 +91,29 @@ module Schematist
         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?
 
@@ -109,6 +132,12 @@ module Schematist
 
       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

data/lib/schematist/validator.rb

@@ -49,15 +49,10 @@ module Schematist
       # Mark node with temporary mark
       marks[node] = GRAY
 
-      # Visit all adjacent nodes (dependencies)
-      definition = definitions[node]
-      if definition && definition[:properties]
-        definition[:properties].each_value do |property|
-          references = extract_references(property)
-          references.each do |adjacent_node|
-            visit(adjacent_node, definitions, marks)
-          end
-        end
+      # 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

data/lib/schematist/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: schematist
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Daniel Friis