rsmp_schema 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 07e5fccae77303733072ab27976c1cb1991ea9cd1add360dbac63e8da97baf8b
+  data.tar.gz: 364e6d5569d3fa262a96de68b80bec855d4fd3bb06c754ee47c5bcc3ea9300c4
+SHA512:
+  metadata.gz: d9a41e3ef2a8f1ce2ed30b701867b118fdaad9fc7f2bced0ca3637a65f242bb69735715e1d41d5bf7ea20690c2280cad7bdbd3b33ce2d0e137f218517967f3d8
+  data.tar.gz: 9885c98876461dab7abc379206ee2617ffb6747fe96a91dec3c382d9111029b3a98ad9a389a6b2ea311db1d4d98e66ead63bf8baf5a7b020c3f520878bad4d54

data/.gitignore

@@ -0,0 +1,6 @@
+/.bundle/
+/pkg/
+/spec/reports/
+/tmp/
+/.DS_Store
+/.rspec_status

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in rsmp_schema.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,49 @@
+PATH
+  remote: .
+  specs:
+    rsmp_schema (0.1.0)
+      json_schemer (~> 0.2.21)
+      thor (~> 1.2.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.5.0)
+    ecma-re-validator (0.4.0)
+      regexp_parser (~> 2.2)
+    hana (1.3.7)
+    json_schemer (0.2.21)
+      ecma-re-validator (~> 0.3)
+      hana (~> 1.3)
+      regexp_parser (~> 2.0)
+      uri_template (~> 0.7)
+    rake (13.0.6)
+    regexp_parser (2.5.0)
+    rspec (3.11.0)
+      rspec-core (~> 3.11.0)
+      rspec-expectations (~> 3.11.0)
+      rspec-mocks (~> 3.11.0)
+    rspec-core (3.11.0)
+      rspec-support (~> 3.11.0)
+    rspec-expectations (3.11.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.11.0)
+    rspec-mocks (3.11.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.11.0)
+    rspec-support (3.11.0)
+    thor (1.2.1)
+    uri_template (0.7.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 2.3.19)
+  rake (~> 13.0.6)
+  rsmp_schema!
+  rspec (~> 3.11.0)
+  rspec-expectations (~> 3.11.0)
+
+BUNDLED WITH
+   2.3.19

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2019 The City Copenhagen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,73 @@
+# About
+JSON Schema for RSMP messages. The schema can be used to automatically validate RSMP messages.
+
+The schema so far covers the core specifiation and the SXL for Trafic Light Controllers:
+https://github.com/rsmp-nordic/rsmp_core
+https://github.com/rsmp-nordic/rsmp_sxl_traffic_lights
+
+More about JSON Schema:
+https://json-schema.org/
+
+## Schema organisation
+The schema consists of a core schema shared by all equipment types, and an SXL schema for each supported equipment type. At the only SXL supported is for Traffic Light Controllers. An SXL defines massages specific to a particular type of equipment, but they all rely on the core part of the RSMP specification.
+
+Both core and SXL schemas exist in different version, for validation agaist a particular version of the spec.
+
+For example, to validate against the SXL for Trafic Light Controllers (TLCs), version 1.0.15, use the file schemas/tcl/1.0.15/sxl.json.
+
+Depending on the message type, relevant JSON Schema elements will be included to validate the detailed parameters, arguments, etc.
+
+For example, validating a CommandRequest M0001 message will include these parts:
+
+```
+sxl.json
+  commands.json
+    M0001.json
+```
+
+##  Usage
+The JSON Schema can be used from any language that provides a suitable JSON Schema validation library.
+
+For example, to validate a JSON message with Ruby using the json_schemer gem:
+
+```ruby
+require 'json_schemer'
+
+message = {
+  "mType" => "rSMsg",
+  "mId" => "4173c2c8-a933-43cb-9425-66d4613731ed",
+  "type" => "CommandRequest",
+  "siteId" => [
+    { "sId" => "RN+SI0001" }
+  ],
+  "cId" => "O+14439=481WA001",
+  "arg" => [
+    {
+      "cCI" => "M0001",
+      "n" => "status",
+      "cO" => "setValue",
+      "v" => "YellowFlash"
+    }
+  ]
+}
+
+# try validating a message against our schema
+schema = Pathname.new('schemas/tlc/1.1/sxl.json')
+schemer = JSONSchemer.schema(schema)
+puts schemer.valid? message     # => true
+```
+
+## RSpec tests
+The reposity includes RSpec test written in Ruby that checks the schema, by testing the result of validating a set of RSMP messages using the json_schemer gem.
+
+To run the tests, you need Ruby installed. Then run bundler to ensure you have rspec. Then run use the rspec command to run tests:
+
+```
+$ bundle              # install gems
+$ bundle exec rspec   # run rspec tests
+```
+
+## Schema maintenance
+The SXL JSON Schemas are generated automatically from their corresponding YAML source, and should therefore not be edited by hand. Instead, edit the YAML source and regenerate the schema files.
+
+The core schemas has no YAML sources and are maintained by hand.

data/Rakefile

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+require "bundler/gem_tasks"
+require "bundler/setup"
+require "rsmp_schema"
+
+
+task default: %i[]
+
+# Regenerate all SXL JSON Schemas.
+# Warning: This will destructively override all relevant files. Any changes will be lost!
+task :regenerate do
+  puts "Regenerating SXL JSON Schemas:"
+  Dir.glob('schemas/tlc/*/sxl.yaml').each do |path|
+    puts "  #{File.dirname(path)}"
+    sxl = RSMP::Convert::Import::YAML.read path
+    RSMP::Convert::Export::JSONSchema.write sxl, File.dirname(path)
+  end
+end

data/examples/validate.rb

@@ -0,0 +1,32 @@
+require 'json_schemer'
+
+message = {
+  "mType" => "rSMsg",
+  "mId" => "4173c2c8-a933-43cb-9425-66d4613731ed",
+  "type" => "CommandRequest",
+  "siteId" => [
+    { "sId" => "RN+SI0001" }
+  ],
+  "cId" => "O+14439=481WA001",
+  "arg" => [
+    {
+      "cCI" => "M0002",
+      "n" => "timeplan",
+      "cO" => "setPlan",
+      "v" => "1"
+    }
+  ]
+}
+
+# try validating a message against our schema
+schema = Pathname.new('schema/tlc/sxl.json')
+schemer = JSONSchemer.schema(schema)
+if schemer.valid? message
+  puts 'ok'
+else
+  schemer.validate(message).each do |item|
+    puts [item['data_pointer'],item['type'],item['details']].compact.join(' ')
+  end
+end
+
+

data/exe/rsmp_schema

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+require 'bundler/setup'
+require 'rsmp_schema/cli'
+RSMP::Schema::CLI.start

data/lib/rsmp_schema/cli.rb

@@ -0,0 +1,35 @@
+require 'thor'
+require 'rsmp_schema'
+
+module RSMP::Schema
+  class CLI < Thor
+    desc "convert", "Convert SXL from YAML to JSON Schema"
+    method_option :in, :type => :string, :aliases => "-i", banner: 'Path to YAML input file'
+    method_option :out, :type => :string, :aliases => "-o", banner: 'Path to JSON Schema output file'
+    def convert
+      unless options[:in]
+        puts "Error: Input option missing"
+        exit
+      end
+
+      unless options[:out]
+        puts "Error: Output option missing"
+        exit
+      end
+
+      unless File.exist? options[:in]
+        puts "Error: Input path file #{options[:in]} not found"
+        exit
+      end
+
+      sxl = RSMP::Convert::Import::YAML.read options[:in]
+      RSMP::Convert::Export::JSONSchema.write sxl, options[:out]
+    end
+
+    # avoid Thor returnin 0 on failures, see
+    # https://github.com/coinbase/salus/pull/380/files
+    def self.exit_on_failure?
+      true
+    end
+  end
+end

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

@@ -0,0 +1,223 @@
+# Import SXL from YAML format
+
+require 'yaml'
+require 'json'
+require 'fileutils'
+
+module RSMP
+  module Convert
+    module Export
+      module JSONSchema
+
+        @@json_options = {
+          array_nl: "\n",
+          object_nl: "\n",
+          indent: '  ',
+          space_before: ' ',
+          space: ' '
+        }
+
+        def self.output_json item
+          JSON.generate(item,@@json_options)
+        end
+
+        def self.build_value item
+          out = {}
+
+          if item['description']
+            out["description"] = item['description']
+          end
+
+          if item['list']
+            case item['type']
+            when "boolean"
+              out["$ref"] = "../../../core/3.1.1/definitions.json#/boolean_list"
+            when "integer", "ordinal", "unit", "scale", "long"
+              out["$ref"] = "../../../core/3.1.1/definitions.json#/integer_list"
+            when "string"
+              out["$ref"] = "../../../core/3.1.1/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('|')
+              out['pattern'] = /(?-mix:^(#{value_list})(?:,(#{value_list}))*$)/
+            end
+
+            if item["pattern"]
+              puts "Warning: Pattern not support for lists: #{item.inspect}"
+            end
+          else
+            case item['type']
+            when "string", "base64"
+              out["type"] = "string"
+            when "boolean"
+              out["$ref"] = "../../../core/3.1.1/definitions.json#/boolean"
+            when "timestamp"
+              out["$ref"] = "../../../core/3.1.1/definitions.json#/timestamp"
+            when "integer", "ordinal", "unit", "scale", "long"
+              out["$ref"] = "../../../core/3.1.1/definitions.json#/integer"
+            else
+              out["type"] = "string"
+            end
+
+            if item["values"]
+              case item["values"]
+              when Hash
+                out["enum"] = item["values"].keys.sort
+              when Array
+                out["enum"] = item["values"].sort
+              else
+                raise "Error: Values must be specified as either a Hash or an Array"
+              end
+
+            end
+
+            if item["pattern"]
+              out["pattern"] = item["pattern"]
+            end
+          end
+
+          # with draft-07 and older, using a $ref mean all other properties are ignored.
+          # to avoid this we need to use an allOf.
+          # this is changed from draft-08, but unfortunately, there is still no Ruby validator for that
+          if out.keys.include? '$ref'
+            ref = out.delete '$ref'
+            { "allOf" => [out,{"$ref"=>ref}]}
+          else
+            out
+          end
+        end
+
+        def self.build_item item, property_key: 'v'
+          json = { "allOf" => [ { "description" => item['description'] } ] }
+          if item['arguments']
+            json["allOf"].first["properties"] = { "n" => { "enum" => item['arguments'].keys.sort } }
+            item['arguments'].each_pair do |key,argument|
+              json["allOf"] << {
+                "if" => { "required" => ["n"], "properties" => { "n" => { "const" => key }}},
+                "then" => { "properties" => { property_key => build_value(argument) } }
+              }
+            end
+          end
+          json
+        end
+
+        def self.output_alarms out, items
+          list = items.keys.sort.map do |key|
+            {
+              "if" => { "required" => ["aCId"], "properties" => { "aCId" => { "const" => key }}},
+              "then" => { "$ref" => "#{key}.json" }
+            }
+          end
+          json = {
+            "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 }
+        end
+
+        def self.output_alarm out, key, item
+          json = build_item item
+          out["alarms/#{key}.json"] = output_json json
+        end
+
+        def self.output_statuses out, items
+          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" }
+            }
+          end
+          json = { "properties" => { "sS" => { "items" => { "allOf" => list }}}}
+          out['statuses/statuses.json'] = output_json json
+          items.each_pair { |key,item| output_status out, key, item }
+        end
+
+        def self.output_status out, key, item
+          json = build_item item, property_key:'s'
+          out["statuses/#{key}.json"] = output_json json
+        end
+
+        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" }
+            }
+          end
+          json = { "items" => { "allOf" => list }}
+          out['commands/commands.json'] = output_json json
+
+          json = { "properties" => { "arg" => { "$ref" => "commands.json" }}}
+          out['commands/command_requests.json'] = output_json json
+
+          json = { "properties" => { "rvs" => { "$ref" => "commands.json" }}}
+          out['commands/command_responses.json'] = output_json json
+
+          items.each_pair { |key,item| output_command out, key, item }
+        end
+
+        def self.output_command out, key, item
+          json = build_item item
+          json["allOf"].first["properties"]['cO'] = { "const" => item['command'] }
+          out["commands/#{key}.json"] = output_json json
+        end
+
+        def self.output_root out, meta
+          json = {
+            "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" }
+              }
+            ]
+          }
+          out["sxl.json"] = output_json json
+        end
+
+        def self.generate sxl
+          out = {}
+          output_root out, sxl[:meta]
+          output_alarms out, sxl[:alarms]
+          output_statuses out, sxl[:statuses]
+          output_commands out, sxl[:commands]
+          out
+        end
+
+        def self.write sxl, folder
+          out = generate sxl
+          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
+          end
+        end
+
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# Import SXL from YAML format
+
+require 'yaml'
+require 'json'
+require 'fileutils'
+
+module RSMP
+  module Convert
+    module Import
+      module YAML
+
+        def self.read path
+          convert ::YAML.load_file(path)
+        end
+
+        def self.parse str
+          convert ::YAML.load(str)
+        end
+
+        def self.convert yaml
+          sxl = {
+            meta: {},
+            alarms: {},
+            statuses: {},
+            commands: {}
+          }
+
+          sxl[:meta] = yaml['meta']
+
+          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"]
+          end
+          sxl
+        end
+      end
+
+    end
+  end
+end

data/lib/rsmp_schema/error.rb

@@ -0,0 +1,13 @@
+module RSMP::Schema
+  class Error < StandardError
+  end
+
+  class UnknownSchemaError < Error
+  end
+
+  class UnknownSchemaTypeError < UnknownSchemaError
+  end
+
+  class UnknownSchemaVersionError < UnknownSchemaError
+  end
+end

data/lib/rsmp_schema/schema.rb

@@ -0,0 +1,102 @@
+require 'json_schemer'
+
+module RSMP
+end
+
+module RSMP::Schema
+  @@schemas = nil
+
+  def self.schemas
+    return @@schemas if @@schemas
+    schemas_path = File.expand_path( File.join(__dir__,'..','..','schemas') )
+    @@schemas = {
+      core: {
+        '3.1.1' => JSONSchemer.schema( Pathname.new(File.join(schemas_path, 'core','3.1.1','rsmp.json')) ),
+        '3.1.2' => JSONSchemer.schema( Pathname.new(File.join(schemas_path, 'core','3.1.2','rsmp.json')) ),
+        '3.1.3' => JSONSchemer.schema( Pathname.new(File.join(schemas_path, 'core','3.1.3','rsmp.json')) ),
+        '3.1.4' => JSONSchemer.schema( Pathname.new(File.join(schemas_path, 'core','3.1.4','rsmp.json')) ),
+        '3.1.5' => JSONSchemer.schema( Pathname.new(File.join(schemas_path, 'core','3.1.5','rsmp.json')) ),
+        '3.2'   => JSONSchemer.schema( Pathname.new(File.join(schemas_path, 'core','3.2',  'rsmp.json')) )
+      },
+      # note that tlc 1.0.11 and 1.0.12 does not exist (unreleased drafts)
+      tlc: {
+        '1.0.7'  => JSONSchemer.schema( Pathname.new(File.join(schemas_path, 'tlc','1.0.7' ,'sxl.json')) ),
+        '1.0.8'  => JSONSchemer.schema( Pathname.new(File.join(schemas_path, 'tlc','1.0.8' ,'sxl.json')) ),
+        '1.0.9'  => JSONSchemer.schema( Pathname.new(File.join(schemas_path, 'tlc','1.0.9' ,'sxl.json')) ),
+        '1.0.10' => JSONSchemer.schema( Pathname.new(File.join(schemas_path, 'tlc','1.0.10','sxl.json')) ),
+        '1.0.13' => JSONSchemer.schema( Pathname.new(File.join(schemas_path, 'tlc','1.0.13','sxl.json')) ),
+        '1.0.14' => JSONSchemer.schema( Pathname.new(File.join(schemas_path, 'tlc','1.0.14','sxl.json')) ),
+        '1.0.15' => JSONSchemer.schema( Pathname.new(File.join(schemas_path, 'tlc','1.0.15','sxl.json')) ),
+        '1.1'    => JSONSchemer.schema( Pathname.new(File.join(schemas_path, 'tlc','1.1',   'sxl.json')) )
+      }
+    }
+  end
+
+  def self.validate_using_schema message, schema
+    raise ArgumentError.new("message missing") unless message
+    raise ArgumentError.new("schema missing") unless schema
+    unless schema.valid? message
+      schema.validate(message).map do |item|
+        [item['data_pointer'],item['type'],item['details']]
+      end
+    else
+      []
+    end
+  end
+
+  def self.find_schemas type
+    raise ArgumentError.new("type missing") unless type
+    schemas[type.to_sym]
+  end
+
+  def self.find_schemas! type
+    schemas = find_schemas type
+    raise UnknownSchemaTypeError.new("Unknown schema type #{type}") unless schemas
+    schemas
+  end
+
+  def self.find_schema type, version, options={}
+    raise ArgumentError.new("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
+
+  def self.sanitize_version version
+    matched = /^\d+\.\d+(\.\d+)?/.match version
+    matched.to_s if matched
+  end
+
+  def self.find_schema! type, version, options={}
+    schema = find_schema type, version, options
+    raise ArgumentError.new("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.new("Unknown schema version #{type} #{version}")
+  end
+
+  def self.has_schema? type, version, options={}
+    find_schema(type,version, options) != nil
+  end
+
+  def self.validate message, schemas, options={}
+    raise ArgumentError.new("message missing") unless message
+    raise ArgumentError.new("schemas missing") unless schemas
+    raise ArgumentError.new("schemas must be a Hash") unless schemas.is_a?(Hash)
+    raise ArgumentError.new("schemas cannot be empty") unless schemas.any?
+    errors = schemas.flat_map do |type, version|
+      schema = find_schema! type, version, options
+      validate_using_schema(message, schema)
+    end
+    return nil if errors.empty?
+    errors
+  end
+
+end

data/lib/rsmp_schema/version.rb

@@ -0,0 +1,5 @@
+module RSMP
+  module Schema
+    VERSION = "0.1.0"
+  end
+end

data/lib/rsmp_schema.rb

@@ -0,0 +1,7 @@
+require 'yaml'
+require 'json_schemer'
+require 'rsmp_schema/error'
+require 'rsmp_schema/schema'
+require 'rsmp_schema/convert/import/yaml'
+require 'rsmp_schema/convert/export/json_schema'
+require 'rsmp_schema/version'