Module: Familia::Features::SchemaValidation

Defined in:
lib/familia/features/schema_validation.rb

Overview

Adds JSON schema validation methods to Horreum models. Schemas are loaded from external files via SchemaRegistry.

This feature provides instance-level validation against JSON schemas, enabling data integrity checks before persistence or during API operations.

Example:

class Customer < Familia::Horreum feature :schema_validation identifier_field :custid field :custid field :email end

# With schema at schemas/customer.json customer = Customer.new(custid: 'c1', email: 'invalid') customer.valid_against_schema? # => false customer.schema_validation_errors # => [...] customer.validate_against_schema! # raises SchemaValidationError

Schema Loading:

Schemas are loaded by SchemaRegistry based on class names. Configure schema loading before enabling this feature:

# Convention-based loading Familia.schema_path = 'schemas/models' # Loads schemas/models/customer.json for Customer class

# Explicit mapping Familia.schemas = { 'Customer' => 'schemas/customer.json' }

Validation Behavior:

  • Returns true/valid if no schema is defined for the class
  • Uses json_schemer gem for validation when available
  • Falls back to null validation (always passes) if gem not installed
  • Raises SchemaValidatorLoadError if json_schemer is installed but fails to load

Integration Patterns:

# Validate before save class Order < Familia::Horreum feature :schema_validation

def save
  validate_against_schema!
  super
end

end

# Conditional validation class User < Familia::Horreum feature :schema_validation

def save
  if self.class.schema_defined?
    return false unless valid_against_schema?
  end
  super
end

end

Error Handling:

The validate_against_schema! method raises SchemaValidationError with detailed error information:

begin customer.validate_against_schema! rescue Familia::SchemaValidationError => e e.errors # => [{ 'data_pointer' => '/email', 'type' => 'format', ... }] end

Defined Under Namespace

Modules: ClassMethods

Instance Method Summary collapse

Instance Method Details

#schema ⇒ Hash?

Get the schema for this instance's class

Returns:

  • (Hash, nil)


111
112
113
# File 'lib/familia/features/schema_validation.rb', line 111

def schema
  self.class.schema
end

#schema_validation_errors ⇒ Array<Hash>

Get validation errors for the current state

Returns:

  • (Array<Hash>) —

    array of error objects (empty if valid)

Raises:



129
130
131
132
133
# File 'lib/familia/features/schema_validation.rb', line 129

def schema_validation_errors
  return [] unless self.class.schema_defined?

  Familia::SchemaRegistry.validate(self.class.name, to_h)[:errors]
end

#valid_against_schema? ⇒ Boolean

Check if the current state validates against the schema

Returns:

  • (Boolean) —

    true if valid or no schema defined

Raises:



119
120
121
122
123
# File 'lib/familia/features/schema_validation.rb', line 119

def valid_against_schema?
  return true unless self.class.schema_defined?

  Familia::SchemaRegistry.validate(self.class.name, to_h)[:valid]
end

#validate_against_schema! ⇒ true

Validate current state or raise SchemaValidationError

Returns:

  • (true) —

    if valid

Raises:



140
141
142
143
144
# File 'lib/familia/features/schema_validation.rb', line 140

def validate_against_schema!
  return true unless self.class.schema_defined?

  Familia::SchemaRegistry.validate!(self.class.name, to_h)
end