structured_store 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e104dd0bcd9069ad670b176be0ad3e56231f8a2a02b2237b9d76cd8e1504302
-  data.tar.gz: b14d540d205c843a34355444f0893b7190c7df870d616c07357bb484e23105ad
+  metadata.gz: d346e5035fb3c5370c2507bc6e7ea91f120f1d757e45e8335ece92bbd9c266b7
+  data.tar.gz: abfeb9b199feb81a5d7629f146b206c475a84498e33780816ceedfb524a9296d
 SHA512:
-  metadata.gz: f946faaa8dc5fa672e765f6a9b5261f499b12c164324e8df7144d3a821009f5dbdb4b3c572d1dc4903578ae20a5802f4f7d0f42d52fd7125a36e445e86357f45
-  data.tar.gz: eae79479eff4abc7a24ac1966f76b24d6b4b8ede45e00d899136f93fec3f714ec4e4e9afe33362c386f9289db6b87dd46ca64c6fa98b54dd4b28788411773ff7
+  metadata.gz: 227e320720ecf341eb778dd0cdc4a4c63d72fcb179c122b7e83b4c238c032447259f58d06cfd355eeaff9e55b75f9480cd465380d540ff6f2a75cc485c252c7c
+  data.tar.gz: 2ed007f16a85163a8231a361451f6f495d12fdcf9854e7e4a2121052be3c46cf36267a076f69a67d2d70723cdd267ebdd55c5c33cbf9672b14e17b6019fcee44

data/README.md

@@ -35,8 +35,8 @@ StructuredStore provides a robust way to manage JSON data with versioned schemas
 After installation, create the necessary database tables:
 
 ```bash
-$ rails generate structured_store:install
-$ rails db:migrate
+rails generate structured_store:install
+rails db:migrate
 ```
 
 This creates a `structured_store_versioned_schemas` table and a `db/structured_store_versioned_schemas/` directory for your schema files.
@@ -90,17 +90,20 @@ end
 Run the migration:
 
 ```bash
-$ rails db:migrate
+rails db:migrate
 ```
 
 ### 2. Creating a Model with Structured Storage
 
-Create a model that includes the `StructuredStore::Storable` concern:
+Create a model that includes the `StructuredStore::Storable` concern and explicitly configure the structured store column(s):
 
 ```ruby
 # app/models/user_preference.rb
 class UserPreference < ApplicationRecord
   include StructuredStore::Storable
+
+  # Must explicitly configure structured store column(s)
+  structured_store :preferences
 end
 ```
 
@@ -111,8 +114,8 @@ Generate and run a migration for your model:
 class CreateUserPreferences < ActiveRecord::Migration[7.0]
   def change
     create_table :user_preferences do |t|
-      t.references :structured_store_versioned_schema, null: false, foreign_key: true
-      t.json :store
+      t.references :structured_store_preferences_versioned_schema, null: false, foreign_key: { to_table: :structured_store_versioned_schemas }
+      t.json :preferences
       t.timestamps
     end
   end
@@ -121,7 +124,7 @@ end
 
 ### 3. Using the Structured Store
 
-Once your model includes `StructuredStore::Storable`, it automatically gets accessor methods for all properties defined in the associated JSON schema:
+Once your model includes `StructuredStore::Storable` and configures structured stores, it automatically gets accessor methods for all properties defined in the associated JSON schema:
 
 ```ruby
 # Find the latest version of your schema
@@ -129,7 +132,7 @@ schema = StructuredStore::VersionedSchema.latest("UserPreferences")
 
 # Create a new record
 preference = UserPreference.create!(
-  versioned_schema: schema,
+  preferences_versioned_schema: schema,
   theme: "dark",
   notifications: false,
   language: "es"
@@ -143,8 +146,23 @@ preference.language      # => "es"
 # Update structured data
 preference.update!(theme: "light", notifications: true)
 
-# The data is stored in the JSON `store` column
-preference.store # => {"theme"=>"light", "notifications"=>true, "language"=>"es"}
+# The data is stored in the JSON `preferences` column
+preference.preferences # => {"theme"=>"light", "notifications"=>true, "language"=>"es"}
+```
+
+If you chose to alter the migration to use a column type other than `json` or `jsonb`, you will need to amend your model to define the store and JSON serialiser (aka coder):
+
+```ruby
+# app/models/user_preference.rb
+class UserPreference < ApplicationRecord
+  include StructuredStore::Storable
+
+  # Declare the ActiveRecord::Store and coder for unstructured database data types
+  store :preferences, coder: JSON
+
+  # Declare that the structured store using the unstructured preferences column
+  structured_store :preferences
+end
 ```
 
 ### 4. Schema Versioning
@@ -164,7 +182,7 @@ Create `db/structured_store_versioned_schemas/UserPreferences-1.1.0.json`:
       "examples": ["light", "dark", "system"]
     },
     "notifications": {
-      "type": "boolean", 
+      "type": "boolean",
       "description": "Whether user notifications are enabled"
     },
     "language": {
@@ -201,7 +219,7 @@ latest_schema = StructuredStore::VersionedSchema.latest("UserPreferences")
 
 # Create a record with the new schema
 new_preference = UserPreference.create!(
-  versioned_schema: latest_schema,
+  preferences_versioned_schema: latest_schema,
   theme: "system",
   timezone: "America/New_York"
 )
@@ -214,7 +232,7 @@ new_preference.timezone # => "America/New_York"
 All data is automatically validated against the associated JSON schema:
 
 ```ruby
-preference = UserPreference.new(versioned_schema: schema)
+preference = UserPreference.new(preferences_versioned_schema: schema)
 
 # This will fail validation because 'theme' is required
 preference.valid? # => false
@@ -227,7 +245,85 @@ preference.valid? # => true
 preference.notifications = "invalid" # Will cause validation error
 ```
 
-### 6. Working with Complex Data Types
+### 6. Working with Array Properties
+
+StructuredStore supports JSON schema properties with `type: "array"` for both arrays with `$ref` items and arrays with direct type items.
+
+#### Arrays with Direct Type Items
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2019-09/schema",
+  "type": "object",
+  "properties": {
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "List of tags"
+    }
+  }
+}
+```
+
+```ruby
+schema = StructuredStore::VersionedSchema.create!(
+  name: 'BlogPost',
+  version: '1.0.0',
+  json_schema: schema
+)
+
+post = BlogPost.new(data_versioned_schema: schema)
+post.tags = ['ruby', 'rails', 'testing']
+post.save!
+
+post.tags # => ['ruby', 'rails', 'testing']
+```
+
+#### Arrays with $ref Items
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2019-09/schema",
+  "type": "object",
+  "definitions": {
+    "status_type": {
+      "type": "string",
+      "enum": ["pending", "active", "completed"]
+    }
+  },
+  "properties": {
+    "statuses": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/status_type"
+      },
+      "description": "List of statuses"
+    }
+  }
+}
+```
+
+```ruby
+schema = StructuredStore::VersionedSchema.create!(
+  name: 'Workflow',
+  version: '1.0.0',
+  json_schema: schema
+)
+
+workflow = Workflow.new(data_versioned_schema: schema)
+workflow.statuses = ['pending', 'active']
+workflow.save!
+
+workflow.statuses # => ['pending', 'active']
+```
+
+**Supported item types:** `string`, `integer`, `boolean`
+
+**Note:** Arrays with `object` or other complex item types are not currently supported.
+
+### 7. Working with Complex Data Types
 
 StructuredStore includes a `JsonDateRangeResolver` for handling date ranges through JSON schema references. This resolver works with date range converters to transform natural language date strings into structured date ranges.
 
@@ -255,7 +351,9 @@ require 'structured_store/ref_resolvers/json_date_range_resolver'
 
 class EventRecord < ApplicationRecord
   include StructuredStore::Storable
-  
+
+  structured_store :event_data
+
   def date_range_converter
     @date_range_converter ||= StructuredStore::Converters::ChronicDateRangeConverter.new
   end
@@ -269,12 +367,12 @@ If you choose to use the `ChronicDateRangeConverter`, you will also need to add
 ```ruby
 # Create a record with a natural language date range
 event = EventRecord.create!(
-  versioned_schema: schema,
+  event_data_versioned_schema: schema,
   event_period: "January 2024"
 )
 
 # The converter transforms this to structured data internally
-event.store['event_period'] 
+event.event_data['event_period']
 # => {"date1"=>"2024-01-01 00:00:00", "date2"=>"2024-01-31 00:00:00"}
 
 # When accessed, it's converted back to the natural language format
@@ -295,7 +393,7 @@ class CustomDateRangeConverter
     # Your custom logic to parse date ranges
     # Should return [start_date, end_date]
   end
-  
+
   def convert_to_string(date1, date2)
     # Your custom logic to format date ranges
     # Should return a string representation
@@ -304,14 +402,16 @@ end
 
 class MyModel < ApplicationRecord
   include StructuredStore::Storable
-  
+
+  structured_store :data
+
   def date_range_converter
     @date_range_converter ||= CustomDateRangeConverter.new
   end
 end
 ```
 
-### 7. Finding and Querying Schemas
+### 8. Finding and Querying Schemas
 
 ```ruby
 # Find the latest version of a schema
@@ -325,27 +425,50 @@ all_versions = StructuredStore::VersionedSchema.where(name: "UserPreferences")
                                                .order(:version)
 ```
 
-### 8. Advanced Usage: Custom Reference Resolvers
+### 9. Configurable Store Columns
+
+StructuredStore supports configurable store columns, allowing you to use alternative column names for a single store (e.g., `depot` instead of `store`) or configure multiple store columns within the same model. This enables you to organize different types of structured data separately while maintaining proper schema versioning.
+
+For detailed information on configuring single custom stores and multiple stores, see the [Custom Stores documentation](docs/custom_stores.md).
+
+### 10. Advanced Usage: Custom Reference Resolvers
 
 StructuredStore includes a resolver system for handling JSON schema references. You can create custom resolvers by extending `StructuredStore::RefResolvers::Base`:
 
 ```ruby
 class CustomResolver < StructuredStore::RefResolvers::Base
   def self.matching_ref_pattern
-    /^#\/custom\//
+    /^external:\/\/my_custom_type\//
   end
 
   def define_attribute
-    lambda do |instance|
-      # Define custom attribute behavior
+    # Access property_schema to get the property's JSON schema
+    type = property_schema['type']
+
+    lambda do |object|
+      # Define custom attribute behavior on the object
+      object.singleton_class.attribute(property_name, type.to_sym)
     end
   end
+
+  def options_array
+    # Return array of [value, label] pairs for form selects
+    # Access parent_schema.definition_schema(name) if you need to look up definitions
+    []
+  end
 end
 
 # Register your custom resolver
 CustomResolver.register
 ```
 
+**Available instance variables in your resolver:**
+- `property_schema` - The property's JSON schema hash
+- `parent_schema` - The parent SchemaInspector for looking up definitions
+- `property_name` - The property name (for error messages)
+- `ref_string` - The `$ref` value
+- `context` - Additional context hash
+
 ### Best Practices
 
 1. **Version your schemas semantically**: Use semantic versioning (e.g., "1.0.0", "1.1.0", "2.0.0") to track schema changes.
@@ -370,7 +493,7 @@ CustomResolver.register
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/HealthDataInsight/structured_store. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/HealthDataInsight/structured_store/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at <https://github.com/HealthDataInsight/structured_store>. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/HealthDataInsight/structured_store/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 

data/app/models/concerns/structured_store/storable.rb

@@ -1,34 +1,101 @@
 module StructuredStore
   # This module is included in models that need to be stored in a structured way.
   # It provides the necessary methods and attributes for structured storage.
-  # The `storeable_attributes` method defines the attributes that will be stored.
-  # The `to_s` method is overridden to return the name of the object or the default string representation.
+  #
+  # To use this module, include it in your model and call `structured_store` for each
+  # store column you want to configure. Each call will create a belongs_to association
+  # to a VersionedSchema and define helper methods for accessing the JSON schema.
+  #
+  # @example Basic usage
+  #   class User < ApplicationRecord
+  #     include StructuredStore::Storable
+  #
+  #     structured_store :preferences
+  #     structured_store :metadata
+  #   end
+  #
+  # @example Custom schema name
+  #   class Product < ApplicationRecord
+  #     include StructuredStore::Storable
+  #
+  #     structured_store :configuration, schema_name: 'product_config_schema'
+  #   end
   module Storable
     extend ActiveSupport::Concern
 
     included do
-      after_initialize :define_store_accessors!
+      after_initialize :define_all_store_accessors!
 
-      belongs_to :versioned_schema, # rubocop:disable Rails/InverseOf
-                 class_name: 'StructuredStore::VersionedSchema',
-                 foreign_key: 'structured_store_versioned_schema_id'
+      class_attribute :_structured_store_configurations, default: []
+    end
+
+    class_methods do
+      # Configures a structured store column and creates the necessary associations.
+      #
+      # This method must be called explicitly for each store column you want to use.
+      # It will:
+      # - Add the column configuration to the internal tracking
+      # - Create a belongs_to association to StructuredStore::VersionedSchema
+      # - Define a helper method to access the JSON schema for this store
+      #
+      # @param column_name [String, Symbol] The name of the store column in your model
+      # @param schema_name [String, Symbol, nil] Optional custom name for the schema association
+      #   If not provided, defaults to "#{column_name}_versioned_schema"
+      #
+      # @example Simple store configuration
+      #   structured_store :preferences
+      #   # Creates: belongs_to :preferences_versioned_schema
+      #   # Helper method: preferences_json_schema
+      #
+      # @example Custom schema name
+      #   structured_store :config, schema_name: 'product_configuration'
+      #   # Creates: belongs_to :product_configuration
+      #   # Helper method: product_configuration_json_schema
+      def structured_store(column_name, schema_name: nil)
+        column_name = column_name.to_s
+        schema_name ||= "#{column_name}_versioned_schema"
+        schema_name = schema_name.to_s
+
+        # Add configuration for this column
+        self._structured_store_configurations = _structured_store_configurations + [{
+          column_name: column_name,
+          schema_name: schema_name
+        }]
+
+        # Define the belongs_to association immediately
+        belongs_to schema_name.to_sym, # rubocop:disable Rails/InverseOf
+                   class_name: 'StructuredStore::VersionedSchema',
+                   foreign_key: "structured_store_#{schema_name}_id"
+
+        # Define helper method to get schema for this specific store
+        define_method "#{column_name}_json_schema" do
+          send(schema_name)&.json_schema
+        end
+      end
+    end
 
-      delegate :json_schema, to: :versioned_schema
+    # Define accessors for all configured store columns
+    def define_all_store_accessors!
+      _structured_store_configurations.each do |config|
+        define_store_accessors_for_column(config[:column_name])
+      end
     end
 
     # Dynamically define accessors for the properties defined in the
-    # JSON schema that this record has.
+    # JSON schema for this specific store column.
     #
     # This method is run automatically as an `after_initialize` callback, but can be called at
     # any time for debugging and testing purposes.
     #
     # It skips defining the accessors if there is insufficient information to do so.
-    def define_store_accessors!
-      return unless sufficient_info_to_define_store_accessors?
+    #
+    # @param column_name [String] The name of the store column
+    def define_store_accessors_for_column(column_name)
+      return unless sufficient_info_to_define_store_accessors?(column_name)
 
-      singleton_class.store_accessor(:store, json_schema_properties.keys)
+      singleton_class.store_accessor(column_name.to_sym, json_schema_properties(column_name).keys)
 
-      property_resolvers.each_value do |resolver|
+      property_resolvers(column_name).each_value do |resolver|
         resolver.define_attribute.call(self)
       end
     end
@@ -37,42 +104,71 @@ module StructuredStore
     # The resolvers are responsible for handling references and defining attributes
     # for each property defined in the schema.
     #
-    # @return [Array<StructuredStore::RefResolvers::Base>] Array of resolver instances
-    def property_resolvers
-      @property_resolvers ||= json_schema_properties.keys.index_with do |property_name|
-        StructuredStore::RefResolvers::Registry.matching_resolver(schema_inspector,
+    # @param column_name [String] The name of the store column
+    # @return [Hash<String, StructuredStore::RefResolvers::Base>] Hash of resolver instances
+    def property_resolvers(column_name)
+      return {} if column_name.nil?
+
+      @property_resolvers ||= {}
+      @property_resolvers[column_name] ||= json_schema_properties(column_name).keys.index_with do |property_name|
+        StructuredStore::RefResolvers::Registry.matching_resolver(schema_inspector(column_name),
                                                                   property_name)
       end
     end
 
     private
 
-    # Returns a SchemaInspector instance for the current JSON schema.
-    def schema_inspector
-      @schema_inspector ||= StructuredStore::SchemaInspector.new(json_schema)
+    # Returns a SchemaInspector instance for the specified store column's JSON schema.
+    #
+    # @param column_name [String] The name of the store column
+    def schema_inspector(column_name)
+      return nil if column_name.nil?
+
+      @schema_inspectors ||= {}
+      @schema_inspectors[column_name] ||= StructuredStore::SchemaInspector.new(json_schema_for_column(column_name))
     end
 
-    # Retrieves the properties from the JSON schema
+    # Retrieves the properties from the JSON schema for the specified store column
     #
+    # @param column_name [String] The name of the store column
     # @return [Hash] a hash containing the properties defined in the JSON schema,
     #                or an empty hash if no properties exist
-    def json_schema_properties
-      json_schema.fetch('properties', {})
+    def json_schema_properties(column_name)
+      return {} if column_name.nil?
+
+      json_schema_for_column(column_name).fetch('properties', {})
+    end
+
+    # Gets the JSON schema for a specific store column
+    #
+    # @param column_name [String] The name of the store column
+    # @return [Hash] The JSON schema hash
+    def json_schema_for_column(column_name)
+      return {} if column_name.nil?
+
+      send("#{column_name}_json_schema") || {}
     end
 
-    # Returns true if there is sufficient information to define accessors for this audit_store,
+    # Returns true if there is sufficient information to define accessors for the specified store column,
     # and false otherwise.
     #
     # The JSON schema must be defined, containing property definitions.
-    def sufficient_info_to_define_store_accessors?
-      if json_schema.nil?
-        Rails.logger.info('This storable instance has no JSON schema')
+    #
+    # @param column_name [String] The name of the store column
+    def sufficient_info_to_define_store_accessors?(column_name)
+      return false if column_name.nil?
+
+      schema = json_schema_for_column(column_name)
+      properties = json_schema_properties(column_name)
+
+      if schema.blank?
+        Rails.logger.info("This storable instance has no JSON schema for column '#{column_name}'")
         return false
       end
 
-      unless json_schema_properties.is_a?(Hash)
-        Rails.logger.warn 'The JSON schema for this storable instance does not contain ' \
-                          "a valid 'properties' hash: #{json_schema_properties.inspect}"
+      unless properties.is_a?(Hash)
+        Rails.logger.warn "The JSON schema for column '#{column_name}' does not contain " \
+                          "a valid 'properties' hash: #{properties.inspect}"
         return false
       end
 

data/app/validators/json_schema_validator.rb

@@ -9,8 +9,8 @@ class JsonSchemaValidator < ActiveModel::EachValidator
     # Convert value to hash if it's a string
     json_data = value.is_a?(String) ? JSON.parse(value) : value
 
-    # Get the schema from options
-    schema = options[:schema] || options
+    # Get the schema from options, evaluating lambda if provided
+    schema = resolve_schema(record, attribute, value)
 
     # Initialize JSONSchemer with proper handling based on schema type
     schemer = json_schemer(schema)
@@ -28,6 +28,20 @@ class JsonSchemaValidator < ActiveModel::EachValidator
 
   private
 
+  # Resolves the schema from options, evaluating lambda if provided.
+  #
+  # If the schema option is a lambda, it will be called with the record,
+  # attribute, and value as arguments.
+  def resolve_schema(record, attribute, value)
+    schema = options[:schema] || options
+
+    if schema.respond_to?(:call)
+      schema.call(record, attribute, value)
+    else
+      schema
+    end
+  end
+
   # Converts given schema to a JSONSchemer::Schema object.
   #
   # Accepts either a symbol referencing a known schema (e.g. :draft7), a string

data/lib/structured_store/ref_resolvers/base.rb

@@ -7,7 +7,8 @@ module StructuredStore
       attr_reader :context,
                   :property_name,
                   :ref_string,
-                  :schema_inspector
+                  :property_schema,
+                  :parent_schema
 
       class << self
         def matching_ref_pattern
@@ -25,10 +26,14 @@ module StructuredStore
 
       # Initialize method for the base reference resolver
       #
-      # @param schema [Hash] JSON Schema for the resolver
-      # @param options [Hash] Additional options for the resolver
-      def initialize(schema_inspector, property_name, ref_string, context = {})
-        @schema_inspector = schema_inspector
+      # @param property_schema [Hash] The property's JSON schema (with type, $ref, etc.)
+      # @param parent_schema [SchemaInspector] Parent schema for definition lookups
+      # @param property_name [String] Name of the property (for error messages)
+      # @param ref_string [String] The $ref string if present
+      # @param context [Hash] Additional context
+      def initialize(property_schema, parent_schema, property_name, ref_string = '', context = {})
+        @property_schema = property_schema
+        @parent_schema = parent_schema
         @property_name = property_name
         @ref_string = ref_string
         @context = context
@@ -54,12 +59,6 @@ module StructuredStore
       def options_array
         raise NotImplementedError, 'Subclasses must implement the options_array method'
       end
-
-      private
-
-      def json_property_schema
-        @json_property_schema ||= schema_inspector.property_schema(property_name) || {}
-      end
     end
   end
 end

data/lib/structured_store/ref_resolvers/blank_ref_resolver.rb

@@ -16,7 +16,10 @@ module StructuredStore
       # @return [Proc] a lambda that defines the attribute on the singleton class
       # @raise [RuntimeError] if the property type is unsupported
       def define_attribute
-        type = json_property_schema['type']
+        type = property_schema['type']
+
+        # Handle arrays
+        return define_array_attribute if type == 'array'
 
         unless %w[boolean integer string].include?(type)
           raise "Unsupported attribute type: #{type.inspect} for property '#{property_name}'"
@@ -31,11 +34,56 @@ module StructuredStore
       # Returns a two dimensional array of options from the 'enum' property definition
       # Each element contains a duplicate of the enum option for both the label and value
       #
+      # For arrays, delegates to a resolver for the items to get options recursively
+      #
       # @return [Array<Array>] Array of arrays containing id, value option pairs
       def options_array
-        enum = json_property_schema['enum']
+        # For arrays, delegate to the items resolver
+        if property_schema['type'] == 'array'
+          items_resolver = create_items_resolver
+          return items_resolver.options_array
+        end
+
+        # For non-arrays, get enum directly
+        enum = property_schema['enum']
+        enum&.map { |option| [option, option] } || []
+      end
+
+      private
+
+      # Defines an array attribute by delegating to the items resolver
+      #
+      # @return [Proc] a lambda that defines the array attribute
+      def define_array_attribute
+        items_resolver = create_items_resolver
+
+        # Get the item type - different resolvers expose this differently
+        item_type = if items_resolver.is_a?(DefinitionsResolver)
+                      # DefinitionsResolver stores type in the resolved definition
+                      items_resolver.send(:local_definition)['type']
+                    else
+                      # BlankRefResolver has it directly in property_schema
+                      items_resolver.property_schema['type']
+                    end
+
+        unless %w[boolean integer string].include?(item_type)
+          raise "Unsupported array item type: #{item_type.inspect} for property '#{property_name}'"
+        end
+
+        # Return a no-op lambda as the serializer will handle casting to an array
+        ->(_object) {}
+      end
+
+      # Creates a resolver for array items by delegating to the registry
+      # This allows arrays to recursively use any resolver (BlankRefResolver, DefinitionsResolver, etc.)
+      #
+      # @return [Base] A resolver instance for the items
+      def create_items_resolver
+        items_schema = property_schema['items'] || {}
+        items_ref = items_schema['$ref'].to_s
 
-        enum.map { |option| [option, option] }
+        # Use the registry to create a resolver for the items schema
+        Registry.resolver_for_schema_hash(items_schema, parent_schema, property_name, items_ref, context)
       end
     end
 

data/lib/structured_store/ref_resolvers/definitions_resolver.rb

@@ -12,10 +12,6 @@ module StructuredStore
         %r{\A#/definitions/}
       end
 
-      def initialize(schema, property_name, ref_string, context = {})
-        super
-      end
-
       # Defines the rails attribute(s) on the given singleton class
       #
       # @return [Proc] a lambda that defines the attribute on the singleton class
@@ -53,7 +49,7 @@ module StructuredStore
       #   resolver.local_definition  # => { "type" => "string" }
       def local_definition
         definition_name = ref_string.sub('#/definitions/', '')
-        local_definition = schema_inspector.definition_schema(definition_name)
+        local_definition = parent_schema.definition_schema(definition_name)
 
         raise "No definition for #{ref_string}" if local_definition.nil?
 

data/lib/structured_store/ref_resolvers/registry.rb

@@ -31,15 +31,30 @@ module StructuredStore
 
         # Returns a resolver instance for the given schema property reference
         #
-        # @param [Hash] schema The JSON schema containing the property reference
+        # @param [SchemaInspector] schema_inspector The JSON schema inspector
         # @param [String, Symbol] property_name The name of the property containing the reference
         # @param [Hash] context Optional context hash (default: {})
         # @return [RefResolver] An instance of the appropriate resolver class for the reference
         # @raise [RuntimeError] If no matching resolver can be found for the reference
         def matching_resolver(schema_inspector, property_name, context = {})
-          ref_string = schema_inspector.property_schema(property_name)['$ref']
+          property_schema = schema_inspector.property_schema(property_name)
+          ref_string = property_schema['$ref'].to_s
 
-          klass_factory(ref_string).new(schema_inspector, property_name, ref_string, context)
+          resolver_for_schema_hash(property_schema, schema_inspector, property_name, ref_string, context)
+        end
+
+        # Returns a resolver instance for a schema hash (e.g., array items)
+        # Direct method that doesn't require looking up properties
+        #
+        # @param [Hash] schema_hash The schema hash (with potential $ref)
+        # @param [SchemaInspector] parent_schema Parent schema for definition lookups
+        # @param [String] property_name The property name for error messages
+        # @param [String] ref_string The $ref string
+        # @param [Hash] context Optional context hash (default: {})
+        # @return [RefResolver] An instance of the appropriate resolver class
+        def resolver_for_schema_hash(schema_hash, parent_schema, property_name, ref_string, context = {})
+          klass = klass_factory(ref_string)
+          klass.new(schema_hash, parent_schema, property_name, ref_string, context)
         end
 
         private

data/lib/structured_store/version.rb

@@ -1,3 +1,3 @@
 module StructuredStore
-  VERSION = '0.1.0'.freeze
+  VERSION = '1.0.0'.freeze
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: structured_store
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Tim Gentry
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-07-01 00:00:00.000000000 Z
+date: 2025-11-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json_schemer
@@ -88,6 +89,7 @@ metadata:
   source_code_uri: https://github.com/HealthDataInsight/structured_store.git
   changelog_uri: https://github.com/HealthDataInsight/structured_store.git/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -102,7 +104,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.3.26
+signing_key:
 specification_version: 4
 summary: Store JSON structured using versioned JSON Schemas.
 test_files: []