kochab 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a614b6dc35cf6bb101732526b9679f51fedd2f4b48a39737d7eca3161fcdbc9
-  data.tar.gz: 055f80b9abb6f3e339bd5fb7949f53b0a83f7c542377b255d8a715205e0789c7
+  metadata.gz: 4e0eb6c563c42845bb7442c624883c75f2421a2298d4e721485433c2676a1abe
+  data.tar.gz: 46c35ab8d5de26c434723e04a6b8b6c22241b79346c0f2eef3e121b20dc2ac74
 SHA512:
-  metadata.gz: fa6984ae1709b30cc8b0cfecaf09a52c03e493cc47f5f485f04ad6d084e1a3f452e3150ac09e3717eb111db3af397522560410bfacd4f8c11e22df69aee6b26b
-  data.tar.gz: 524c84d838078662b7881f26f1ded5b5843a40c80a5fd5aea47d7d88c88638f1dbbdbee170f09470daa95c8fc6ba590ad2b837ab66ffc3918aed0ec975a350ed
+  metadata.gz: 2d665d220c79847fc8771f9433196a673be028bb5f171e9e51bc78755d4a0a9e08e5649da38211ecef279dbec50992f10dbf7e8d7f6c6c54ecbfe1857cfdcb17
+  data.tar.gz: 93970f7f6ccf7cff4f8165f9e9fe42ffcd9bef186efed304eb1a1dce40598165c0bf377d740ef14fed456cf7d43f621303b1b93f4c70fbedba1c0ee334a50754

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.2.0 — 2026-09-15
+
+- Add schema DSL, defaults, source-aware validation, and field metadata.
+- Add safe layered merging that retains earlier values when later values are invalid.
+- Add a JSON Schema subset importer.
+
 ## 0.1.0 — 2026-09-11
 
 - Initial release.

data/README.md

@@ -1,26 +1,66 @@
-# Kochab
+<h1 align="center">Kochab</h1>
+
+<p align="center">
+  <strong>JSONC parsing with byte ranges, error recovery, and formatting-preserving edits</strong>
+</p>
+
+<p align="center">
+  <a href="https://rubygems.org/gems/kochab"><img src="https://img.shields.io/gem/v/kochab.svg?colorB=319e8c" alt="Gem Version"></a>
+  <a href="https://rubygems.org/gems/kochab"><img src="https://img.shields.io/gem/dt/kochab.svg" alt="Downloads"></a>
+  <a href="https://github.com/noxdea/kochab/actions/workflows/main.yml"><img src="https://github.com/noxdea/kochab/actions/workflows/main.yml/badge.svg" alt="CI"></a>
+  <img src="https://img.shields.io/badge/ruby-%3E%3D%203.1-CC342D.svg" alt="Ruby 3.1+">
+  <a href="LICENSE.txt"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
+</p>
+
+<p align="center">
+  <a href="#features">Features</a> ·
+  <a href="#installation">Installation</a> ·
+  <a href="#quick-start">Quick Start</a> ·
+  <a href="#source-queries">Source Queries</a> ·
+  <a href="#schemas">Schemas</a> ·
+  <a href="#editing">Editing</a> ·
+  <a href="#development">Development</a>
+</p>
+
+---
+
+Kochab is a pure Ruby JSONC parser that retains exact source locations. It
+recovers from syntax errors and produces minimal text edits that preserve
+surrounding comments and formatting.
+
+## Features
+
+- JSONC parsing with comments and trailing commas
+- UTF-8 byte ranges, syntax tree queries, and UTF-16 position conversion
+- Error recovery with structured diagnostics and a strict JSON mode
+- Minimal insert, replace, and remove edits that preserve unrelated source text
+- Comment-preserving formatting
+- Typed settings schemas with source-aware diagnostics and safe layer merging
+- RBS signatures with no runtime gem dependencies
 
-JSONC parsing with byte ranges, error recovery, and edits that preserve the
-surrounding comments and formatting. Ruby 3.1+, no runtime gem dependencies,
-no custom native extension. Ruby's standard `json` library handles string
-escapes and value serialization; scanning, recovery, and edits are Ruby code.
+## Installation
 
-Kochab are annotations written in a manuscript's margins. `gloss` and `glossa`
-were registered on RubyGems; `kochab` was available when checked on
-2026-09-09. Availability is not a reservation. This checkout is not published.
+Add Kochab to your Gemfile:
 
-## Installation
+```ruby
+gem "kochab"
+```
+
+Then install:
+
+```sh
+bundle install
+```
 
-From this checkout:
+Or install it directly:
 
 ```sh
-gem build kochab.gemspec
-gem install ./kochab-0.1.0.gem
+gem install kochab
 ```
 
-Or use `gem "kochab", path: "/path/to/checkout"` in your Gemfile.
+Kochab requires Ruby 3.1 or later.
 
-## Parse and update a setting
+## Quick Start
 
 ```ruby
 require "kochab"
@@ -73,7 +113,67 @@ Property nodes have one value child; a missing value is a zero-length `:null`
 node. Containers' `value` fields contain their Ruby Hash or Array values.
 Treat the tree and its values as read-only snapshots. `doc.text` is frozen.
 
-## Recovery and strict mode
+## Schemas
+
+Define settings metadata once and use it for defaults, validation, layer
+merging, and settings UI generation:
+
+```ruby
+schema = Kochab::Schema.define do
+  boolean "format_on_save", default: false,
+    description: "Run the formatter when saving"
+  integer "font_size", default: 14, minimum: 6, maximum: 96
+  enum "theme", values: %w[auto light dark], default: "auto"
+  object "minimap" do
+    boolean "enabled", default: false
+    integer "width", default: 100, minimum: 20, maximum: 400
+  end
+  array "code_actions_on_save", items: :string, default: []
+  map "languages", value: ->(language) {
+    language.integer "tab_size", default: 2, minimum: 1
+  }
+end
+
+schema.defaults
+# {"format_on_save"=>false, "font_size"=>14, "theme"=>"auto",
+#  "minimap"=>{"enabled"=>false, "width"=>100},
+#  "code_actions_on_save"=>[]}
+
+document = Kochab.parse('{"font_size": 4, "theme": "blue"}')
+diagnostics = schema.validate(document)
+diagnostics.first.path                         # ["font_size"]
+document.text.byteslice(diagnostics.first.range) # "4"
+
+field = schema.describe(["minimap", "width"])
+field.type                                    # :integer
+schema.fields                                 # all metadata in definition order
+```
+
+Schema paths are arrays, like `Document` paths. Map metadata uses `"*"` in
+`Field#path`; `describe` accepts a concrete map key. Diagnostics have `path`,
+byte `range`, `severity` (`:error`), and `message`. Syntax diagnostics remain
+in `Document#errors`.
+
+`merge` starts with schema defaults and applies documents or Hash layers from
+left to right. Objects merge recursively and arrays replace earlier arrays.
+An invalid value is skipped at its own key, leaving the earlier valid value
+active; unrelated valid values in the same layer still apply. Fields not
+declared by the DSL are retained, which permits extension-owned settings.
+
+```ruby
+user = Kochab.parse('{"font_size": 18, "minimap": {"width": 120}}')
+project = Kochab.parse('{"font_size": "large", "minimap": {"enabled": true}}')
+values = schema.merge(user, project)
+values["font_size"]                    # 18; invalid project value was skipped
+values["minimap"]                      # {"enabled"=>true, "width"=>120}
+```
+
+`Schema.from_json_schema(hash)` imports the settings-oriented JSON Schema
+subset: local references, object properties, required names, array items,
+additional properties, primitive and nullable types, defaults, descriptions,
+deprecation, enums, numeric bounds, and collection/string size bounds.
+
+## Parsing and Recovery
 
 The default parser consumes the complete input and reports syntax problems in
 `doc.errors`, including invalid UTF-8. It returns the best available value:
@@ -115,7 +215,7 @@ value's `trailing_comment`. Comments separated by a blank line, and additional
 comments that cannot occupy the single trailing slot, are `floating_comments`.
 Comment text always retains its original delimiters and bytes.
 
-## Minimal edits
+## Editing
 
 ```ruby
 doc.set(["editor", "font_size"], 14)                 # replace one value
@@ -157,7 +257,7 @@ the first newline style present in the input, and appends one final newline.
 rejects invalid documents to avoid discarding incomplete input. Use minimal
 edits when existing whitespace must be preserved exactly.
 
-## Validation and performance
+## Development
 
 ```sh
 bundle install
@@ -177,6 +277,8 @@ outcome for `i_` cases. Valid inputs are also checked against `JSON.parse`.
 Recovery/fuzz tests check termination, source preservation, and bounded ranges.
 Edit tests check exact replacement bytes and preservation of unrelated comments.
 
+## Performance
+
 Measured on macOS arm64, Ruby 4.0.0 with YJIT (2026-09-09), seven-sample medians:
 
 | Operation | Observed | Budget |
@@ -185,6 +287,8 @@ Measured on macOS arm64, Ruby 4.0.0 with YJIT (2026-09-09), seven-sample medians
 | Parse 1,048,594-byte JSONC | 157.5 ms | 200 ms |
 | Query `node_at` | < 1 µs | 10 µs |
 | Generate a `set` edit | 2 µs | 1 ms |
+| Validate a small schema document | 1 µs | 1 ms |
+| Merge a small schema document | 2 µs | 1 ms |
 
 The corpus contains nested settings, UTF-8 strings, and one comment per setting.
 Run `bench/benchmark.rb` on your deployment machine; these are measurements,
@@ -197,6 +301,13 @@ CI tests Ruby 3.1, 3.2, 3.3, 3.4, and 4.0 on Linux, macOS, and Windows. Performa
 budgets run separately on Linux with Ruby 4.0 and YJIT. Built-gem installation
 and the example are smoke-tested in CI.
 
+## Contributing
+
+Bug reports and pull requests are welcome on
+[GitHub](https://github.com/noxdea/kochab).
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+
 ## License
 
 MIT; see [LICENSE.txt](LICENSE.txt). Vendored test data retains its original

data/lib/kochab/schema/builder.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Kochab
+  class Schema
+    # Definition context for Schema.define.
+    class Builder
+      def initialize(path = [])
+        @path = path
+        @rules = []
+      end
+
+      attr_reader :rules
+
+      def boolean(name, **options) = scalar(name, :boolean, **options)
+      def integer(name, **options) = scalar(name, :integer, **options)
+      def number(name, **options) = scalar(name, :number, **options)
+      def string(name, **options) = scalar(name, :string, **options)
+
+      def enum(name, values:, **options)
+        raise ArgumentError, "values must be a nonempty Array" unless values.is_a?(Array) && !values.empty?
+
+        types = values.map { |value| Schema.type_of(value) }.uniq
+        scalar(name, types.one? ? types.first : :any, enum: values, **options)
+      end
+
+      def object(name, **options, &block)
+        nested = self.class.new(field_path(name))
+        evaluate(nested, block)
+        add(name, :object, items: nested.rules.map(&:field).freeze, children: nested.rules, **options)
+      end
+
+      def array(name, items:, **options)
+        item = Schema.rule_for_type(items, field_path(name) + [0])
+        add(name, :array, items: Schema.public_item(item), item: item, **options)
+      end
+
+      def map(name, value:, **options)
+        path = field_path(name) + ["*"]
+        item = if value.respond_to?(:call)
+          nested = self.class.new(path)
+          value.call(nested)
+          Schema.rule(nil, :object, children: nested.rules)
+        else
+          Schema.rule_for_type(value, path)
+        end
+        public_items = item.field || item.children.map(&:field).freeze
+        add(name, :map, items: public_items, item: item, **options)
+      end
+
+      private
+
+      def scalar(name, type, **options)
+        add(name, type, **options)
+      end
+
+      def add(name, type, default: UNSET, description: nil, enum: nil, minimum: nil,
+        maximum: nil, items: nil, deprecated: false, children: [], item: nil)
+        path = field_path(name)
+        raise ArgumentError, "Duplicate field #{path.join(".")}" if @rules.any? { |rule| rule.field.path == path }
+        validate_metadata(description, deprecated, minimum, maximum)
+
+        field = Field.new(path: Schema.frozen_copy(path), type: type, default: default.equal?(UNSET) ? nil : Schema.frozen_copy(default),
+          description: description && Schema.frozen_copy(description), enum: enum && Schema.frozen_copy(enum), minimum: minimum, maximum: maximum,
+          items: items, deprecated: deprecated).freeze
+        @rules << Schema.rule(field, type, children: children, item: item,
+          constraints: {minimum: minimum, maximum: maximum, enum: field.enum}, default_set: !default.equal?(UNSET))
+      end
+
+      def field_path(name)
+        raise TypeError, "field names must be nonempty Strings" unless name.is_a?(String) && !name.empty?
+
+        @path + [name]
+      end
+
+      def evaluate(builder, block)
+        raise ArgumentError, "a schema block is required" unless block
+
+        block.arity.zero? ? builder.instance_eval(&block) : block.call(builder)
+      end
+
+      def validate_metadata(description, deprecated, minimum, maximum)
+        raise TypeError, "description must be a String" unless description.nil? || description.is_a?(String)
+        raise TypeError, "deprecated must be true or false" unless [true, false].include?(deprecated)
+        {minimum: minimum, maximum: maximum}.each do |name, value|
+          next if value.nil? || value.is_a?(Numeric) && (!value.respond_to?(:finite?) || value.finite?)
+
+          raise TypeError, "#{name} must be a finite Numeric"
+        end
+      end
+    end
+  end
+end

data/lib/kochab/schema/json_compiler.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Kochab
+  class Schema
+    # Compiles the documented JSON Schema subset into internal rules.
+    class JsonCompiler
+      def initialize(root)
+        @root = root
+        @active = {}
+        @resolving = {}
+      end
+
+      def compile_root
+        schema = @root
+        seen = {}
+        while schema.is_a?(Hash) && schema.key?("$ref")
+          raise ArgumentError, "Circular JSON Schema reference" if seen[schema.object_id]
+
+          seen[schema.object_id] = true
+          schema = reference(schema.fetch("$ref"))
+        end
+        raise TypeError, "JSON Schema entries must be Hash values" unless schema.is_a?(Hash)
+        raise ArgumentError, "JSON Schema root must be an object" unless infer_type(schema) == :object
+
+        compile(@root, [])
+      end
+
+      def compile(schema, path)
+        raise TypeError, "JSON Schema entries must be Hash values" unless schema.is_a?(Hash)
+        if schema.key?("$ref")
+          target = reference(schema.fetch("$ref"))
+          return @active[target.object_id] if @active.key?(target.object_id)
+          raise ArgumentError, "Circular JSON Schema reference" if @resolving[target.object_id]
+
+          @resolving[target.object_id] = true
+          begin
+            return compile(target, path)
+          ensure
+            @resolving.delete(target.object_id)
+          end
+        end
+        return @active[schema.object_id] if @active.key?(schema.object_id)
+
+        properties = schema.fetch("properties", {})
+        required = schema.fetch("required", [])
+        raise TypeError, "JSON Schema properties must be a Hash" unless properties.is_a?(Hash)
+        raise TypeError, "JSON Schema required must be an Array" unless required.is_a?(Array)
+        unless properties.keys.all? { |name| name.is_a?(String) } && required.all? { |name| name.is_a?(String) }
+          raise TypeError, "JSON Schema property names must be Strings"
+        end
+        validate_keywords(schema)
+
+        type = infer_type(schema)
+        field = path.empty? ? nil : public_field(schema, path, type)
+        rule = Rule.new(field: field, children: [], item: nil, additional: true, required: [], constraints: {},
+          default_set: schema.key?("default"),
+          default: schema.key?("default") ? Schema.frozen_copy(schema["default"]) : nil)
+        @active[schema.object_id] = rule
+        rule.children = properties.map { |name, child| compile(child, path + [name]) }.freeze
+        rule.item = compile(schema["items"], path + [0]) if schema["items"].is_a?(Hash)
+        rule.additional = additional(schema, path)
+        rule.required = required.dup.freeze
+        rule.constraints = constraints(schema).freeze
+        @active.delete(schema.object_id)
+        rule
+      end
+
+      private
+
+      def infer_type(schema)
+        type = schema["type"]
+        type ||= "object" if schema.key?("properties") || schema.key?("additionalProperties")
+        Schema.normalize_type(type || :any)
+      end
+
+      def public_field(schema, path, type)
+        items = schema["items"] && Schema.normalize_type(schema["items"]["type"] || :any)
+        Field.new(path: Schema.frozen_copy(path), type: type, default: schema.key?("default") ? Schema.frozen_copy(schema["default"]) : nil,
+          description: schema["description"] && Schema.frozen_copy(schema["description"]),
+          enum: schema["enum"] && Schema.frozen_copy(schema["enum"]),
+          minimum: schema["minimum"], maximum: schema["maximum"], items: items,
+          deprecated: schema.fetch("deprecated", false)).freeze
+      end
+
+      def additional(schema, path)
+        value = schema.fetch("additionalProperties", true)
+        unless value.equal?(true) || value.equal?(false) || value.is_a?(Hash)
+          raise TypeError, "JSON Schema additionalProperties must be true, false, or a Hash"
+        end
+
+        value.is_a?(Hash) ? compile(value, path + ["*"]) : value
+      end
+
+      def constraints(schema)
+        {enum: schema["enum"] && Schema.frozen_copy(schema["enum"]), minimum: schema["minimum"], maximum: schema["maximum"],
+         exclusive_minimum: schema["exclusiveMinimum"], exclusive_maximum: schema["exclusiveMaximum"],
+         min_items: schema["minItems"], max_items: schema["maxItems"],
+         min_length: schema["minLength"], max_length: schema["maxLength"],
+         min_properties: schema["minProperties"], max_properties: schema["maxProperties"]}
+      end
+
+      def validate_keywords(schema)
+        raise TypeError, "JSON Schema items must be a Hash" if schema.key?("items") && !schema["items"].is_a?(Hash)
+        unless !schema.key?("enum") || schema["enum"].is_a?(Array) && !schema["enum"].empty?
+          raise TypeError, "JSON Schema enum must be a nonempty Array"
+        end
+        if schema.key?("description") && !schema["description"].is_a?(String)
+          raise TypeError, "JSON Schema description must be a String"
+        end
+        unless [true, false].include?(schema.fetch("deprecated", false))
+          raise TypeError, "JSON Schema deprecated must be true or false"
+        end
+        %w[minimum maximum exclusiveMinimum exclusiveMaximum].each do |name|
+          next unless schema.key?(name)
+
+          value = schema[name]
+          unless value.is_a?(Numeric) && (!value.respond_to?(:finite?) || value.finite?)
+            raise TypeError, "JSON Schema #{name} must be a finite Numeric"
+          end
+        end
+        %w[minItems maxItems minLength maxLength minProperties maxProperties].each do |name|
+          next unless schema.key?(name)
+
+          raise TypeError, "JSON Schema #{name} must be a nonnegative Integer" unless schema[name].is_a?(Integer) && schema[name] >= 0
+        end
+      end
+
+      def reference(pointer)
+        raise ArgumentError, "Only local JSON Schema references are supported" unless pointer.is_a?(String) && pointer.start_with?("#")
+
+        pointer.delete_prefix("#").split("/").reject(&:empty?).reduce(@root) do |value, token|
+          value.fetch(token.gsub("~1", "/").gsub("~0", "~"))
+        end
+      rescue KeyError
+        raise ArgumentError, "Unknown JSON Schema reference #{pointer.inspect}"
+      end
+    end
+    private_constant :JsonCompiler
+  end
+end

data/lib/kochab/schema/merge.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Kochab
+  class Schema
+    def merge(*documents)
+      documents.reduce(defaults) do |values, document|
+        if document.is_a?(Document)
+          layer = document.value
+          next values unless layer.is_a?(Hash)
+        else
+          layer = document
+          raise TypeError, "layers must be Kochab::Document or Hash values" unless layer.is_a?(Hash)
+        end
+
+        merge_object(values, layer, @root)
+      end
+    end
+
+    private
+
+    def merge_object(previous, layer, rule)
+      merge_members(previous, layer, rule).first
+    end
+
+    def merge_members(previous, layer, rule)
+      result = copy(previous)
+      changed = layer.empty?
+      layer.each do |name, value|
+        child = rule.children.find { |candidate| candidate.field.path.last == name }
+        child ||= rule.additional if rule.additional.is_a?(Rule)
+        if child
+          merged, valid = merge_value(result.fetch(name, UNSET), value, child)
+          result[name] = merged if valid
+          changed ||= valid
+        elsif rule.additional
+          result[name] = merge_untyped(result.fetch(name, UNSET), value)
+          changed = true
+        end
+      end
+      [result, changed]
+    end
+
+    def merge_value(previous, value, rule)
+      return [previous, false] unless type_match?(rule.field&.type || :object, value)
+      type = matching_type(rule.field&.type || :object, value)
+      if type == :object
+        base = previous.is_a?(Hash) ? previous : {}
+        candidate, changed = merge_members(base, value, rule)
+        return [candidate, changed && valid_value?(rule, candidate)] if previous.equal?(UNSET)
+
+        return [candidate, valid_value?(rule, candidate)]
+      end
+      if type == :map
+        result = previous.is_a?(Hash) ? copy(previous) : {}
+        changed = value.empty?
+        value.each do |name, entry|
+          next unless name.is_a?(String)
+
+          previous_item = result.fetch(name, UNSET)
+          if previous_item.equal?(UNSET)
+            item_default = default_for(rule.item)
+            previous_item = item_default if rule.item.default_set || !item_default.nil?
+          end
+          merged, valid = merge_value(previous_item, entry, rule.item)
+          result[name] = merged if valid
+          changed ||= valid
+        end
+        return [result, changed && valid_value?(rule, result)] if previous.equal?(UNSET)
+
+        return [result, valid_value?(rule, result)]
+      end
+
+      [copy(value), valid_value?(rule, value)]
+    end
+
+    def valid_value?(rule, value)
+      diagnostics = []
+      validate_rule(rule, value, [], nil, diagnostics)
+      diagnostics.empty?
+    end
+
+    def merge_untyped(previous, value)
+      return copy(value) unless previous.is_a?(Hash) && value.is_a?(Hash)
+
+      value.each_with_object(copy(previous)) do |(name, entry), result|
+        result[name] = merge_untyped(result.fetch(name, UNSET), entry)
+      end
+    end
+  end
+end

data/lib/kochab/schema/validation.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Kochab
+  class Schema
+    def validate(document)
+      raise TypeError, "document must be a Kochab::Document" unless document.is_a?(Document)
+
+      diagnostics = []
+      validate_rule(@root, document.value, [], document, diagnostics)
+      diagnostics
+    end
+
+    private
+
+    def validate_rule(rule, value, path, document, diagnostics, check_required: true)
+      type = rule.field&.type || :object
+      unless type_match?(type, value)
+        return add_diagnostic(diagnostics, document, path, "Expected #{Array(type).join(" or ")}")
+      end
+
+      constraints = rule.constraints
+      add_diagnostic(diagnostics, document, path, "Must be one of #{constraints[:enum].inspect}") if constraints[:enum] && !constraints[:enum].include?(value)
+      add_diagnostic(diagnostics, document, path, "Must be at least #{constraints[:minimum]}") if constraints[:minimum] && value.is_a?(Numeric) && value < constraints[:minimum]
+      add_diagnostic(diagnostics, document, path, "Must be at most #{constraints[:maximum]}") if constraints[:maximum] && value.is_a?(Numeric) && value > constraints[:maximum]
+      add_diagnostic(diagnostics, document, path, "Must be greater than #{constraints[:exclusive_minimum]}") if constraints[:exclusive_minimum] && value.is_a?(Numeric) && value <= constraints[:exclusive_minimum]
+      add_diagnostic(diagnostics, document, path, "Must be less than #{constraints[:exclusive_maximum]}") if constraints[:exclusive_maximum] && value.is_a?(Numeric) && value >= constraints[:exclusive_maximum]
+      add_size_diagnostics(diagnostics, document, path, value, constraints)
+      validate_container(rule, value, path, document, diagnostics, check_required: check_required)
+    end
+
+    def validate_container(rule, value, path, document, diagnostics, check_required: true)
+      type = matching_type(rule.field&.type || :object, value)
+      if type == :array
+        value.each_with_index { |entry, index| validate_rule(rule.item, entry, path + [index], document, diagnostics, check_required: check_required) } if rule.item
+      elsif type == :map
+        value.each do |key, entry|
+          if key.is_a?(String)
+            validate_rule(rule.item, entry, path + [key], document, diagnostics, check_required: check_required) if rule.item
+          else
+            add_diagnostic(diagnostics, document, path + [key], "Map keys must be Strings")
+          end
+        end
+      elsif type == :object
+        validate_object(rule, value, path, document, diagnostics, check_required: check_required)
+      end
+    end
+
+    def add_size_diagnostics(diagnostics, document, path, value, constraints)
+      return unless value.respond_to?(:length)
+
+      minimum = value.is_a?(String) ? constraints[:min_length] : constraints[value.is_a?(Array) ? :min_items : :min_properties]
+      maximum = value.is_a?(String) ? constraints[:max_length] : constraints[value.is_a?(Array) ? :max_items : :max_properties]
+      add_diagnostic(diagnostics, document, path, "Must contain at least #{minimum} entries") if minimum && value.length < minimum
+      add_diagnostic(diagnostics, document, path, "Must contain at most #{maximum} entries") if maximum && value.length > maximum
+    end
+
+    def validate_object(rule, value, path, document, diagnostics, check_required: true)
+      rule.required.each do |name|
+        add_diagnostic(diagnostics, document, path + [name], "Required value is missing", path) unless value.key?(name)
+      end if check_required
+      value.each do |name, entry|
+        child = rule.children.find { |candidate| candidate.field.path.last == name }
+        child ||= rule.additional if rule.additional.is_a?(Rule)
+        add_diagnostic(diagnostics, document, path + [name], "Unknown field") if !child && !rule.additional
+        validate_rule(child, entry, path + [name], document, diagnostics, check_required: check_required) if child
+      end
+    end
+
+    def add_diagnostic(diagnostics, document, path, message, range_path = path)
+      range = document && (document.range_of(range_path) || document.range_of(range_path[0...-1]))
+      diagnostics << Diagnostic.new(path: path.freeze, range: range, severity: :error, message: message)
+    end
+
+    def type_match?(type, value)
+      return type.any? { |entry| type_match?(entry, value) } if type.is_a?(Array)
+
+      case type
+      when :any then true
+      when :null then value.nil?
+      when :boolean then value.equal?(true) || value.equal?(false)
+      when :integer then value.is_a?(Integer)
+      when :number then value.is_a?(Numeric) && (!value.respond_to?(:finite?) || value.finite?)
+      when :string then value.is_a?(String)
+      when :array then value.is_a?(Array)
+      when :object, :map then value.is_a?(Hash)
+      else false
+      end
+    end
+
+    def matching_type(type, value)
+      type.is_a?(Array) ? type.find { |entry| type_match?(entry, value) } : type
+    end
+  end
+end

data/lib/kochab/schema.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Kochab
+  # Typed settings metadata, source-aware validation, and safe layer merging.
+  class Schema
+    UNSET = Object.new.freeze
+    TYPES = %i[any array boolean integer map null number object string].freeze
+    Rule = Struct.new(:field, :children, :item, :additional, :required, :constraints,
+      :default_set, :default, keyword_init: true)
+    private_constant :UNSET, :TYPES, :Rule
+
+    def self.define(&block)
+      raise ArgumentError, "a schema block is required" unless block
+
+      builder = Builder.new
+      block.arity.zero? ? builder.instance_eval(&block) : block.call(builder)
+      new(rule(nil, :object, children: builder.rules))
+    end
+
+    def self.from_json_schema(hash)
+      raise TypeError, "JSON Schema must be a Hash" unless hash.is_a?(Hash)
+
+      compiler = JsonCompiler.new(hash)
+      root = compiler.compile_root
+      new(root)
+    end
+
+    def initialize(root)
+      @root = root
+      validate_defaults!
+      @fields = collect_fields(root).freeze
+    end
+
+    def defaults
+      copy(default_for(@root) || {})
+    end
+
+    def describe(path)
+      rule = find_rule(path)
+      rule&.field
+    end
+
+    def fields
+      @fields.dup
+    end
+
+    class << self
+      def rule(field, type, children: [], item: nil, additional: true, required: [], constraints: {}, default_set: false)
+        Rule.new(field: field, children: children.freeze, item: item, additional: additional,
+          required: required.freeze, constraints: constraints.freeze, default_set: default_set,
+          default: default_set ? field&.default : nil)
+      end
+
+      def rule_for_type(type, path)
+        type = normalize_type(type)
+        field = Field.new(path: frozen_copy(path), type: type, default: nil, items: nil, deprecated: false).freeze
+        rule(field, type)
+      end
+
+      def normalize_type(type)
+        unless type.is_a?(Array) || type.respond_to?(:to_sym)
+          raise ArgumentError, "Unsupported schema type #{type.inspect}"
+        end
+
+        normalized = type.is_a?(Array) ? type.map { |entry| normalize_type(entry) }.freeze : type.to_sym
+        raise ArgumentError, "Unsupported schema type #{type.inspect}" if normalized.is_a?(Array) && normalized.empty?
+
+        valid = normalized.is_a?(Array) ? normalized.all? { |entry| TYPES.include?(entry) } : TYPES.include?(normalized)
+        raise ArgumentError, "Unsupported schema type #{type.inspect}" unless valid
+
+        normalized
+      end
+
+      def type_of(value)
+        case value
+        when nil then :null
+        when true, false then :boolean
+        when Integer then :integer
+        when Numeric then :number
+        when String then :string
+        when Array then :array
+        when Hash then :object
+        else :any
+        end
+      end
+
+      def public_item(rule)
+        rule.field&.type
+      end
+
+      def copy(value)
+        case value
+        when Hash then value.to_h { |key, entry| [copy(key), copy(entry)] }
+        when Array then value.map { |entry| copy(entry) }
+        else value.dup
+        end
+      rescue TypeError
+        value
+      end
+
+      def frozen_copy(value)
+        freeze_value(copy(value))
+      end
+
+      def freeze_value(value)
+        case value
+        when Hash then value.each { |key, entry| freeze_value(key); freeze_value(entry) }
+        when Array then value.each { |entry| freeze_value(entry) }
+        end
+        value.freeze
+      end
+    end
+
+    private
+
+    def validate_defaults!
+      diagnostics = []
+      defaults = default_for(@root) || {}
+      validate_rule(@root, defaults, [], nil, diagnostics, check_required: false)
+      return if diagnostics.empty?
+
+      raise ArgumentError, "Invalid schema default at #{diagnostics.first.path.join(".")}: #{diagnostics.first.message}"
+    end
+
+    def collect_fields(rule, seen = {})
+      return [] if seen[rule.object_id]
+
+      seen[rule.object_id] = true
+      own = rule.field ? [rule.field] : []
+      own + rule.children.flat_map { |child| collect_fields(child, seen) } +
+        (rule.item.is_a?(Rule) ? collect_fields(rule.item, seen) : []) +
+        (rule.additional.is_a?(Rule) ? collect_fields(rule.additional, seen) : [])
+    end
+
+    def default_for(rule, ancestors = {})
+      return copy(rule.default) if rule.default_set
+
+      return unless [:object, :map].include?(rule.field&.type || :object)
+      return if ancestors[rule.object_id]
+
+      ancestors[rule.object_id] = true
+      values = rule.children.each_with_object({}) do |child, result|
+        value = default_for(child, ancestors)
+        result[child.field.path.last] = value unless value.nil? && !child.default_set
+      end
+      ancestors.delete(rule.object_id)
+      values.empty? ? nil : values
+    end
+
+    def find_rule(path)
+      raise TypeError, "path must be an Array" unless path.is_a?(Array)
+
+      path.reduce(@root) do |rule, part|
+        return nil unless rule
+        type = rule.field&.type || :object
+        case type
+        when :object
+          rule.children.find { |child| child.field.path.last == part } || (rule.additional if rule.additional.is_a?(Rule))
+        when :map
+          return nil unless part.is_a?(String)
+          rule.item
+        when :array
+          return nil unless part.is_a?(Integer) && part >= 0
+          rule.item
+        end
+      end
+    end
+
+    def copy(value) = self.class.copy(value)
+
+  end
+end
+
+require_relative "schema/builder"
+require_relative "schema/json_compiler"
+require_relative "schema/validation"
+require_relative "schema/merge"

data/lib/kochab/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kochab
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/kochab.rb

@@ -11,6 +11,9 @@ module Kochab
   TextEdit = Struct.new(:offset, :length, :text, keyword_init: true)
   Node = Struct.new(:kind, :range, :key_range, :value, :children,
     :leading_comments, :trailing_comment, :key, :parent, keyword_init: true)
+  Field = Struct.new(:path, :type, :default, :description, :enum, :minimum, :maximum,
+    :items, :deprecated, keyword_init: true)
+  Diagnostic = Struct.new(:path, :range, :severity, :message, keyword_init: true)
 
   class ParseError < StandardError
     attr_reader :errors
@@ -79,3 +82,4 @@ end
 require_relative "kochab/parser"
 require_relative "kochab/document"
 require_relative "kochab/editing"
+require_relative "kochab/schema"

data/sig/kochab.rbs

@@ -42,6 +42,27 @@ module Kochab
     def initialize: (?kind: Symbol, ?range: Range[Integer], ?key_range: Range[Integer]?, ?value: value, ?children: Array[Node], ?leading_comments: Array[Comment], ?trailing_comment: Comment?, ?key: (String | Integer)?, ?parent: Node?) -> void
   end
 
+  class Field < Struct[untyped]
+    attr_accessor path: path
+    attr_accessor type: (Symbol | Array[Symbol])
+    attr_accessor default: value
+    attr_accessor description: String?
+    attr_accessor enum: Array[value]?
+    attr_accessor minimum: Numeric?
+    attr_accessor maximum: Numeric?
+    attr_accessor items: untyped
+    attr_accessor deprecated: bool
+    def initialize: (?path: path, ?type: (Symbol | Array[Symbol]), ?default: value, ?description: String?, ?enum: Array[value]?, ?minimum: Numeric?, ?maximum: Numeric?, ?items: untyped, ?deprecated: bool) -> void
+  end
+
+  class Diagnostic < Struct[untyped]
+    attr_accessor path: path
+    attr_accessor range: Range[Integer]?
+    attr_accessor severity: Symbol
+    attr_accessor message: String
+    def initialize: (?path: path, ?range: Range[Integer]?, ?severity: Symbol, ?message: String) -> void
+  end
+
   class ParseError < StandardError
     attr_reader errors: Array[Error]
     def initialize: (Array[Error] errors) -> void
@@ -66,4 +87,25 @@ module Kochab
     def insert: (path path, value value, ?after: String?) -> Array[TextEdit]
     def format: (?indent: Integer, ?keep_blank_lines: Integer) -> String
   end
+
+  class Schema
+    def self.define: () { (Builder) -> void } -> Schema
+    def self.from_json_schema: (Hash[String, value] hash) -> Schema
+    def validate: (Document document) -> Array[Diagnostic]
+    def defaults: () -> Hash[String, value]
+    def merge: (*(Document | Hash[String, value]) documents) -> Hash[String, value]
+    def describe: (path path) -> Field?
+    def fields: () -> Array[Field]
+
+    class Builder
+      def boolean: (String name, ?default: value, ?description: String?, ?deprecated: bool) -> untyped
+      def integer: (String name, ?default: value, ?description: String?, ?minimum: Numeric?, ?maximum: Numeric?, ?deprecated: bool) -> untyped
+      def number: (String name, ?default: value, ?description: String?, ?minimum: Numeric?, ?maximum: Numeric?, ?deprecated: bool) -> untyped
+      def string: (String name, ?default: value, ?description: String?, ?deprecated: bool) -> untyped
+      def enum: (String name, values: Array[value], ?default: value, ?description: String?, ?deprecated: bool) -> untyped
+      def object: (String name, ?default: value, ?description: String?, ?deprecated: bool) { (Builder) -> void } -> untyped
+      def array: (String name, items: (Symbol | Array[Symbol]), ?default: value, ?description: String?, ?deprecated: bool) -> untyped
+      def map: (String name, value: (Symbol | ^(Builder) -> void), ?default: value, ?description: String?, ?deprecated: bool) -> untyped
+    end
+  end
 end

metadata

@@ -1,16 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: kochab
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Yudai Takada
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-09-15 00:00:00.000000000 Z
 dependencies: []
 description: A Ruby JSONC parser with byte ranges, syntax recovery, source queries,
-  minimal text edits, formatting, and UTF-16 positions. No runtime gem dependencies.
+  minimal text edits, formatting, UTF-16 positions, and typed settings schemas. No
+  runtime gem dependencies.
 email:
 - t.yudai92@gmail.com
 executables: []
@@ -25,6 +27,11 @@ files:
 - lib/kochab/document.rb
 - lib/kochab/editing.rb
 - lib/kochab/parser.rb
+- lib/kochab/schema.rb
+- lib/kochab/schema/builder.rb
+- lib/kochab/schema/json_compiler.rb
+- lib/kochab/schema/merge.rb
+- lib/kochab/schema/validation.rb
 - lib/kochab/version.rb
 - sig/kochab.rbs
 homepage: https://github.com/noxdea/kochab
@@ -33,7 +40,9 @@ licenses:
 metadata:
   source_code_uri: https://github.com/noxdea/kochab
   changelog_uri: https://github.com/noxdea/kochab/blob/main/CHANGELOG.md
+  allowed_push_host: https://rubygems.org
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -48,7 +57,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.19
+rubygems_version: 3.4.19
+signing_key:
 specification_version: 4
-summary: Recoverable JSONC parsing and edits that preserve comments and formatting
+summary: Source-aware JSONC parsing, editing, formatting, and schema validation
 test_files: []