Module: RSMP::Schema

Defined in:
lib/rsmp/schema.rb,
lib/rsmp/schema_error.rb,
lib/rsmp/schema/validation.rb,
lib/rsmp/schema/message_resolution.rb,
lib/rsmp/schema/core_sxl_resolution.rb

Overview

Provides JSON Schema validation for RSMP messages across core and SXL versions.

Defined Under Namespace

Classes: AmbiguousMessageCodeError, Error, UnknownMessageCodeError, UnknownSchemaError, UnknownSchemaTypeError, UnknownSchemaVersionError

Constant Summary collapse

MESSAGE_CODE_EXTRACTORS = 
{
  'StatusRequest' => ->(message) { status_codes(message) },
  'StatusSubscribe' => ->(message) { status_codes(message) },
  'StatusUnsubscribe' => ->(message) { status_codes(message) },
  'StatusResponse' => ->(message) { status_codes(message) },
  'StatusUpdate' => ->(message) { status_codes(message) },
  'CommandRequest' => ->(message) { request_command_codes(message) },
  'CommandResponse' => ->(message) { response_command_codes(message) },
  'Alarm' => ->(message) { alarm_codes(message) }
}.freeze
MESSAGE_CODE_KINDS = 
{
  'StatusRequest' => :statuses,
  'StatusSubscribe' => :statuses,
  'StatusUnsubscribe' => :statuses,
  'StatusResponse' => :statuses,
  'StatusUpdate' => :statuses,
  'CommandRequest' => :commands,
  'CommandResponse' => :commands,
  'Alarm' => :alarms
}.freeze

Class Method Summary collapse

Class Method Details

.alarm_codes(message) ⇒ Object 



43
44
45
 
# File 'lib/rsmp/schema/message_resolution.rb', line 43

def self.alarm_codes(message)
  [message['aCId']].compact
end

.build_core_sxl_schema(type, version, core_version) ⇒ Object

Raises:



37
38
39
40
41
42
43
44
45
46
 
# File 'lib/rsmp/schema/core_sxl_resolution.rb', line 37

def self.build_core_sxl_schema(type, version, core_version)
  schema_path = @schema_paths&.dig(type.to_sym, version.to_s)
  raise UnknownSchemaVersionError, "Unknown schema version #{type} #{version}" unless schema_path

  file_path = File.join(schema_path, 'rsmp.json')
  JSONSchemer.schema(
    Pathname.new(file_path),
    ref_resolver: core_sxl_ref_resolver(core_version)
  )
end

.clear_core_sxl_schemas(type = nil, version = nil) ⇒ Object 



4
5
6
7
8
9
10
11
12
 
# File 'lib/rsmp/schema/core_sxl_resolution.rb', line 4

def self.clear_core_sxl_schemas(type = nil, version = nil)
  @core_sxl_schemas ||= {}
  return @core_sxl_schemas.clear unless type

  type = type.to_sym
  @core_sxl_schemas.delete_if do |(cached_type, cached_version, _core_version), _schema|
    cached_type == type && (!version || cached_version == version.to_s)
  end
end

.clear_sxl_index(type = nil, version = nil) ⇒ Object 



233
234
235
236
237
238
239
240
241
242
243
 
# File 'lib/rsmp/schema.rb', line 233

def self.clear_sxl_index(type = nil, version = nil)
  @sxl_indexes ||= {}
  return @sxl_indexes.clear unless type

  type = type.to_sym
  if version
    @sxl_indexes.delete([type, version.to_s])
  else
    @sxl_indexes.delete_if { |key, _value| key.first == type }
  end
end

.core_definitions_path(core_version) ⇒ Object

Raises:



62
63
64
65
66
67
 
# File 'lib/rsmp/schema/core_sxl_resolution.rb', line 62

def self.core_definitions_path(core_version)
  path = File.join(schema_root_path, 'core', core_version.to_s, 'definitions.json')
  return path if File.exist?(path)

  raise UnknownSchemaVersionError, "Missing core definitions for RSMP #{core_version}"
end

.core_message_type?(message) ⇒ Boolean

Returns:

  • (Boolean) 


4
5
6
7
8
9
10
11
12
13
14
15
 
# File 'lib/rsmp/schema/validation.rb', line 4

def self.core_message_type?(message)
  type = message['type']
  %w[
    MessageAck
    MessageNotAck
    Version
    ComponentList
    AggregatedStatus
    AggregatedStatusRequest
    Watchdog
  ].include?(type)
end

.core_sxl_ref_resolver(core_version) ⇒ Object 



48
49
50
51
52
53
54
55
56
 
# File 'lib/rsmp/schema/core_sxl_resolution.rb', line 48

def self.core_sxl_ref_resolver(core_version)
  proc do |uri|
    if sxl_definitions_ref?(uri)
      JSON.parse(File.read(core_definitions_path(core_version), encoding: 'UTF-8'))
    else
      JSONSchemer::FILE_URI_REF_RESOLVER.call(uri)
    end
  end
end

.core_versions ⇒ Object

get array of core schema versions



89
90
91
 
# File 'lib/rsmp/schema.rb', line 89

def self.core_versions
  versions :core
end

.earliest_core_version ⇒ Object

get earliest core schema version



94
95
96
 
# File 'lib/rsmp/schema.rb', line 94

def self.earliest_core_version
  earliest_version :core
end

.earliest_version(type) ⇒ Object

get earliest schema version for a particular schema type



110
111
112
113
 
# File 'lib/rsmp/schema.rb', line 110

def self.earliest_version(type)
  schemas = find_schemas!(type).keys
  sort_versions(schemas).first
end

.ensure_schema_type_available(type, force) ⇒ Object 



48
49
50
 
# File 'lib/rsmp/schema.rb', line 48

def self.ensure_schema_type_available(type, force)
  raise "Schema type #{type} already loaded" if @schemas[type] && force != true
end

.find_core_sxl_schema!(type, version, core_version, options = {}) ⇒ Object

Raises:

  • (ArgumentError) 


24
25
26
27
28
29
30
31
32
33
34
35
 
# File 'lib/rsmp/schema/core_sxl_resolution.rb', line 24

def self.find_core_sxl_schema!(type, version, core_version, options = {})
  raise ArgumentError, 'core version missing' unless core_version

  version = sanitize_version(version.to_s) if options[:lenient]
  core_version = sanitize_version(core_version.to_s) if options[:lenient]
  find_schema! type, version
  find_schema! :core, core_version

  key = [type.to_sym, version.to_s, core_version.to_s]
  @core_sxl_schemas ||= {}
  @core_sxl_schemas[key] ||= build_core_sxl_schema(type, version, core_version)
end

.find_schema(type, version, options = {}) ⇒ Object

find schema for a particular schema and version return nil if not found

Raises:

  • (ArgumentError) 


159
160
161
162
163
164
165
166
167
168
 
# File 'lib/rsmp/schema.rb', line 159

def self.find_schema(type, version, options = {})
  raise ArgumentError, 'version missing' unless version

  version = sanitize_version version if options[:lenient]
  if version
    schemas = find_schemas type
    return schemas[version] if schemas
  end
  nil
end

.find_schema!(type, version, options = {}) ⇒ Object

find schema for a particular schema and version raise error if not found

Raises:

  • (ArgumentError) 


187
188
189
190
191
192
193
194
195
196
197
198
 
# File 'lib/rsmp/schema.rb', line 187

def self.find_schema!(type, version, options = {})
  schema = find_schema type, version, options
  raise ArgumentError, 'version missing' unless version

  version = sanitize_version version if options[:lenient]
  if version
    schemas = find_schemas! type
    schema = schemas[version]
    return schema if schema
  end
  raise UnknownSchemaVersionError, "Unknown schema version #{type} #{version}"
end

.find_schemas(type) ⇒ Object

find schemas versions for particular schema type return nil if type not found

Raises:

  • (ArgumentError) 


142
143
144
145
146
 
# File 'lib/rsmp/schema.rb', line 142

def self.find_schemas(type)
  raise ArgumentError, 'type missing' unless type

  @schemas[type.to_sym]
end

.find_schemas!(type) ⇒ Object

find schemas versions for particular schema type raise error if not found

Raises:



150
151
152
153
154
155
 
# File 'lib/rsmp/schema.rb', line 150

def self.find_schemas!(type)
  schemas = find_schemas type
  raise UnknownSchemaTypeError, "Unknown schema type #{type}" unless schemas

  schemas
end

.latest_core_version ⇒ Object

get latesty core schema version



99
100
101
 
# File 'lib/rsmp/schema.rb', line 99

def self.latest_core_version
  latest_version :core
end

.latest_version(type) ⇒ Object

get latest schema version for a particular schema type



116
117
118
119
 
# File 'lib/rsmp/schema.rb', line 116

def self.latest_version(type)
  schemas = find_schemas!(type).keys
  sort_versions(schemas).last
end

.load_schema_type(type, type_path, force: false) ⇒ Object

load an schema from a folder. schemas are organized by version, and contain json schema files, with the entry point being rsmp.jspon, eg: tlc

 1.0.7
   rsmp.json
   other jon schema files...
 1.0.8
 ...

an error is raised if the schema type already exists, and force is not set to true



36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/rsmp/schema.rb', line 36

def self.load_schema_type(type, type_path, force: false)
  type = type.to_sym
  ensure_schema_type_available(type, force)

  @schemas[type] = {}
  @schema_paths ||= {}
  @schema_paths[type] = {}
  clear_sxl_index(type)
  clear_core_sxl_schemas(type)
  schema_version_paths(type_path).each { |schema_path| load_schema_version(type, schema_path) }
end

.load_schema_version(type, schema_path) ⇒ Object 



56
57
58
59
60
61
62
63
64
65
 
# File 'lib/rsmp/schema.rb', line 56

def self.load_schema_version(type, schema_path)
  version = File.basename(schema_path)
  file_path = File.join(schema_path, 'rsmp.json')
  return unless File.exist? file_path

  @schemas[type][version] = JSONSchemer.schema(Pathname.new(file_path))
  @schema_paths[type][version] = schema_path
  clear_sxl_index(type, version)
  clear_core_sxl_schemas(type, version)
end

.load_sxl_index(type, version) ⇒ Object

Raises:



251
252
253
254
255
256
257
258
259
 
# File 'lib/rsmp/schema.rb', line 251

def self.load_sxl_index(type, version)
  schema_path = @schema_paths&.dig(type.to_sym, version.to_s)
  raise UnknownSchemaVersionError, "Unknown schema version #{type} #{version}" unless schema_path

  index_path = File.join(schema_path, 'sxl_index.json')
  raise Error, "Missing SXL index #{index_path}" unless File.exist?(index_path)

  JSON.parse(File.read(index_path, encoding: 'UTF-8'))
end

.matching_sxl_schemas(schemas, kind, codes, options) ⇒ Object 



82
83
84
85
86
87
88
 
# File 'lib/rsmp/schema/message_resolution.rb', line 82

def self.matching_sxl_schemas(schemas, kind, codes, options)
  sxl_schemas(schemas).select do |type, version|
    sxl_defines_codes?(type, version, kind, codes, options)
  rescue UnknownSchemaError
    false
  end
end

.message_code_kind(message) ⇒ Object 



47
48
49
 
# File 'lib/rsmp/schema/message_resolution.rb', line 47

def self.message_code_kind(message)
  MESSAGE_CODE_KINDS[message['type']]
end

.message_code_kind_name(kind) ⇒ Object 



62
63
64
65
66
67
68
 
# File 'lib/rsmp/schema/message_resolution.rb', line 62

def self.message_code_kind_name(kind)
  {
    statuses: 'status',
    commands: 'command',
    alarms: 'alarm'
  }.fetch(kind) { kind.to_s.delete_suffix('s') }
end

.message_codes(message) ⇒ Object 



26
27
28
29
 
# File 'lib/rsmp/schema/message_resolution.rb', line 26

def self.message_codes(message)
  extractor = MESSAGE_CODE_EXTRACTORS[message['type']]
  extractor ? extractor.call(message).uniq : []
end

.raise_if_ambiguous_sxl_match(codes, matches) ⇒ Object

Raises:



99
100
101
102
 
# File 'lib/rsmp/schema/message_resolution.rb', line 99

def self.raise_if_ambiguous_sxl_match(codes, matches)
  names = matches.map { |type, version| "#{type} #{version}" }.join(', ')
  raise AmbiguousMessageCodeError, "Message code(s) #{codes.join(', ')} match multiple accepted SXLs: #{names}"
end

.raise_if_no_sxl_match(kind, codes) ⇒ Object

Raises:



94
95
96
97
 
# File 'lib/rsmp/schema/message_resolution.rb', line 94

def self.raise_if_no_sxl_match(kind, codes)
  raise UnknownMessageCodeError,
        "No accepted SXL defines #{message_code_kind_name(kind)} code(s) #{codes.join(', ')}"
end

.remove_schema_type(type) ⇒ Object

remove a schema type



68
69
70
71
72
73
74
 
# File 'lib/rsmp/schema.rb', line 68

def self.remove_schema_type(type)
  type = type.to_sym
  schemas.delete type
  @schema_paths&.delete type
  clear_sxl_index(type)
  clear_core_sxl_schemas(type)
end

.request_command_codes(message) ⇒ Object 



35
36
37
 
# File 'lib/rsmp/schema/message_resolution.rb', line 35

def self.request_command_codes(message)
  (message['arg'] || []).map { |item| item['cCI'] }.compact
end

.resolve_sxl(message, schemas:, **options) ⇒ Object 



70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/rsmp/schema/message_resolution.rb', line 70

def self.resolve_sxl(message, schemas:, **options)
  kind = message_code_kind(message)
  codes = message_codes(message)
  return nil unless kind && codes.any?

  matches = matching_sxl_schemas(schemas, kind, codes, options)
  raise_if_no_sxl_match(kind, codes) if matches.empty?
  raise_if_ambiguous_sxl_match(codes, matches) if matches.size > 1

  matches.first
end

.response_command_codes(message) ⇒ Object 



39
40
41
 
# File 'lib/rsmp/schema/message_resolution.rb', line 39

def self.response_command_codes(message)
  (message['rvs'] || []).map { |item| item['cCI'] }.compact
end

.sanitize_version(version) ⇒ Object

get major.minor.patch part of a version string, where patch is optional ignore trailing characters, e.g.

3.1.3.32A => 3.1.3
3.1A3r3 >= 3.1

return nil if string doesn’t match



175
176
177
178
179
180
181
182
183
 
# File 'lib/rsmp/schema.rb', line 175

def self.sanitize_version(version)
  # match normal semver z.y.z format
  if (matched = /^\d+\.\d+\.\d+/.match(version))
    matched.to_s
  # match x.y format, and add patch version zero to get z.y.0
  elsif (matched = /^\d+\.\d+/.match(version))
    "#{matched}.0"
  end
end

.schema?(type, version, options = {}) ⇒ Boolean

true if a particular schema type and version found

Returns:

  • (Boolean) 


201
202
203
 
# File 'lib/rsmp/schema.rb', line 201

def self.schema?(type, version, options = {})
  find_schema(type, version, options) != nil
end

.schema_core_version(schemas) ⇒ Object 



14
15
16
 
# File 'lib/rsmp/schema/core_sxl_resolution.rb', line 14

def self.schema_core_version(schemas)
  schemas[:core] || schemas['core']
end

.schema_root_path ⇒ Object 



22
23
24
 
# File 'lib/rsmp/schema.rb', line 22

def self.schema_root_path
  File.expand_path(File.join(__dir__, '..', '..', 'schemas'))
end

.schema_types ⇒ Object

get schemas types



77
78
79
 
# File 'lib/rsmp/schema.rb', line 77

def self.schema_types
  schemas.keys
end

.schema_version_paths(type_path) ⇒ Object 



52
53
54
 
# File 'lib/rsmp/schema.rb', line 52

def self.schema_version_paths(type_path)
  Dir.glob("#{type_path}/*").select { |path| File.directory? path }
end

.schemas ⇒ Object

get all schemas, oganized by type and version



82
83
84
85
86
 
# File 'lib/rsmp/schema.rb', line 82

def self.schemas
  raise 'No schemas available, perhaps Schema.setup was never called?' unless @schemas

  @schemas
end

.setup ⇒ Object 



10
11
12
13
14
15
16
17
18
19
20
 
# File 'lib/rsmp/schema.rb', line 10

def self.setup
  @schemas = {}
  @schema_paths = {}
  @sxl_indexes = {}
  @core_sxl_schemas = {}
  schemas_path = schema_root_path
  Dir.glob("#{schemas_path}/*").select { |f| File.directory? f }.each do |type_path|
    type = File.basename(type_path).to_sym
    load_schema_type type, type_path
  end
end

.sort_versions(versions) ⇒ Object

sort version strings



136
137
138
 
# File 'lib/rsmp/schema.rb', line 136

def self.sort_versions(versions)
  versions.sort_by { |k| Gem::Version.new(k) }
end

.status_catalogue(type, version) ⇒ Object

return a catalogue of statuses for a particular schema type and version returns a hash of { status_code_id_sym => [arg_name_sym, …] } raises an error if the schema type/version is not found, or has no status catalogue



219
220
221
222
223
 
# File 'lib/rsmp/schema.rb', line 219

def self.status_catalogue(type, version)
  sxl_catalogue(type, version, :statuses).transform_keys(&:to_sym).transform_values do |status|
    status.fetch('arguments', []).map(&:to_sym)
  end
end

.status_codes(message) ⇒ Object 



31
32
33
 
# File 'lib/rsmp/schema/message_resolution.rb', line 31

def self.status_codes(message)
  (message['sS'] || []).map { |item| item['sCI'] }.compact
end

.sxl_catalogue(type, version, kind) ⇒ Object 



225
226
227
228
229
230
231
 
# File 'lib/rsmp/schema.rb', line 225

def self.sxl_catalogue(type, version, kind)
  find_schema! type, version
  catalogue = sxl_index(type, version)[kind.to_s]
  raise "No #{kind} catalogue for #{type} #{version}" unless catalogue

  catalogue
end

.sxl_defines_codes?(type, version, kind, codes, options) ⇒ Boolean

Returns:

  • (Boolean) 


51
52
53
54
55
56
57
58
59
60
 
# File 'lib/rsmp/schema/message_resolution.rb', line 51

def self.sxl_defines_codes?(type, version, kind, codes, options)
  version = sanitize_version(version.to_s) if options[:lenient]
  catalogue = sxl_catalogue(type, version, kind)
  prefix = sxl_prefix(type, version, options)
  codes.all? do |code|
    unprefixed = prefix && code.start_with?(prefix) ? code[prefix.length..] : code
    catalogue.key?(code) || catalogue.key?(code.to_sym) ||
      catalogue.key?(unprefixed) || catalogue.key?(unprefixed.to_sym)
  end
end

.sxl_definitions_ref?(uri) ⇒ Boolean

Returns:

  • (Boolean) 


58
59
60
 
# File 'lib/rsmp/schema/core_sxl_resolution.rb', line 58

def self.sxl_definitions_ref?(uri)
  uri.scheme == 'file' && uri.path.end_with?('/defs/definitions.json')
end

.sxl_index(type, version) ⇒ Object 



245
246
247
248
249
 
# File 'lib/rsmp/schema.rb', line 245

def self.sxl_index(type, version)
  key = [type.to_sym, version.to_s]
  @sxl_indexes ||= {}
  @sxl_indexes[key] ||= load_sxl_index(type, version)
end

.sxl_metadata(type, version, options = {}) ⇒ Object 



205
206
207
208
209
210
 
# File 'lib/rsmp/schema.rb', line 205

def self.sxl_metadata(type, version, options = {})
  version = sanitize_version version if options[:lenient]
  find_schema! type, version

  sxl_index(type, version).fetch('meta', {})
end

.sxl_prefix(type, version, options = {}) ⇒ Object 



212
213
214
 
# File 'lib/rsmp/schema.rb', line 212

def self.sxl_prefix(type, version, options = {})
  sxl_metadata(type, version, options)['prefix']
end

.sxl_schemas(schemas) ⇒ Object 



90
91
92
 
# File 'lib/rsmp/schema/message_resolution.rb', line 90

def self.sxl_schemas(schemas)
  schemas.reject { |type, _version| type.to_sym == :core }
end

.validate(message, schemas, options = {}) ⇒ Object

Core must pass. SXL-defined messages pass if at least one SXL schema passes.

Raises:

  • (ArgumentError) 


44
45
46
47
48
49
50
51
52
53
54
55
 
# File 'lib/rsmp/schema/validation.rb', line 44

def self.validate(message, schemas, options = {})
  raise ArgumentError, 'message missing' unless message
  raise ArgumentError, 'schemas missing' unless schemas
  raise ArgumentError, 'schemas must be a Hash' unless schemas.is_a?(Hash)
  raise ArgumentError, 'schemas cannot be empty' unless schemas.any?

  errors = validate_core(message, schemas, options)
  errors.concat validate_sxls(message, schemas, options) if errors.empty?
  return nil if errors.empty?

  errors
end

.validate_core(message, schemas, options) ⇒ Object

Raises:

  • (ArgumentError) 


17
18
19
20
21
22
23
 
# File 'lib/rsmp/schema/validation.rb', line 17

def self.validate_core(message, schemas, options)
  core_version = schemas[:core] || schemas['core']
  raise ArgumentError, 'schemas must include core' unless core_version

  schema = find_schema! :core, core_version, options
  validate_using_schema(message, schema)
end

.validate_resolved_sxl(message, resolved, schemas, options) ⇒ Object 



18
19
20
21
22
 
# File 'lib/rsmp/schema/core_sxl_resolution.rb', line 18

def self.validate_resolved_sxl(message, resolved, schemas, options)
  type, version = resolved
  schema = find_core_sxl_schema! type, version, schema_core_version(schemas), options
  validate_using_schema(message, schema)
end

.validate_sxls(message, schemas, options) ⇒ Object 



25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
 
# File 'lib/rsmp/schema/validation.rb', line 25

def self.validate_sxls(message, schemas, options)
  sxl_schemas = schemas.reject { |type, _version| type.to_sym == :core }
  return [] if sxl_schemas.empty? || core_message_type?(message)

  resolved = resolve_sxl(message, schemas: schemas, **options)
  return validate_resolved_sxl(message, resolved, schemas, options) if resolved

  all_errors = []
  sxl_schemas.each do |type, version|
    schema = find_core_sxl_schema! type, version, schema_core_version(schemas), options
    errors = validate_using_schema(message, schema)
    return [] if errors.empty?

    all_errors.concat errors
  end
  all_errors
end

.validate_using_schema(message, schema) ⇒ Object

validate an rsmp messages using a schema object

Raises:

  • (ArgumentError) 


122
123
124
125
126
127
128
129
130
131
132
133
 
# File 'lib/rsmp/schema.rb', line 122

def self.validate_using_schema(message, schema)
  raise ArgumentError, 'message missing' unless message
  raise ArgumentError, 'schema missing' unless schema

  if schema.valid? message
    []
  else
    schema.validate(message).map do |item|
      [item['data_pointer'], item['type'], item['details']]
    end
  end
end

.versions(type) ⇒ Object

get array of schema versions for a particular schema type



104
105
106
107
 
# File 'lib/rsmp/schema.rb', line 104

def self.versions(type)
  schemas = find_schemas!(type).keys
  sort_versions(schemas)
end