JSON Method Standardization Guide

Overview

This guide documents the standardized JSON processing methods across all models in the ODAPI project. All models use consistent method names and implementations via the JsonUpdatable concern.

Standardized Methods

Instance Methods

update_from_json(json_data, options = {})

Updates existing model instances from JSON data.

# Basic usage
company.update_from_json(json_data)

# With options
company.update_from_json(json_data, autosave: true)
company.update_from_json(json_data, autosave: false)

Options:

• autosave: true/false - Whether to automatically save after updating
• include_id: true/false - Whether to include ID in processing
• merge: Hash - Additional attributes to merge

Class Methods

build_from_json(json_data, options = {})

Creates new model instances from JSON data.

# Basic usage
company = Company.build_from_json(json_data)

# With autosave
company = Company.build_from_json(json_data, autosave: true)

extract_attributes_from_json(json_data)

Extracts model attributes from JSON data without creating an instance.

attrs = Company.extract_attributes_from_json(json_data)
# Returns hash of attributes for use with new() or update()

build_attributes_from_json(json_data, options = {})

Builds clean attributes hash from JSON data.

attrs = Company.build_attributes_from_json(json_data, include_id: false)
# Returns cleaned attributes hash for database operations

Implementation Details

JsonUpdatable Concern

All models include the JsonUpdatable concern which provides:

1. Standardized method signatures
2. Consistent option handling
3. Automatic JSON symbolization
4. Special attribute processing (flags_data, numeric_data, dates_data)
5. Filtered attribute handling

Custom Processing Hooks

Models can override these methods for custom behavior:

filter_ignored_attributes!(json_data)

private

def filter_ignored_attributes!(json_data)
  self.class::JSON_IGNORED_ATTRS.each { |attr| json_data.delete(attr) }
  super # Call parent implementation
end

process_json_transformations!(json_data)

private

def process_json_transformations!(json_data)
  # Handle nested objects
  if json_data[:address].present?
    self.build_address if self.address.nil?
    self.address.update_from_json(json_data.delete(:address))
  end
  
  # Handle custom field processing
  build_description(json_data.delete(:description))
end

Usage Examples

Basic Operations

# Update existing record
company.update_from_json(api_data, autosave: true)

# Create new record
new_company = Company.build_from_json(api_data, autosave: true)

# Extract attributes only
attrs = Company.extract_attributes_from_json(api_data)
company = Company.new(attrs)

Advanced Usage

# Custom options
facility.update_from_json(data, {
  autosave: false,
  include_id: false,
  merge: { status: 'active' }
})

# Batch processing
companies_data.each do |data|
  company = Company.find_by(siren: data[:siren])
  if company
    company.update_from_json(data, autosave: true)
  else
    Company.build_from_json(data, autosave: true)
  end
end

Best Practices

For New Code

Always use the standardized methods:

# ✅ Good
model.update_from_json(json_data, autosave: true)
Model.build_from_json(json_data)

# ❌ Avoid deprecated methods
model.update_from_parser(json_data)
Model.setup_attributes(json_data)

Options Handling

Use the standardized options hash:

# ✅ Consistent
model.update_from_json(data, autosave: true, include_id: false)

# ❌ Old style
model.update_from_json(data, true) # ambiguous

Error Handling

begin
  company.update_from_json(api_data, autosave: true)
rescue => e
  Rails.logger.error "Failed to process JSON for #{company.class.name}: #{e.message}"
end

Testing

When testing, use the standardized methods:

describe '#update_from_json' do
  it 'updates model from JSON data' do
    model.update_from_json(valid_json_data)
    expect(model.name).to eq('Expected Name')
  end
  
  it 'handles autosave option' do
    expect { model.update_from_json(data, autosave: true) }
      .to change { model.reload.updated_at }
  end
end

Models Using Standardization

The following models use standardized JSON methods:

• Activity - With specialized transformations
• Address - Custom attribute extraction with address-specific logic
• Facility - Standardized with relationship handling
• CompanyCessation - Simplified with attribute data handling
• Entrepreneur - Custom attribute extraction with partner handling
• Right - Company representative processing
• Companies::Info - Basic standardization
• Company - Full standardization with complex processing

Integration Notes

• All public method signatures maintain backward compatibility
• New development should use standardized methods
• The JsonUpdatable concern is included in ApplicationRecord
• Custom processing hooks available for specialized needs