structured_store 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5e104dd0bcd9069ad670b176be0ad3e56231f8a2a02b2237b9d76cd8e1504302
+  data.tar.gz: b14d540d205c843a34355444f0893b7190c7df870d616c07357bb484e23105ad
+SHA512:
+  metadata.gz: f946faaa8dc5fa672e765f6a9b5261f499b12c164324e8df7144d3a821009f5dbdb4b3c572d1dc4903578ae20a5802f4f7d0f42d52fd7125a36e445e86357f45
+  data.tar.gz: eae79479eff4abc7a24ac1966f76b24d6b4b8ede45e00d899136f93fec3f714ec4e4e9afe33362c386f9289db6b87dd46ca64c6fa98b54dd4b28788411773ff7

data/MIT-LICENSE

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

data/README.md

@@ -0,0 +1,381 @@
+# StructuredStore
+
+StructuredStore is a Ruby gem designed for Rails applications that provides a robust system for managing JSON data using versioned JSON schemas. The library enables developers to store structured data in a JSON database column while maintaining strict schema validation through the json_schemer gem.
+
+It features a VersionedSchema model that tracks different versions of JSON schemas using semantic versioning, and a Storable concern that can be included in ActiveRecord models to automatically define accessor methods for schema properties. The gem supports schema evolution by allowing multiple versions of the same schema to coexist, making it ideal for applications that need to maintain backward compatibility while evolving their data structures.
+
+With a built-in Rails generator for reliable setup and dynamic property resolution through a configurable resolver registry, StructuredStore simplifies the management of complex, schema-validated JSON data in database applications.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "structured_store"
+```
+
+And then execute:
+
+```bash
+bundle
+```
+
+Or install it yourself as:
+
+```bash
+gem install structured_store
+```
+
+## Usage
+
+StructuredStore provides a robust way to manage JSON data with versioned schemas in Rails applications. Here's how to use it:
+
+### Basic Setup
+
+After installation, create the necessary database tables:
+
+```bash
+$ 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.
+
+### 1. Creating a JSON Schema
+
+First, define your JSON schema by creating a JSON file in the `db/structured_store_versioned_schemas/` directory. The file should be named using the pattern `{name}-{version}.json`.
+
+Create `db/structured_store_versioned_schemas/UserPreferences-1.0.0.json`:
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2019-09/schema",
+  "type": "object",
+  "properties": {
+    "theme": {
+      "type": "string",
+      "description": "User interface theme preference"
+      "examples": ["light", "dark", "system"]
+    },
+    "notifications": {
+      "type": "boolean",
+      "description": "Whether user notifications are enabled"
+    },
+    "language": {
+      "type": "string",
+      "description": "Preferred language"
+    }
+  },
+  "required": ["theme"],
+  "additionalProperties": false
+}
+```
+
+Then create a migration to install the schema:
+
+```ruby
+# Generate a new migration
+$ rails generate migration InstallUserPreferencesSchema
+
+# Edit the migration file
+class InstallUserPreferencesSchema < ActiveRecord::Migration[7.0]
+  include StructuredStore::MigrationHelper
+
+  def change
+    create_versioned_schema("UserPreferences", "1.0.0")
+  end
+end
+```
+
+Run the migration:
+
+```bash
+$ rails db:migrate
+```
+
+### 2. Creating a Model with Structured Storage
+
+Create a model that includes the `StructuredStore::Storable` concern:
+
+```ruby
+# app/models/user_preference.rb
+class UserPreference < ApplicationRecord
+  include StructuredStore::Storable
+end
+```
+
+Generate and run a migration for your model:
+
+```ruby
+# db/migrate/xxx_create_user_preferences.rb
+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.timestamps
+    end
+  end
+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:
+
+```ruby
+# Find the latest version of your schema
+schema = StructuredStore::VersionedSchema.latest("UserPreferences")
+
+# Create a new record
+preference = UserPreference.create!(
+  versioned_schema: schema,
+  theme: "dark",
+  notifications: false,
+  language: "es"
+)
+
+# Access the structured data
+preference.theme         # => "dark"
+preference.notifications # => false
+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"}
+```
+
+### 4. Schema Versioning
+
+StructuredStore supports schema evolution. You can create new versions of your schema by adding new JSON files and creating migrations to install them.
+
+Create `db/structured_store_versioned_schemas/UserPreferences-1.1.0.json`:
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2019-09/schema",
+  "type": "object",
+  "properties": {
+    "theme": {
+      "type": "string",
+      "description": "User interface theme preference",
+      "examples": ["light", "dark", "system"]
+    },
+    "notifications": {
+      "type": "boolean", 
+      "description": "Whether user notifications are enabled"
+    },
+    "language": {
+      "type": "string",
+      "description": "Preferred language"
+    },
+    "timezone": {
+      "type": "string",
+      "description": "User's timezone"
+    }
+  },
+  "required": ["theme"],
+  "additionalProperties": false
+}
+```
+
+Create a migration to install the new schema version:
+
+```ruby
+class InstallUserPreferencesSchemaV110 < ActiveRecord::Migration[7.0]
+  include StructuredStore::MigrationHelper
+
+  def change
+    create_versioned_schema("UserPreferences", "1.1.0")
+  end
+end
+```
+
+Existing records continue to work with their original schema, while new records can use the latest version:
+
+```ruby
+# Get the latest schema version
+latest_schema = StructuredStore::VersionedSchema.latest("UserPreferences")
+
+# Create a record with the new schema
+new_preference = UserPreference.create!(
+  versioned_schema: latest_schema,
+  theme: "system",
+  timezone: "America/New_York"
+)
+
+new_preference.timezone # => "America/New_York"
+```
+
+### 5. Schema Validation
+
+All data is automatically validated against the associated JSON schema:
+
+```ruby
+preference = UserPreference.new(versioned_schema: schema)
+
+# This will fail validation because 'theme' is required
+preference.valid? # => false
+
+# This will pass validation
+preference.theme = "light"
+preference.valid? # => true
+
+# Invalid data types are rejected
+preference.notifications = "invalid" # Will cause validation error
+```
+
+### 6. 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.
+
+#### Using Date Ranges
+
+To use date ranges, define a property in your JSON schema with the custom reference:
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2019-09/schema",
+  "type": "object",
+  "properties": {
+    "event_period": {
+      "$ref": "external://structured_store/json_date_range/"
+    }
+  }
+}
+```
+
+Then implement a `date_range_converter` method in your model and require the optional `JsonDateRangeResolver`:
+
+```ruby
+require 'structured_store/ref_resolvers/defaults'
+require 'structured_store/ref_resolvers/json_date_range_resolver'
+
+class EventRecord < ApplicationRecord
+  include StructuredStore::Storable
+  
+  def date_range_converter
+    @date_range_converter ||= StructuredStore::Converters::ChronicDateRangeConverter.new
+  end
+end
+```
+
+If you choose to use the `ChronicDateRangeConverter`, you will also need to add `chronic` to your application's Gemfile.
+
+#### Working with Date Range Data
+
+```ruby
+# Create a record with a natural language date range
+event = EventRecord.create!(
+  versioned_schema: schema,
+  event_period: "January 2024"
+)
+
+# The converter transforms this to structured data internally
+event.store['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
+event.event_period # => "Jan 2024"
+
+# Other date range examples
+event.update!(event_period: "between 1st and 15th January 2024")
+event.update!(event_period: "2024") # Full year
+```
+
+#### Using Alternative Converters
+
+The `ChronicDateRangeConverter` is the default, but you can implement custom converters that respond to `convert_to_dates` and `convert_to_string`:
+
+```ruby
+class CustomDateRangeConverter
+  def convert_to_dates(value)
+    # 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
+  end
+end
+
+class MyModel < ApplicationRecord
+  include StructuredStore::Storable
+  
+  def date_range_converter
+    @date_range_converter ||= CustomDateRangeConverter.new
+  end
+end
+```
+
+### 7. Finding and Querying Schemas
+
+```ruby
+# Find the latest version of a schema
+latest = StructuredStore::VersionedSchema.latest("UserPreferences")
+
+# Find a specific version
+specific = StructuredStore::VersionedSchema.find_by(name: "UserPreferences", version: "1.0.0")
+
+# Get all versions of a schema
+all_versions = StructuredStore::VersionedSchema.where(name: "UserPreferences")
+                                               .order(:version)
+```
+
+### 8. 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\//
+  end
+
+  def define_attribute
+    lambda do |instance|
+      # Define custom attribute behavior
+    end
+  end
+end
+
+# Register your custom resolver
+CustomResolver.register
+```
+
+### 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.
+
+2. **Use migrations for schema management**: Always use the `StructuredStore::MigrationHelper` and migrations to install schemas. This ensures proper version control and rollback capabilities.
+
+3. **Organize schema files consistently**: Keep your JSON schema files in `db/structured_store_versioned_schemas/` with clear naming: `{SchemaName}-{version}.json`.
+
+4. **Plan for backward compatibility**: When creating new schema versions, consider how existing data will be handled.
+
+5. **Use meaningful schema names**: Choose descriptive names for your schemas that indicate their purpose.
+
+6. **Validate your JSON schemas**: Test your JSON schema files before creating migrations to ensure they're valid.
+
+7. **Document your schemas**: Include clear descriptions for all properties in your JSON schemas.
+
+8. **JSON schema defaults**: Given the attribute lifecycle, StructuredStore does not support JSON Schema property defaults.
+
+9. **Version control schema files**: Keep your `.json` schema files in version control alongside your migrations.
+
+10. **Test schema migrations**: Always test your schema installation migrations in development before deploying to production.
+
+## 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).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the structured_store project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/HealthDataInsight/structured_store/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,22 @@
+require 'bundler/setup'
+
+APP_RAKEFILE = File.expand_path('test/dummy/Rakefile', __dir__)
+load 'rails/tasks/engine.rake'
+
+load 'rails/tasks/statistics.rake'
+
+require 'bundler/gem_tasks'
+require 'ndr_dev_support/tasks'
+require 'rubocop/rake_task'
+
+# Running tests via rail will ensure that the dummy app tests are run
+namespace :test do
+  desc 'Run tests via Rails'
+  task :via_rails do
+    system('bin/rails test')
+  end
+end
+
+# Override the default rake test task
+desc 'Rake test will run tests via Rails'
+task test: 'test:via_rails'

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

@@ -0,0 +1,82 @@
+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.
+  module Storable
+    extend ActiveSupport::Concern
+
+    included do
+      after_initialize :define_store_accessors!
+
+      belongs_to :versioned_schema, # rubocop:disable Rails/InverseOf
+                 class_name: 'StructuredStore::VersionedSchema',
+                 foreign_key: 'structured_store_versioned_schema_id'
+
+      delegate :json_schema, to: :versioned_schema
+    end
+
+    # Dynamically define accessors for the properties defined in the
+    # JSON schema that this record has.
+    #
+    # 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?
+
+      singleton_class.store_accessor(:store, json_schema_properties.keys)
+
+      property_resolvers.each_value do |resolver|
+        resolver.define_attribute.call(self)
+      end
+    end
+
+    # Returns an array of property resolvers for each property in the JSON schema.
+    # 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,
+                                                                  property_name)
+      end
+    end
+
+    private
+
+    # Returns a SchemaInspector instance for the current JSON schema.
+    def schema_inspector
+      @schema_inspector ||= StructuredStore::SchemaInspector.new(json_schema)
+    end
+
+    # Retrieves the properties from the JSON schema
+    #
+    # @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', {})
+    end
+
+    # Returns true if there is sufficient information to define accessors for this audit_store,
+    # 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')
+        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}"
+        return false
+      end
+
+      true
+    end
+  end
+end

data/app/models/structured_store/versioned_schema.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module StructuredStore
+  # This model stores individual versions of each structured store schema
+  class VersionedSchema < ApplicationRecord
+    validates :json_schema, json_schema: { allow_blank: true, schema: :draft201909 }
+    validates :name, presence: true, uniqueness: { scope: :version, case_sensitive: true }
+    validates :version, presence: true, format: { with: Gem::Version::ANCHORED_VERSION_PATTERN }
+
+    store_accessor :json_schema, :definitions, :properties
+
+    def self.table_name_prefix
+      'structured_store_'
+    end
+
+    def self.latest(name)
+      schemas = where(name: name)
+
+      # Return nil if no schemas with this name exist
+      return nil if schemas.empty?
+
+      # Sort by version using gem_version and return the last one (highest version)
+      schemas.max_by(&:gem_version)
+    end
+
+    def json_schema=(json)
+      case json
+      when String
+        super(JSON.parse(json))
+      else
+        super
+      end
+    end
+
+    def gem_version
+      Gem::Version.new(version)
+    end
+  end
+end

data/app/validators/json_schema_validator.rb

@@ -0,0 +1,49 @@
+require 'json_schemer'
+
+# This Rails validator checks that an attribute is either a valid JSON schema
+# or that it complies with a given schema.
+class JsonSchemaValidator < ActiveModel::EachValidator
+  NAMED_SCHEMA_VERSIONS = %i[draft201909 draft202012 draft4 draft6 draft7 openapi30 openapi31].freeze
+
+  def validate_each(record, attribute, value)
+    # 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
+
+    # Initialize JSONSchemer with proper handling based on schema type
+    schemer = json_schemer(schema)
+
+    # Collect validation errors
+    validation_errors = schemer.validate(json_data).to_a
+
+    # Add errors to the record using json_schemer's built-in I18n support
+    validation_errors.each do |error|
+      record.errors.add(attribute, error['error'])
+    end
+  rescue JSON::ParserError
+    record.errors.add(attribute, :invalid_json)
+  end
+
+  private
+
+  # Converts given schema to a JSONSchemer::Schema object.
+  #
+  # Accepts either a symbol referencing a known schema (e.g. :draft7), a string
+  # or hash representing a schema, or a JSONSchemer::Schema object directly.
+  #
+  # Raises an ArgumentError if schema is in an unsupported format.
+  def json_schemer(schema)
+    case schema
+    when *NAMED_SCHEMA_VERSIONS
+      JSONSchemer.send(schema)
+    when String, Hash
+      JSONSchemer.schema(schema)
+    when JSONSchemer::Schema
+      schema
+    else
+      raise ArgumentError, "Invalid schema format: #{schema.class}"
+    end
+  end
+end

data/lib/structured_store/converters/chronic_date_range_converter.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'chronic'
+
+module StructuredStore
+  module Converters
+    # This class is responsible for converting date ranges to and from a string format.
+    class ChronicDateRangeConverter
+      # Converts a natural language date range string into an array containing start and end dates
+      #
+      # @param value [String] A natural language date range string (e.g., "between 1st and 15th January 2024")
+      # @return [Array<Time>] An array containing two Time objects: [start_date, end_date]
+      # @raise [NoMethodError] If the input string cannot be parsed into a valid date range
+      def convert_to_dates(value)
+        return [nil, nil] if value.blank?
+
+        if /\A\d{4}\z/.match?(value.strip)
+          # If the value is a year, return the start and end of that year
+          year = value.strip.to_i
+          return [Time.new(year, 1, 1), Time.new(year, 12, 31)]
+        end
+
+        parsed_date_range = Chronic.parse(value, endian_precedence: :little, guess: false)
+
+        [parsed_date_range&.begin, parsed_date_range&.end&.days_ago(1)]
+      end
+
+      # Formats two dates into a human readable date range string
+      #
+      # @param date1 [Date] The start date of the range
+      # @param date2 [Date] The end date of the range
+      # @return [String] A formatted date range string in one of these formats:
+      #   - "D MMM YYYY" (when dates are equal)
+      #   - "MMM YYYY" (when dates span a full month in the same year)
+      #   - "YYYY" (when dates span a full year)
+      #   - "D MMM YYYY to D MMM YYYY" (for all other date ranges)
+      # @example
+      #   convert_to_string(Date.new(2023,1,1), Date.new(2023,1,1)) #=> "1 Jan 2023"
+      #   convert_to_string(Date.new(2023,1,1), Date.new(2023,1,31)) #=> "Jan 2023"
+      #   convert_to_string(Date.new(2023,1,1), Date.new(2023,12,31)) #=> "2023"
+      #   convert_to_string(Date.new(2023,1,1), Date.new(2023,2,1)) #=> "1 Jan 2023 to 1 Feb 2023"
+      def convert_to_string(date1, date2)
+        return format_single_date(date1) if date1 == date2
+        return format_full_month(date1) if full_month_range?(date1, date2)
+        return format_full_year(date1) if full_year_range?(date1, date2)
+
+        format_date_range(date1, date2)
+      end
+
+      private
+
+      # Formats a single date
+      def format_single_date(date)
+        date.strftime('%e %b %Y').strip
+      end
+
+      # Formats a full month
+      def format_full_month(date)
+        date.strftime('%b %Y')
+      end
+
+      # Formats a full year
+      def format_full_year(date)
+        date.strftime('%Y')
+      end
+
+      # Formats a date range
+      def format_date_range(date1, date2)
+        "#{date1.strftime('%e %b %Y').strip} to #{date2.strftime('%e %b %Y').strip}"
+      end
+
+      # Checks if the date range spans a full month
+      def full_month_range?(date1, date2)
+        date1.year == date2.year &&
+          date1.month == date2.month &&
+          date1 == date1.beginning_of_month &&
+          date2 == date2.end_of_month
+      end
+
+      # Checks if the date range spans a full year
+      def full_year_range?(date1, date2)
+        date1.year == date2.year &&
+          date1 == date1.beginning_of_year &&
+          date2 == date2.end_of_year
+      end
+    end
+  end
+end

data/lib/structured_store/engine.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# This defines the StructuredStore engine for Rails.
+module StructuredStore
+  class Engine < ::Rails::Engine
+  end
+end

data/lib/structured_store/generators/install_generator.rb

@@ -0,0 +1,41 @@
+require 'rails/generators'
+require 'rails/generators/base'
+
+module StructuredStore
+  module Generators
+    # This generator creates a migration for the structured store versioned schemas table
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Creates a migration for the structured store tables'
+
+      # This method is required when including Rails::Generators::Migration
+      def self.next_migration_number(_dirname)
+        Time.now.utc.strftime('%Y%m%d%H%M%S')
+      end
+
+      def create_migration_file
+        migration_template 'create_structured_store.rb', 'db/migrate/create_structured_store.rb'
+      end
+
+      def create_schemas_directory
+        directory_path = 'db/structured_store_versioned_schemas'
+        keep_file_path = File.join(directory_path, '.keep')
+
+        # Create the directory if it doesn't exist
+        empty_directory directory_path
+
+        # Create the .keep file
+        create_file keep_file_path
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::Migration.current_version}]"
+      end
+    end
+  end
+end

data/lib/structured_store/generators/templates/create_structured_store.rb.tt

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# This migration creates the underlying table for the structured store
+class CreateStructuredStore < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :structured_store_versioned_schemas do |t|
+      t.string :name, null: false
+      t.string :version, null: false
+      t.json :json_schema
+
+      t.timestamps
+    end
+
+    # Add a unique index on the combination of name and version in versioned_schemas
+    add_index :structured_store_versioned_schemas, %i[name version], unique: true
+  end
+end

data/lib/structured_store/migration_helper.rb

@@ -0,0 +1,21 @@
+module StructuredStore
+  # Helper method for creating versioned schemas
+  module MigrationHelper
+    def create_versioned_schema(name, version)
+      reversible do |dir|
+        dir.up do
+          json_schema_string = Rails.root.join("db/structured_store_versioned_schemas/#{name}-#{version}.json").read
+          json_schema = JSON.parse(json_schema_string)
+          ::StructuredStore::VersionedSchema.create(
+            name: name,
+            version: version,
+            json_schema: json_schema
+          )
+        end
+        dir.down do
+          ::StructuredStore::VersionedSchema.where(name: name, version: version).destroy_all
+        end
+      end
+    end
+  end
+end

data/lib/structured_store/ref_resolvers/base.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module StructuredStore
+  module RefResolvers
+    # This is the base class for all JSON Schema $ref resolvers.
+    class Base
+      attr_reader :context,
+                  :property_name,
+                  :ref_string,
+                  :schema_inspector
+
+      class << self
+        def matching_ref_pattern
+          raise NotImplementedError, 'Subclasses must implement the matching_ref_pattern method'
+        end
+
+        def register
+          StructuredStore::RefResolvers::Registry.register(self)
+        end
+
+        def unregister
+          StructuredStore::RefResolvers::Registry.unregister(self)
+        end
+      end
+
+      # 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
+        @property_name = property_name
+        @ref_string = ref_string
+        @context = context
+      end
+
+      # Defines the rails attribute(s) on the given singleton class
+      #
+      # @abstract Subclasses must implement this method
+      # @return [Proc] a lambda that defines the attribute on the singleton class
+      # @raise [NotImplementedError] if the method is not implemented in a subclass
+      def define_attribute
+        raise NotImplementedError, 'Subclasses must implement the define_attribute method'
+      end
+
+      # Returns a two dimensional array of HTML select box options
+      #
+      # This method must be implemented by subclasses to provide specific options
+      # for reference resolution.
+      #
+      # @abstract Subclasses must implement this method
+      # @return [Array<Array>] Array of arrays containing id, value option pairs
+      # @raise [NotImplementedError] if the method is not implemented by a subclass
+      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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'structured_store/ref_resolvers/base'
+
+module StructuredStore
+  # This is the namespace for all reference resolvers used in StructuredStore.
+  module RefResolvers
+    # This class resolves properties where no $ref is defined.
+    class BlankRefResolver < Base
+      def self.matching_ref_pattern
+        /\A\z/
+      end
+
+      # Defines the rails attribute(s) on the given singleton class
+      #
+      # @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']
+
+        unless %w[boolean integer string].include?(type)
+          raise "Unsupported attribute type: #{type.inspect} for property '#{property_name}'"
+        end
+
+        # Define the attribute on the singleton class of the object
+        lambda do |object|
+          object.singleton_class.attribute(property_name, type.to_sym)
+        end
+      end
+
+      # 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
+      #
+      # @return [Array<Array>] Array of arrays containing id, value option pairs
+      def options_array
+        enum = json_property_schema['enum']
+
+        enum.map { |option| [option, option] }
+      end
+    end
+
+    # Register the BlankRefResolver with the registry
+    BlankRefResolver.register
+  end
+end

data/lib/structured_store/ref_resolvers/defaults.rb

@@ -0,0 +1,5 @@
+# This file will require the registry and default resolvers.
+require 'structured_store/ref_resolvers/registry'
+
+require 'structured_store/ref_resolvers/blank_ref_resolver'
+require 'structured_store/ref_resolvers/definitions_resolver'

data/lib/structured_store/ref_resolvers/definitions_resolver.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'structured_store/ref_resolvers/base'
+require 'structured_store/ref_resolvers/registry'
+
+module StructuredStore
+  # This is the namespace for all reference resolvers used in StructuredStore.
+  module RefResolvers
+    # This class resolves $ref strings that point to definitions within the schema.
+    class DefinitionsResolver < Base
+      def self.matching_ref_pattern
+        %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
+      # @raise [RuntimeError] if the property type is unsupported
+      def define_attribute
+        type = local_definition['type']
+
+        unless %w[boolean integer string].include?(type)
+          raise "Unsupported attribute type: #{type.inspect} for property '#{property_name}'"
+        end
+
+        # Define the attribute on the singleton class of the object
+        lambda do |object|
+          object.singleton_class.attribute(property_name, type.to_sym)
+        end
+      end
+
+      # Returns a two dimensional array of options from the 'enum' definition
+      # Each element contains a duplicate of the enum option for both the label and value
+      #
+      # @return [Array<Array>] Array of arrays containing id, value option pairs
+      def options_array
+        enum = local_definition['enum']
+
+        enum.map { |option| [option, option] }
+      end
+
+      private
+
+      # Retrieves a local definition from the schema based on the reference string
+      #
+      # @return [Hash] The local definition hash from the schema's definitions
+      # @raise [RuntimeError] If no definition is found for the given reference string
+      # @example
+      #   resolver.local_definition  # => { "type" => "string" }
+      def local_definition
+        definition_name = ref_string.sub('#/definitions/', '')
+        local_definition = schema_inspector.definition_schema(definition_name)
+
+        raise "No definition for #{ref_string}" if local_definition.nil?
+
+        local_definition
+      end
+    end
+
+    # Register the DefinitionsResolver with the registry
+    DefinitionsResolver.register
+  end
+end

data/lib/structured_store/ref_resolvers/json_date_range_resolver.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'structured_store/ref_resolvers/base'
+
+module StructuredStore
+  # This is the namespace for all reference resolvers used in StructuredStore.
+  module RefResolvers
+    # This class resolves properties where no $ref is defined.
+    class JsonDateRangeResolver < Base
+      def self.matching_ref_pattern
+        %r{\Aexternal://structured_store/json_date_range/}
+      end
+
+      # Defines the rails attribute(s) on the given singleton class
+      #
+      # @return [Proc] a lambda that defines the attribute on the singleton class
+      # @raise [RuntimeError] if the property type is unsupported
+      def define_attribute
+        # Capture the property name in a local variable for closure
+        prop_name = property_name
+        resolver = self
+
+        # Define the attribute on the singleton class of the object
+        lambda do |object|
+          converter = object.date_range_converter
+
+          # Define custom getter and setter methods
+          object.singleton_class.define_method(prop_name) do
+            resolver.send(:cast_stored_value, store, prop_name, converter)
+          end
+
+          object.singleton_class.define_method("#{prop_name}=") do |value|
+            resolver.send(:serialize_value_to_store, self, prop_name, value, converter)
+          end
+        end
+      end
+
+      # Returns an empty array of options for date ranges
+      #
+      # @return [Array<Array>] Array of arrays containing id, value option pairs
+      def options_array
+        []
+      end
+
+      private
+
+      # Casts the stored value from hash to formatted string
+      def cast_stored_value(store_hash, prop_name, converter)
+        stored_value = store_hash&.[](prop_name)
+        return nil if stored_value.blank?
+
+        case stored_value
+        when String
+          stored_value
+        when Hash
+          cast_hash_to_string(stored_value, converter)
+        end
+      end
+
+      # Converts a hash with date1/date2 to a formatted string
+      def cast_hash_to_string(stored_value, converter)
+        return nil unless stored_value['date1']
+
+        date1 = Date.parse(stored_value['date1'])
+        date2 = Date.parse(stored_value['date2'])
+        converter.convert_to_string(date1, date2)
+      end
+
+      # Serializes an input value to the store as a hash
+      def serialize_value_to_store(object, prop_name, value, converter)
+        # Initialize store as empty hash if nil
+        object.store ||= {}
+        return object.store[prop_name] = nil if value.blank?
+
+        date1, date2 = converter.convert_to_dates(value)
+        object.store[prop_name] = {
+          'date1' => date1&.to_fs(:db),
+          'date2' => date2&.to_fs(:db)
+        }
+      end
+    end
+
+    # Register the JsonDateRangeResolver with the registry
+    JsonDateRangeResolver.register
+  end
+end

data/lib/structured_store/ref_resolvers/registry.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module StructuredStore
+  module RefResolvers
+    # This is the registry for JSON Schema $ref resolvers.
+    module Registry
+      class << self
+        # Returns the Hash of registered resolvers
+        # If no resolvers have been registered, returns an empty Hash
+        # @return [Hash] Registered resolvers
+        def resolvers
+          @resolvers || {}
+        end
+
+        # Registers a resolver class with a specific regular expression pattern.
+        #
+        # @param klass [Class] The resolver class to register.
+        # @param regexp [Regexp] The regular expression pattern to match against references.
+        def register(klass)
+          @resolvers ||= {}
+          @resolvers[klass] = klass.matching_ref_pattern
+        end
+
+        # Unregisters a resolver class from the registry
+        #
+        # @param klass [Class] The resolver class to remove from the registry
+        # @return [Class, nil] The removed resolver class or nil if not found
+        def unregister(klass)
+          @resolvers.delete(klass)
+        end
+
+        # Returns a resolver instance for the given schema property reference
+        #
+        # @param [Hash] schema The JSON schema containing the property reference
+        # @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']
+
+          klass_factory(ref_string).new(schema_inspector, property_name, ref_string, context)
+        end
+
+        private
+
+        # Creates a new resolver instance based on the provided reference string
+        #
+        # @param ref_string [String] The $ref string to resolve
+        # @return [Object] An instance of the matching resolver class or NoRefResolver
+        # @raise [RuntimeError] If no matching resolver class is found for the reference string
+        def klass_factory(ref_string)
+          # Find the first registered resolver class that matches the ref_string
+          klass = resolvers.find { |_, regexp| ref_string.to_s.match?(regexp) }&.then { |(klass, _)| klass }
+          return klass if klass
+
+          raise "Error: No matching $ref resolver pattern for #{ref_string.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/structured_store/schema_inspector.rb

@@ -0,0 +1,59 @@
+require 'json_schemer'
+require 'active_support'
+require 'active_support/core_ext/hash'
+
+module StructuredStore
+  # This class inspects a JSON Schema and provides methods to retrieve
+  # property and definition schemas.
+  #
+  # It allows us to abstract away the implementation details of JSONSchemer
+  # and provides a clean interface for working with JSON Schemas.
+  class SchemaInspector
+    MAX_JSON_INPUT_SIZE_BYTES = 1_048_576
+
+    def initialize(schema)
+      @original_schema = schema
+    end
+
+    def valid_schema?
+      JSONSchemer.draft201909.valid?(schema_hash)
+    rescue ArgumentError
+      false
+    end
+
+    def property_schema(property_name)
+      schema_hash.dig('properties', property_name.to_s)
+    end
+
+    def definition_schema(definition_name)
+      schema_hash.dig('definitions', definition_name.to_s)
+    end
+
+    private
+
+    def safe_parse_json(json_string)
+      # Ensure the schema is a valid JSON object
+      if json_string.bytesize > MAX_JSON_INPUT_SIZE_BYTES
+        raise ArgumentError, "Schema size exceeds maximum limit of #{MAX_JSON_INPUT_SIZE_BYTES} bytes"
+      end
+
+      JSON.parse(json_string)
+    rescue JSON::ParserError
+      raise ArgumentError, "Invalid JSON schema: #{json_string.inspect}"
+    end
+
+    def schema_hash
+      @schema_hash =
+        case @original_schema
+        when Hash
+          # TODO: ensure the hash is safe to use (e.g. not too large)
+          @original_schema.deep_stringify_keys
+        when String
+          safe_parse_json(@original_schema)
+        else
+          raise ArgumentError, "Unsupported schema type: #{@original_schema.class}"
+        end
+    end
+    public :schema_hash
+  end
+end

data/lib/structured_store/version.rb

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

data/lib/structured_store.rb

@@ -0,0 +1,18 @@
+require 'structured_store/version'
+require 'zeitwerk'
+
+loader = Zeitwerk::Loader.for_gem
+
+# Avoid loading default resolvers by default
+loader.ignore("#{__dir__}/structured_store/ref_resolvers/defaults.rb")
+
+loader.setup
+
+require 'structured_store/engine'
+require 'structured_store/generators/install_generator' if defined?(Rails::Generators)
+require 'structured_store/ref_resolvers/defaults'
+
+# This module serves as a namespace for the StructuredStore gem
+module StructuredStore
+  # Your code goes here...
+end

data/lib/tasks/structured_store_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :structured_store do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification
+name: structured_store
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tim Gentry
+bindir: bin
+cert_chain: []
+date: 2025-07-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json_schemer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+description: StructuredStore is a gem for managing JSON data with versioned schemas.
+email:
+- 52189+timgentry@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/models/concerns/structured_store/storable.rb
+- app/models/structured_store/versioned_schema.rb
+- app/validators/json_schema_validator.rb
+- lib/structured_store.rb
+- lib/structured_store/converters/chronic_date_range_converter.rb
+- lib/structured_store/engine.rb
+- lib/structured_store/generators/install_generator.rb
+- lib/structured_store/generators/templates/create_structured_store.rb.tt
+- lib/structured_store/migration_helper.rb
+- lib/structured_store/ref_resolvers/base.rb
+- lib/structured_store/ref_resolvers/blank_ref_resolver.rb
+- lib/structured_store/ref_resolvers/defaults.rb
+- lib/structured_store/ref_resolvers/definitions_resolver.rb
+- lib/structured_store/ref_resolvers/json_date_range_resolver.rb
+- lib/structured_store/ref_resolvers/registry.rb
+- lib/structured_store/schema_inspector.rb
+- lib/structured_store/version.rb
+- lib/tasks/structured_store_tasks.rake
+homepage: https://github.com/HealthDataInsight/structured_store
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/HealthDataInsight/structured_store
+  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'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Store JSON structured using versioned JSON Schemas.
+test_files: []