attr_json Documentation

AttrJson is designed for scenarios where you want to access complex, structured data in an object-oriented fashion without creating a highly normalized RDBMS schema.

Use cases include:

• Complex Data Structures: When you need to avoid complicated normalized schemas but still want to interact with data as objects.
• Single-Table Inheritance (STI): When subclasses have non-shared data fields that would otherwise require many sparse columns in a single table.
• Content Management Systems (CMS): When you need varied, plugin-driven, or configuration-dependent structured data that doesn't require heavy relational querying.
• Model Versioning: When you want to minimize associations by inlining complex data into a single table row to simplify versioning.
• Hybrid Document Store: When you want to treat PostgreSQL as a simple object-oriented document store while still maintaining standard RDBMS features like foreign keys and associations on the same row.

When to avoid AttrJson:

• If you require sophisticated querying, reporting, or high performance on complex data, a traditional normalized RDBMS schema is preferred over jsonb.

You can represent complex, object-oriented data structures within a single jsonb column by using AttrJson::Model. This mix-in allows you to define models that can be nested (singly or as arrays) to any depth. These models can be used as types for an AttrJson::Record via the .to_type method.

Key features:

• Round-trip serialization: Complex graphs of models are serialized to JSON and reconstructed as model instances upon retrieval.
• Nested updates: You can edit nested model attributes "in place" (e.g., m.nested_model.attr = value) and they will be properly saved.
• Validation: Validations defined within an AttrJson::Model work and errors are posted up to the parent AttrJson::Record.
• Form Support: For Rails forms, use include AttrJson::NestedAttributes and attr_json_accepts_nested_attributes_for to enable behavior similar to Rails' accepts_nested_attributes_for.

class LangAndValue
  include AttrJson::Model

  attr_json :lang, :string, default: "en"
  attr_json :value, :string

  validates :lang, inclusion: %w[en es fr]
end

class MyModel < ActiveRecord::Base
  include AttrJson::Record
  include AttrJson::Record::QueryScopes

  # Single nested model
  attr_json :lang_and_value, LangAndValue.to_type

  # Array of nested models
  attr_json :lang_and_value_array, LangAndValue.to_type, array: true
end

# Usage
m = MyModel.new(lang_and_value: { lang: 'fr', value: "S'il vous plaît" })
m.save!

# In-place update
m.lang_and_value.lang = "de"
m.save!

Handling an array of primitive types (like strings) in Rails forms is non-standard. To ensure values are submitted and updated correctly, use the multiple: true option on text fields.

Handling Empty Arrays: If JavaScript removes all elements from an array, Rails may not send any parameters for that attribute, preventing it from being cleared. To fix this, use a hidden field with the _attributes suffix. If you use attr_json_accepts_nested_attributes_for on the attribute, it will automatically filter out empty strings sent by the hidden field.

Recommendation: If the logic becomes too complex, consider wrapping your primitives in an AttrJson::Model with a single attribute to use standard nested attribute patterns.

# Model
attr_json :string_array, :string, array: true

<%# Using a hidden field to ensure empty arrays are handled correctly %>
<%= f.hidden_field "string_array_attributes[]", "" %>
<%= f.input :string_array_attributes do %>
    <% f.object.string_array.each do |str| %>
        <%= f.text_field(:string_array_attributes, value: str, class: "form-control", multiple: true) %>
    <% end %>
<% end %>

To treat nested or compound AttrJson::Model objects as if they were Rails associations in forms, you must follow these steps:

1. Include AttrJson::NestedAttributes in your main AttrJson::Record model.
2. Include AttrJson::Model in your nested model classes.
3. Use attr_json_accepts_nested_attributes_for instead of the standard Rails accepts_nested_attributes_for.

attr_json_accepts_nested_attributes_for always includes allow_destroy. It is recommended to use the reject_if: :all_blank option to ignore empty hashes.

Build Methods: Including AttrJson::NestedAttributes automatically adds Rails-style build_ methods (e.g., build_one_event) for your attributes. You can disable this by passing define_build_method: false to attr_json_accepts_nested_attributes_for.

Strong Params: You must handle strong parameters for nested attributes manually, following the same pattern used for standard Rails associations.

class Event
  include AttrJson::Model
  attr_json :name
  attr_json :datetime
end

class MyRecord < ActiveRecord::Base
  include AttrJson::Record
  include AttrJson::NestedAttributes

  attr_json :one_event, Event.to_type
  attr_json :many_events, Event.to_type, array: true

  attr_json_accepts_nested_attributes_for :one_event, :many_events, reject_if: :all_blank
end

<%# In a form template %>
<%= form_for(record) do |f|
  <%= f.fields_for :one_event do |one_event_f|
    <%= one_event_f.text_field :name %>
    <%= one_event_f.datetime_field :datetime %>
  <% end %>

  <%= f.fields_for :many_events do |many_events_f|
    <%= many_events_f.text_field :name %>
    <%= many_events_f.datetime_field :datetime %>
  <% end %>
<% end %>

The AttrJson::Type::Model class is an ActiveModel::Type::Value implementation designed to map JSON data to nested AttrJson::Model objects. It manages the lifecycle of data between a database-friendly serializable hash and a rich Ruby model object.

Casting Behavior

When calling cast(v), the type attempts to convert the input into an instance of the configured AttrJson::Model class:

• If v is already an instance of the model, it is returned as-is.
• If v responds to to_hash or to_h, it initializes a new model instance using that hash.
• If the model's configuration bad_cast is set to :as_nil, it returns nil for non-castable values. Otherwise, it raises an AttrJson::Type::Model::BadCast error.

Serialization and Deserialization

• serialize(v): Converts a model instance (or a castable value) into a serializable hash using v.serializable_hash(strip_nils: strip_nils). This is used when saving data to the database.
• deserialize(v): Converts a serializable hash (from the database) back into a model instance using model.new_from_serializable(v.to_hash).

Nil Handling during Serialization

The strip_nils option controls how nil values are treated when converting the model to a hash. This value is passed to AttrJson::Model#serialized_hash.