Module: Servus::Schema::Declaration

Included in:
Base, Event
Defined in:
lib/servus/schema/declaration.rb

Overview

Provides the schema DSL to a class.

Extend a class with this and call #declare_schemas with the schema kinds it supports. Base declares arguments, result, and failure; Event declares payload. Each kind gets:

  • a keyword on the generated schema class method
  • a reader returning the compiled schema, e.g. arguments_schema

Compiled on read

The plain reader compiles, so every consumer — validation, the test example builders, the have_schema matcher, application code reading a service's contract — sees resolved +$ref+s without having to know that compilation exists. Results are memoized per class against generation, so registering a changed fragment rebuilds dependent schemas with no dependency tracking.

Inheritance

Readers walk the ancestor chain, so a subclass of a schema-bearing class inherits its contract. Without this a subclass silently validates nothing, which is the failure mode this whole subsystem is built to prevent.

See Also:

Instance Method Summary collapse

Instance Method Details

#declare_schemas(*types) ⇒ void

This method returns an undefined value.

Defines the schema DSL and its readers for the given kinds.

Examples:

class Servus::Event
  extend Servus::Schema::Declaration
  declare_schemas :payload
end

Parameters:

  • types (Array<Symbol>) —

    the schema kinds this class supports



42
43
44
45
46
47
48
 
# File 'lib/servus/schema/declaration.rb', line 42

def declare_schemas(*types)
  @schema_types = types.freeze

  types.each do |type|
    define_singleton_method(:"#{type}_schema") { compiled_schema(type) }
  end
end

#schema(**schemas) ⇒ void

This method returns an undefined value.

Declares schemas for this class.

Omitting a keyword leaves any previously declared schema of that kind in place. Passing one explicitly as nil raises, rather than quietly leaving the class unvalidated — a lookup that returns nil is a bug at the call site, and swallowing it is how contracts silently disappear.

Examples:

schema arguments: { type: 'object', required: ['user_id'] }

Parameters:

  • schemas (Hash{Symbol => Hash}) —

    schema kind to JSON Schema

Raises:

  • (ArgumentError) —

    on an unknown kind or an explicit nil



71
72
73
74
75
76
77
78
79
80
81
 
# File 'lib/servus/schema/declaration.rb', line 71

def schema(**schemas)
  validate_schema_kinds!(schemas.keys)

  schemas.each do |type, value|
    raise ArgumentError, nil_schema_message(type) if value.nil?

    instance_variable_set(:"@raw_#{type}_schema", value.with_indifferent_access)
  end

  @compiled_schemas = nil
end

#schema_types ⇒ Array<Symbol>

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The schema kinds this class supports.

Returns:

  • (Array<Symbol>) 


54
55
56
 
# File 'lib/servus/schema/declaration.rb', line 54

def schema_types
  @schema_types || superclass.schema_types
end