rsmp_schema 0.9.1 → 0.10.1

data/lib/rsmp_schema/convert/export/json_schema.rb

@@ -6,26 +6,27 @@ require 'fileutils'
 
 module RSMP
   module Convert
+    # Handles exporting SXL definitions.
     module Export
+      # Converts SXL definitions to JSON Schema files.
       module JSONSchema
-
-        @@json_options = {
+        JSON_OPTIONS = {
           array_nl: "\n",
           object_nl: "\n",
           indent: '  ',
           space_before: ' ',
           space: ' '
-        }
+        }.freeze
 
-        def self.output_json item
-          JSON.generate(item,@@json_options)
+        def self.output_json(item)
+          JSON.generate(item, JSON_OPTIONS)
         end
 
         # convert a yaml item to json schema
-        def self.build_value item
+        def self.build_value(item)
           out = {}
           out['description'] = item['description'] if item['description']
-          if item['type'] =~/_list$/
+          if item['type'] =~ /_list$/
             handle_string_list item, out
           else
             handle_types item, out
@@ -36,283 +37,294 @@ module RSMP
         end
 
         # convert an item which is not a string-list, to json schema
-        def self.handle_types item, out
+        def self.handle_types(item, out)
           case item['type']
-          when "string", "base64"
-            out["type"] = "string"
-          when "boolean"
-            out["$ref"] = "../../../core/3.1.2/definitions.json#/boolean"
-          when "timestamp"
-            out["$ref"] = "../../../core/3.1.2/definitions.json#/timestamp"
-          when "integer", "ordinal", "unit", "scale", "long"
-            out["$ref"] = "../../../core/3.1.2/definitions.json#/integer"
-          when 'array'   # a json array
+          when 'boolean'
+            out['$ref'] = '../../../core/3.1.2/definitions.json#/boolean'
+          when 'timestamp'
+            out['$ref'] = '../../../core/3.1.2/definitions.json#/timestamp'
+          when 'integer', 'ordinal', 'unit', 'scale', 'long'
+            out['$ref'] = '../../../core/3.1.2/definitions.json#/integer'
+          when 'array' # a json array
             build_json_array item['items'], out
-          else
-            out["type"] = "string"
+          else # string, base64, and any unknown types
+            out['type'] = 'string'
           end
         end
 
         # convert an yaml item with type: array to json schema
-        def self.build_json_array item, out
-          required = item.select { |k,v| v['optional'] != true }.keys.sort
+        def self.build_json_array(item, out)
+          required = item.reject { |_k, v| v['optional'] == true }.keys.sort
           out.merge!({
-            "type" => "array",
-            "items" => {
-              "type" => "object",
-              "required" => required,
-              "unevaluatedProperties" => false  # Modern alternative to additionalProperties
-            }
-          })
-          out["items"]["properties"] = {}
-          item.each_pair do |key,v|
-            out["items"]["properties"][key] = build_value(v)
+                       'type' => 'array',
+                       'items' => {
+                         'type' => 'object',
+                         'required' => required,
+                         'unevaluatedProperties' => false # Modern alternative to additionalProperties
+                       }
+                     })
+          out['items']['properties'] = {}
+          item.each_pair do |key, v|
+            out['items']['properties'][key] = build_value(v)
           end
           out
         end
 
         # JSON Schema 2020-12 allows combining $ref with other properties directly
-        def self.wrap_refs out
+        def self.wrap_refs(out)
           # No wrapping needed with modern JSON Schema
           out
         end
 
         # convert a yaml item with list: true to json schema
-        def self.handle_string_list item, out
+        def self.handle_string_list(item, out)
           case item['type']
-          when "boolean_list"
-            out["$ref"] = "../../../core/3.1.2/definitions.json#/boolean_list"
-          when "integer_list"
-            out["$ref"] = "../../../core/3.1.2/definitions.json#/integer_list"
-          when "string_list"
-            out["$ref"] = "../../../core/3.1.2/definitions.json#/string_list"
+          when 'boolean_list'
+            out['$ref'] = '../../../core/3.1.2/definitions.json#/boolean_list'
+          when 'integer_list'
+            out['$ref'] = '../../../core/3.1.2/definitions.json#/integer_list'
+          when 'string_list'
+            out['$ref'] = '../../../core/3.1.2/definitions.json#/string_list'
           else
             raise "Error: List of #{item['type']} is not supported: #{item.inspect}"
           end
 
-          if item["values"]
-            value_list = item["values"].keys.join('|')
+          if item['values']
+            value_list = item['values'].keys.join('|')
             out['pattern'] = /(?-mix:^(#{value_list})(?:,(#{value_list}))*$)/
           end
 
-          puts "Warning: Pattern not support for lists: #{item.inspect}" if item["pattern"]
+          puts "Warning: Pattern not support for lists: #{item.inspect}" if item['pattern']
         end
 
         # convert yaml values to jsons schema enum
-        def self.handle_enum item, out
-          if item["values"]
-            out["enum"] = case item["values"]
-            when Hash
-              item["values"].each_pair do |k,v|
-                if v=='' or v==nil
-                  raise "Error: '#{k}' has empty value in #{item}. (When using a hash to specify 'values', the hash values cannot be empty.)"
-                end
-              end
-              item["values"].keys.sort
-            when Array
-              item["values"].sort
-            else
-              raise "Error: Values must be specified as either a Hash or an Array, got #{item["values"].class}"
-            end.map do |v|
-              if v.is_a?(Integer) || v.is_a?(Float)
-                v.to_s
-              else
-                v
-              end
-            end
+        def self.handle_enum(item, out)
+          return unless item['values']
+
+          out['enum'] = stringify_values(enum_keys(item))
+        end
+
+        def self.enum_keys(item)
+          case item['values']
+          when Hash
+            validate_hash_values! item
+            item['values'].keys.sort
+          when Array
+            item['values'].sort
+          else
+            raise 'Error: Values must be specified as either a Hash or an Array, ' \
+                  "got #{item['values'].class}"
           end
         end
 
+        def self.validate_hash_values!(item)
+          item['values'].each_pair do |k, v|
+            next unless ['', nil].include?(v)
+
+            raise "Error: '#{k}' has empty value in #{item}. " \
+                  '(When using a hash to specify \'values\', the hash values cannot be empty.)'
+          end
+        end
+
+        def self.stringify_values(values)
+          values.map { |v| v.is_a?(Integer) || v.is_a?(Float) ? v.to_s : v }
+        end
+
         # convert yaml pattern to jsons schema
-        def self.handle_pattern item, out
-          out["pattern"] = item["pattern"] if item["pattern"]
+        def self.handle_pattern(item, out)
+          out['pattern'] = item['pattern'] if item['pattern']
         end
 
         # convert yaml alarm/status/command item to corresponding jsons schema
-        def self.build_item item, property_key: 'v'
-          unless item['arguments']
-            json = {
-              "$schema" => "https://json-schema.org/draft/2020-12/schema",
-              "description" => item['description'],
-            }
-            return json
-          end
-
+        def self.build_item(item, property_key: 'v')
           arguments = item['arguments']
+          return simple_item(item) unless arguments
 
-          # For statuses (property_key == 's'), generate a single top-level gate:
-          # if q is undefined/unknown -> no constraints; else -> per-n branches.
-          if property_key == 's'
-            branches = arguments.map do |key, argument|
-              {
-                "if" => { "properties" => { "n" => { "const" => key } } },
-                "then" => { "properties" => { property_key => build_value(argument) } }
-              }
-            end
-
-            return {
-              "$schema" => "https://json-schema.org/draft/2020-12/schema",
-              "description" => item['description'],
-              "properties" => {
-                "n" => { "enum" => arguments.keys.sort }
-              },
-              # reference shared guard (relative from statuses folder to tlc/defs)
-              "if" => { "$ref" => "../../defs/guards.json#/$defs/q_unknown_or_undefined" },
-              "then" => {},
-              "else" => { "allOf" => branches }
+          property_key == 's' ? build_status_item(item, arguments) : build_default_item(item, arguments, property_key)
+        end
+
+        def self.simple_item(item)
+          {
+            '$schema' => 'https://json-schema.org/draft/2020-12/schema',
+            'description' => item['description']
+          }
+        end
+
+        def self.build_status_item(item, arguments)
+          branches = arguments.map do |key, argument|
+            {
+              'if' => { 'properties' => { 'n' => { 'const' => key } } },
+              'then' => { 'properties' => { 's' => build_value(argument) } }
             }
           end
+          {
+            '$schema' => 'https://json-schema.org/draft/2020-12/schema',
+            'description' => item['description'],
+            'properties' => { 'n' => { 'enum' => arguments.keys.sort } },
+            'if' => { '$ref' => '../../defs/guards.json#/$defs/q_unknown_or_undefined' },
+            'then' => {},
+            'else' => { 'allOf' => branches }
+          }
+        end
 
-          # Default behavior (alarms/commands): keep simple per-n if/then rules without q gating
+        def self.build_default_item(item, arguments, property_key)
           rules = arguments.map do |key, argument|
             {
-              "if" => { "properties" => { "n" => { "const" => key } } },
-              "then" => { "properties" => { property_key => build_value(argument) } }
+              'if' => { 'properties' => { 'n' => { 'const' => key } } },
+              'then' => { 'properties' => { property_key => build_value(argument) } }
             }
           end
-
           {
-            "$schema" => "https://json-schema.org/draft/2020-12/schema",
-            "description" => item['description'],
-            "properties" => {
-              "n" => { "enum" => arguments.keys.sort }
-            },
-            "allOf" => rules
+            '$schema' => 'https://json-schema.org/draft/2020-12/schema',
+            'description' => item['description'],
+            'properties' => { 'n' => { 'enum' => arguments.keys.sort } },
+            'allOf' => rules
           }
         end
 
         # convert alarms to json schema
-        def self.output_alarms out, items
+        def self.output_alarms(out, items)
           list = items.keys.sort.map do |key|
             {
-              "if" => { "required" => ["aCId"], "properties" => { "aCId" => { "const" => key }}},
-              "then" => { "$ref" => "#{key}.json" }
+              'if' => { 'required' => ['aCId'], 'properties' => { 'aCId' => { 'const' => key } } },
+              'then' => { '$ref' => "#{key}.json" }
             }
           end
           json = {
-            "$schema" => "https://json-schema.org/draft/2020-12/schema",
-            "properties" => {
-              "aCId" => { "enum" => items.keys.sort },
-              "rvs" => { "items" => { "allOf" => list } }
+            '$schema' => 'https://json-schema.org/draft/2020-12/schema',
+            'properties' => {
+              'aCId' => { 'enum' => items.keys.sort },
+              'rvs' => { 'items' => { 'allOf' => list } }
             }
           }
           out['alarms/alarms.json'] = output_json json
-          items.each_pair { |key,item| output_alarm out, key, item }
+          items.each_pair { |key, item| output_alarm out, key, item }
         end
 
         # convert an alarm to json schema
-        def self.output_alarm out, key, item
+        def self.output_alarm(out, key, item)
           json = build_item item
           out["alarms/#{key}.json"] = output_json json
         end
 
         # convert statuses to json schema
-        def self.output_statuses out, items
+        def self.output_statuses(out, items)
           # ensure shared guard is written (relative to version folder)
           out['../defs/guards.json'] ||= output_json({
-            "$schema" => "https://json-schema.org/draft/2020-12/schema",
-            "$defs" => {
-              "q_unknown_or_undefined" => {
-                "allOf" => [
-                  { "required" => ["q"] },
-                  { "properties" => { "q" => { "enum" => ["undefined", "unknown"] } } }
-                ]
-              }
-            }
-          })
-
-          list = [ { "properties" => { "sCI" => { "enum"=> items.keys.sort }}} ]
+                                                       '$schema' => 'https://json-schema.org/draft/2020-12/schema',
+                                                       '$defs' => {
+                                                         'q_unknown_or_undefined' => {
+                                                           'allOf' => [
+                                                             { 'required' => ['q'] },
+                                                             { 'properties' => { 'q' => { 'enum' => %w[undefined
+                                                                                                       unknown] } } }
+                                                           ]
+                                                         }
+                                                       }
+                                                     })
+
+          list = [{ 'properties' => { 'sCI' => { 'enum' => items.keys.sort } } }]
           items.keys.sort.each do |key|
             list << {
-              "if"=> { "required" => ["sCI"], "properties" => { "sCI"=> { "const"=> key }}},
-              "then" => { "$ref" => "#{key}.json" }
+              'if' => { 'required' => ['sCI'], 'properties' => { 'sCI' => { 'const' => key } } },
+              'then' => { '$ref' => "#{key}.json" }
             }
           end
-          json = { 
-            "$schema" => "https://json-schema.org/draft/2020-12/schema",
-            "properties" => { "sS" => { "items" => { "allOf" => list }}}
+          json = {
+            '$schema' => 'https://json-schema.org/draft/2020-12/schema',
+            'properties' => { 'sS' => { 'items' => { 'allOf' => list } } }
           }
           out['statuses/statuses.json'] = output_json json
-          items.each_pair { |key,item| output_status out, key, item }
+          items.each_pair { |key, item| output_status out, key, item }
         end
 
         # convert a status to json schema
-        def self.output_status out, key, item
+        def self.output_status(out, key, item)
           json = build_item item, property_key: 's'
           out["statuses/#{key}.json"] = output_json json
         end
 
         # convert commands to json schema
-        def self.output_commands out, items
-          list = [ { "properties" => { "cCI" => { "enum"=> items.keys.sort }}} ]
+        def self.output_commands(out, items)
+          list = [{ 'properties' => { 'cCI' => { 'enum' => items.keys.sort } } }]
           items.keys.sort.each do |key|
             list << {
-              "if" => { "required" => ["cCI"], "properties" => { "cCI"=> { "const"=> key }}},
-              "then" => { "$ref" => "#{key}.json" }
+              'if' => { 'required' => ['cCI'], 'properties' => { 'cCI' => { 'const' => key } } },
+              'then' => { '$ref' => "#{key}.json" }
             }
           end
-          json = { 
-            "$schema" => "https://json-schema.org/draft/2020-12/schema",
-            "items" => { "allOf" => list }
+          json = {
+            '$schema' => 'https://json-schema.org/draft/2020-12/schema',
+            'items' => { 'allOf' => list }
           }
           out['commands/commands.json'] = output_json json
 
-          json = { 
-            "$schema" => "https://json-schema.org/draft/2020-12/schema",
-            "properties" => { "arg" => { "$ref" => "commands.json" }}
+          json = {
+            '$schema' => 'https://json-schema.org/draft/2020-12/schema',
+            'properties' => { 'arg' => { '$ref' => 'commands.json' } }
           }
           out['commands/command_requests.json'] = output_json json
 
-          json = { 
-            "$schema" => "https://json-schema.org/draft/2020-12/schema",
-            "properties" => { "rvs" => { "$ref" => "commands.json" }}
+          json = {
+            '$schema' => 'https://json-schema.org/draft/2020-12/schema',
+            'properties' => { 'rvs' => { '$ref' => 'commands.json' } }
           }
           out['commands/command_responses.json'] = output_json json
 
-          items.each_pair { |key,item| output_command out, key, item }
+          items.each_pair { |key, item| output_command out, key, item }
         end
 
         # convert a command to json schema
-        def self.output_command out, key, item
+        def self.output_command(out, key, item)
           json = build_item item
           # Always add the command operation (cO) constraint at the top-level properties
-          json["properties"] ||= {}
-          json["properties"]["cO"] = { "const" => item['command'] }
-          
+          json['properties'] ||= {}
+          json['properties']['cO'] = { 'const' => item['command'] }
+
           out["commands/#{key}.json"] = output_json json
         end
 
         # output the json schema root
-        def self.output_root out, meta
+        def self.output_root(out, meta)
           json = {
-            "$schema" => "https://json-schema.org/draft/2020-12/schema",
-            "name"=> meta['name'],
-            "description"=> meta['description'],
-            "version"=> meta['version'],
-            "allOf" => [
-              {
-                "if" => { "required" => ["type"], "properties" => { "type" => { "const" => "CommandRequest" }}},
-                "then" => { "$ref" => "commands/command_requests.json" }
-              },
-              {
-                "if" => { "required" => ["type"], "properties" => { "type" => { "const" => "CommandResponse" }}},
-                "then" => { "$ref" => "commands/command_responses.json" }
-              },
-              {
-                "if" => { "required" => ["type"], "properties" => { "type" => { "enum" => ["StatusRequest","StatusResponse","StatusSubscribe","StatusUnsubscribe","StatusUpdate"] }}},
-                "then" => { "$ref" => "statuses/statuses.json" }
-              },
-              {
-                "if" => { "required" => ["type"], "properties" => { "type" => { "const" => "Alarm" }}},
-                "then" => { "$ref" => "alarms/alarms.json" }
-              }
-            ]
+            '$schema' => 'https://json-schema.org/draft/2020-12/schema',
+            'name' => meta['name'],
+            'description' => meta['description'],
+            'version' => meta['version'],
+            'allOf' => root_type_rules
           }
-          out["rsmp.json"] = output_json json
+          out['rsmp.json'] = output_json json
+        end
+
+        def self.root_type_rules
+          [
+            {
+              'if' => { 'required' => ['type'], 'properties' => { 'type' => { 'const' => 'CommandRequest' } } },
+              'then' => { '$ref' => 'commands/command_requests.json' }
+            },
+            {
+              'if' => { 'required' => ['type'], 'properties' => { 'type' => { 'const' => 'CommandResponse' } } },
+              'then' => { '$ref' => 'commands/command_responses.json' }
+            },
+            {
+              'if' => {
+                'required' => ['type'],
+                'properties' => {
+                  'type' => { 'enum' => %w[StatusRequest StatusResponse StatusSubscribe StatusUnsubscribe
+                                           StatusUpdate] }
+                }
+              },
+              'then' => { '$ref' => 'statuses/statuses.json' }
+            },
+            {
+              'if' => { 'required' => ['type'], 'properties' => { 'type' => { 'const' => 'Alarm' } } },
+              'then' => { '$ref' => 'alarms/alarms.json' }
+            }
+          ]
         end
 
         # generate the json schema from a string containing yaml
-        def self.generate sxl
+        def self.generate(sxl)
           out = {}
           output_root out, sxl[:meta]
           output_alarms out, sxl[:alarms]
@@ -322,16 +334,15 @@ module RSMP
         end
 
         # convert yaml to json schema and write files to a folder
-        def self.write sxl, folder
+        def self.write(sxl, folder)
           out = generate sxl
-          out.each_pair do |relative_path,str|
+          out.each_pair do |relative_path, str|
             path = File.join(folder, relative_path)
-            FileUtils.mkdir_p File.dirname(path)      # create folders if needed
-            file = File.open(path, 'w+')      # w+ means truncate or create new file
-            file.puts str
+            FileUtils.mkdir_p File.dirname(path)
+            File.open(path, 'w+') { |file| file.puts str }
           end
         end
       end
     end
   end
-end
+end

data/lib/rsmp_schema/convert/import/yaml.rb

@@ -5,37 +5,35 @@ require 'json'
 require 'fileutils'
 
 module RSMP
+  # Namespace for SXL format conversion tools.
   module Convert
+    # Handles importing SXL definitions.
     module Import
+      # Reads SXL definitions from YAML files.
       module YAML
-
-        def self.read path
+        def self.read(path)
           convert ::YAML.load_file(path)
         end
 
-        def self.parse str
-          convert ::YAML.load(str)
+        def self.parse(str)
+          convert ::YAML.safe_load(str)
         end
 
-        def self.convert yaml
-          sxl = {
-            meta: {},
-            alarms: {},
-            statuses: {},
-            commands: {}
-          }
-
+        def self.convert(yaml)
+          sxl = { meta: {}, alarms: {}, statuses: {}, commands: {} }
           sxl[:meta] = yaml['meta']
+          collect_objects yaml['objects'], sxl
+          sxl
+        end
 
-          yaml['objects'].each_pair do |type,object|
-            object["alarms"].each { |id,item| sxl[:alarms][id] = item } if object["alarms"]
-            object["statuses"].each { |id,item| sxl[:statuses][id] = item } if object["statuses"]
-            object["commands"].each { |id,item| sxl[:commands][id] = item } if object["commands"]
+        def self.collect_objects(objects, sxl)
+          objects.each_pair do |_type, object|
+            object['alarms']&.each { |id, item| sxl[:alarms][id] = item }
+            object['statuses']&.each { |id, item| sxl[:statuses][id] = item }
+            object['commands']&.each { |id, item| sxl[:commands][id] = item }
           end
-          sxl
         end
       end
-
     end
   end
-end
+end

data/lib/rsmp_schema/error.rb

@@ -1,13 +1,19 @@
-module RSMP::Schema
-  class Error < StandardError
-  end
+module RSMP
+  module Schema
+    # Base error class for rsmp_schema.
+    class Error < StandardError
+    end
 
-  class UnknownSchemaError < Error
-  end
+    # Raised when an unknown schema type or version is requested.
+    class UnknownSchemaError < Error
+    end
 
-  class UnknownSchemaTypeError < UnknownSchemaError
-  end
+    # Raised when the requested schema type does not exist.
+    class UnknownSchemaTypeError < UnknownSchemaError
+    end
 
-  class UnknownSchemaVersionError < UnknownSchemaError
+    # Raised when the requested schema version does not exist.
+    class UnknownSchemaVersionError < UnknownSchemaError
+    end
   end
 end