json-typed-attributes

name	json-typed-attributes
description	Define typed attributes backed by JSON fields in Rails models. Use when models need flexible data storage with type casting, validations, and form integration. Supports integer, decimal, string, text, boolean, date, and array types.

JSON Typed Attributes

This skill helps you work with JSON-backed attributes in Rails models using the StoreJsonAttributes concern. It provides type casting, validation support, and seamless form integration.

When to Use

• You need flexible data storage without creating separate database columns
• You want to store structured data (like configuration, metadata, or dynamic fields) in a JSON column
• You need proper type casting for JSON attributes (numbers, dates, booleans, arrays)
• You want to validate JSON-backed attributes like regular ActiveRecord attributes
• You need JSON attributes to work seamlessly with Rails forms

Setup

1. Ensure JSON Column Exists

Your model must have a JSON column to store the attributes. Common names are data, metadata, or settings:

# In migration
add_column :table_name, :data, :jsonb, default: {}

2. Include the Concern

class YourModel < ApplicationRecord
  include StoreJsonAttributes
end

3. Define Typed Attributes

Use store_typed_attributes to define attributes with automatic type casting:

store_typed_attributes [:attribute_name], type: :type_name, field: :json_column_name

Supported Types

String

store_typed_attributes %i[timeline status], type: :string, field: :data

• Casts values to strings
• Returns nil for blank values
• Example usage:

  record.timeline = "30 Days"
  record.timeline # => "30 Days"
  

Integer

store_typed_attributes %i[age count quantity], type: :integer, field: :data

• Casts values to integers
• Automatically strips commas and spaces from input ("1,000" → 1000)
• Returns nil for invalid values
• Example usage:

  record.quantity = "1,500"
  record.quantity # => 1500
  

Decimal

store_typed_attributes %i[price revenue percentage], type: :decimal, field: :data

• Casts values to BigDecimal
• Automatically strips commas and spaces from input
• Preserves precision
• Example usage:

  record.price = "1,234.56"
  record.price # => BigDecimal("1234.56")
  

Boolean

store_typed_attributes %i[active enabled verified], type: :boolean, field: :data

• Creates predicate methods (ending in ?)
• Casts truthy/falsy values correctly
• Example usage:

  record.active = "1"
  record.active? # => true
  
  record.active = "0"
  record.active? # => false
  

Date

store_typed_attributes %i[started_at completed_at], type: :date, field: :data

• Casts strings to Date objects
• Handles various date formats
• Example usage:

  record.started_at = "2026-02-04"
  record.started_at # => Date object
  record.started_at.strftime("%B %d, %Y") # => "February 04, 2026"
  

Array

store_typed_attributes %i[categories tags], type: :array, field: :data

• Always returns an array (empty array if nil)
• Automatically removes blank values with compact_blank
• Example usage:

  record.categories = ["Revenue Generation", "Operations Management"]
  record.categories # => ["Revenue Generation", "Operations Management"]
  
  record.categories = ["", "Valid", nil, "Another"]
  record.categories # => ["Valid", "Another"]
  

Text

store_typed_attributes %i[notes description], type: :text, field: :data

• Similar to string but intended for longer content
• Creates predicate method (ending in ?)
• Example usage:

  record.notes = "Long text content..."
  record.notes? # => true (if present)
  

Complete Example

# frozen_string_literal: true

class CBPComponents::KeyQuestion < CoreBusinessPresentationComponent
  CATEGORIES = [
    'Revenue Generation',
    'Operations Management',
    'Organizational Development',
    'Financial Management',
    'Ministry',
    'Personal Issue',
  ].freeze

  TIMELINES = ['30 Days', '90 Days', '180 Days', '1 Year', 'More than 1 Year'].freeze

  # Define JSON-backed typed attributes
  store_typed_attributes %i[timeline], type: :string, field: :data
  store_typed_attributes %i[categories], type: :array, field: :data

  # Add validations like any other attribute
  validates :timeline, inclusion: { in: TIMELINES, allow_blank: true }
  validates :categories, inclusion: { in: CATEGORIES }, allow_blank: true

  # Use in strong parameters
  private

  def base_params
    super.concat([:timeline, :summary, categories: []])
  end
end

Working with Forms

JSON-backed attributes work seamlessly with Rails form helpers:

Simple Fields

= form.text_field :timeline
= form.number_field :quantity
= form.check_box :active

Array Fields (Checkboxes)

- CATEGORIES.each do |category|
  = form.check_box :categories,
    { multiple: true, checked: form.object.categories.include?(category) },
    category,
    nil
  = category

Select Fields

= form.select :timeline,
  options_for_select(TIMELINES, form.object.timeline),
  { include_blank: "Select timeline" }

Adding Validations

Validate JSON-backed attributes like regular attributes:

# Presence
validates :timeline, presence: true

# Inclusion
validates :timeline, inclusion: { in: TIMELINES }

# Length
validates :categories, length: { minimum: 1, message: "must select at least one" }

# Custom validation
validate :categories_must_be_valid

private

def categories_must_be_valid
  invalid_categories = categories - CATEGORIES
  if invalid_categories.any?
    errors.add(:categories, "contains invalid categories: #{invalid_categories.join(', ')}")
  end
end

# Numericality
validates :quantity, numericality: { greater_than: 0, allow_nil: true }

# Format
validates :status, format: { with: /\A[A-Z][a-z]+\z/, allow_blank: true }

Strong Parameters

Always include JSON-backed attributes in your strong parameters:

# For simple types (string, integer, decimal, boolean, date)
params.require(:model).permit(:timeline, :quantity, :active, :started_at)

# For arrays, use array syntax
params.require(:model).permit(:timeline, categories: [])

Multiple JSON Fields

You can use different JSON fields for different concerns:

class Product < ApplicationRecord
  # Pricing data
  store_typed_attributes %i[base_price discount_percentage], type: :decimal, field: :pricing_data

  # Inventory data
  store_typed_attributes %i[quantity threshold], type: :integer, field: :inventory_data

  # Feature flags
  store_typed_attributes %i[featured new_arrival on_sale], type: :boolean, field: :flags
end

Common Patterns

Constants for Validation

Define constants for valid values:

STATUSES = %w[pending approved rejected].freeze
PRIORITIES = %w[low medium high urgent].freeze

store_typed_attributes %i[status], type: :string, field: :data
store_typed_attributes %i[priority], type: :string, field: :data

validates :status, inclusion: { in: STATUSES, allow_blank: true }
validates :priority, inclusion: { in: PRIORITIES, allow_blank: true }

Default Values

Set defaults in initializer or after_initialize:

after_initialize :set_defaults, if: :new_record?

private

def set_defaults
  self.categories ||= []
  self.timeline ||= '90 Days'
  self.active = true if active.nil?
end

Scopes and Queries

Query JSON attributes using PostgreSQL JSON operators:

# Find records with specific value
scope :with_timeline, ->(timeline) {
  where("data->>'timeline' = ?", timeline)
}

# Find records where array contains value
scope :with_category, ->(category) {
  where("data->'categories' ? :category", category: category)
}

# Find records with any of multiple values
scope :with_any_category, ->(categories) {
  where("data->'categories' ?| array[:categories]", categories: categories)
}

Best Practices

1. Always specify the field name - Makes it clear where data is stored

   store_typed_attributes %i[timeline], type: :string, field: :data
   

2. Use arrays for multi-select data - Automatically handles blank values

   store_typed_attributes %i[categories], type: :array, field: :data
   

3. Define constants for valid values - Makes validations and forms easier

   TIMELINES = ['30 Days', '90 Days', '180 Days'].freeze
   validates :timeline, inclusion: { in: TIMELINES, allow_blank: true }
   

4. Add validations - JSON attributes should be validated like any other attribute

   validates :quantity, numericality: { greater_than: 0, allow_nil: true }
   

5. Use appropriate types - Choose the type that matches your data

   • Use :decimal for money/percentages (not :integer)
   • Use :array for multi-select (automatically removes blanks)
   • Use :boolean for flags (creates predicate methods)

6. Include in strong parameters - Don't forget array syntax for array types

   params.require(:model).permit(:timeline, categories: [])
   

7. Consider indexing - For frequently queried JSON attributes, add GIN indexes

   add_index :table_name, :data, using: :gin
   

Troubleshooting

Attribute not persisting

• Ensure the JSON column exists in the database
• Check that the field name matches: field: :data
• Verify strong parameters include the attribute

Type casting not working

• Verify the type is spelled correctly: :integer, :decimal, :string, etc.
• For arrays, ensure you're setting an array value
• For booleans, use the predicate method: record.active?

Form not displaying correct values

• For arrays, check that you're using multiple: true and checking inclusion
• For selects, use options_for_select with the current value
• Ensure the getter method returns the expected type

Validation failing

• Check that the attribute is included in strong parameters
• Verify constants match the expected values exactly
• For arrays, remember blank values are automatically removed