aspera-cli 4.26.0 → 4.26.1

data/lib/aspera/cli/plugins/aoc.rb

@@ -304,7 +304,7 @@ module Aspera
         # @param fields fields to display
         # @param base_query a query applied always
         # @param default_query default query unless overridden by user
-        # @param &block (Optional) calls block with user's or default query
+        # @yieldparam query [Hash] The user's or default query for modification
         def result_list(resource_class_path, fields: nil, base_query: {}, default_query: {})
           Aspera.assert_type(base_query, Hash)
           Aspera.assert_type(default_query, Hash)
@@ -402,34 +402,50 @@ module Aspera
         # Execute an action on admin resources
         # @param resource_type [Symbol] One of ADMIN_OBJECTS
         def execute_resource_action(resource_type)
+          # Set to `true` is resource creation requires a workspace id
           require_workspace_id = false
+          # Default fields to display
           list_default_fields = %w[id name]
+          # Default query for `list` action
           list_default_query = {}
+          # In result of create, what is the field that contains the id of the created resource
+          id_result = 'id'
           supported_operations = Operations::ALL
+          # API path
           resource_class_path = "#{resource_type}s"
+          # path in openapi where post is located to get creation schema
+          create_schema_path = resource_class_path
           case resource_type
           when :client
             supported_operations += %i[set_pub_key]
+            # schema_create_modify = Schema::Registry.req_body(Schema::Registry::AOC, "#{resource_class_path}.post")
           when :client_access_key
             resource_class_path = "admin/#{resource_type}s"
           when :client_registration_token
             resource_class_path = "admin/#{resource_type}s"
-            list_default_fields = %w[id value data.client_subject_scopes created_at]
+            list_default_fields = %w[id value data.client_subject_scopes data.name created_at]
+            id_result = 'token'
           when :contact
             list_default_fields = %w[source_type source_id name email]
             # list_default_query = {'include_only_user_personal_contacts' => true} if @scope == Api::AoC::Scope::USER
           when :dropbox
             require_workspace_id = true
             resource_class_path = "#{resource_type}es"
+            create_schema_path = resource_class_path
+          when :group, :saml_configuration
+            create_schema_path = nil
           when :group_membership
             list_default_fields = %w[id group_id member_type member_id]
+            create_schema_path = nil
           when :kms_profile
             resource_class_path = "integrations/#{resource_type}s"
+            create_schema_path = nil
           when :node
             list_default_fields = %w[id name host access_key]
             supported_operations += %i[do bearer_token]
           when :operation
-            list_default_fields = nil
+            list_default_fields = %w[id type status created_at updated_at workspace_id user_id workspace_membership_id group_membership_id]
+            supported_operations = %i[list show modify]
           when :organization, :self
             supported_operations = Operations::SINGLETON
             resource_instance_path = resource_class_path = resource_type
@@ -443,6 +459,8 @@ module Aspera
           when :workspace_membership
             list_default_fields = %w[id workspace_id member_type member_id]
           end
+          # Default location of creation payload in schema
+          schema_create_modify = Schema::Registry.req_body(Schema::Registry::AOC, "#{create_schema_path}.post") if create_schema_path && supported_operations.include?(:create)
           command = options.get_next_command(supported_operations)
           # Require identifier for non global commands
           if (supported_operations != Operations::SINGLETON) && !Operations::GLOBAL.include?(command)
@@ -451,12 +469,10 @@ module Aspera
           end
           case command
           when :create
-            id_result = 'id'
-            id_result = 'token' if resource_class_path.eql?('admin/client_registration_tokens')
             # TODO: report inconsistency: creation url is !=, and does not return id.
             resource_class_path = 'admin/client_registration/token' if resource_class_path.eql?('admin/client_registration_tokens')
             workspace_id = aoc_api.workspace_info[:id] if require_workspace_id
-            return do_bulk_operation(command: command, descr: 'creation data', id_result: id_result) do |params|
+            return do_bulk_operation(command: command, descr: 'creation data', id_result: id_result, schema: schema_create_modify) do |params|
               params['workspace_id'] = workspace_id if require_workspace_id && workspace_id && !params.key?('workspace_id')
               aoc_api.create(resource_class_path, params)
             end
@@ -466,7 +482,7 @@ module Aspera
             object = aoc_api.read(resource_instance_path, query_read_delete)
             return Main.result_single_object(object, fields: Formatter.all_but('certificate'))
           when :modify
-            changes = options.get_next_argument('properties', validation: Hash)
+            changes = options.get_next_argument('properties', validation: Hash, schema: schema_create_modify)
             return do_bulk_operation(command: command, values: res_id) do |one_id|
               aoc_api.update("#{resource_class_path}/#{one_id}", changes)
               {'id' => one_id}
@@ -503,12 +519,18 @@ module Aspera
             query = options.get_option(:query) || Api::AoC.workspace_access(res_id).merge({'admin' => true})
             shared_folders = aoc_api.read_with_paging("#{resource_instance_path}/permissions", query)[:items]
             # inside a workspace
-            command_shared = options.get_next_command(%i[list member])
+            command_shared = options.get_next_command(%i[list node member])
             case command_shared
             when :list
               return Main.result_object_list(shared_folders, fields: %w[id node_name node_id file_id file.path tags.aspera.files.workspace.share_as])
+            when :node
+              shared_folder_id = options.instance_identifier(description: 'Shared folder ID')
+              shared_folder = shared_folders.find{ |i| i['id'].eql?(shared_folder_id)}
+              Aspera.assert(shared_folder)
+              command_repo = options.get_next_command(FILES_COMMANDS)
+              return execute_nodegen4_command(command_repo, shared_folder['node_id'], file_id: shared_folder['file_id'], scope: Api::Node::Scope::ADMIN)
             when :member
-              shared_folder_id = options.instance_identifier
+              shared_folder_id = options.instance_identifier(description: 'Shared folder ID')
               shared_folder = shared_folders.find{ |i| i['id'].eql?(shared_folder_id)}
               Aspera.assert(shared_folder)
               command_shared_member = options.get_next_command(%i[list])
@@ -825,7 +847,10 @@ module Aspera
         # - a resource id, e.g. `scQ7uXPbvQ`
         # - a short URL path, e.g. `dxyRpT9`
         # @param shared_data [Hash] Information for shared data: dropbox_id+name or file_id+node_id
-        # @param &perm_block [Proc] Optional: create/modify/delete permissions on node
+        # @param shared_data [Hash] Shared data for the short link
+        # @yieldparam operation [Symbol] Operation type (:create, :update, :delete)
+        # @yieldparam resource_id [String] Resource ID for permission management
+        # @yieldparam access_levels [Object] Access levels for permissions
         def short_link_command(**shared_data, &perm_block)
           link_type = options.get_next_argument('link access (public or private)', accept_list: %i[public private])
           if shared_data.keys.sort == %i[dropbox_id name]
@@ -1043,7 +1068,7 @@ module Aspera
                 return short_link_command(dropbox_id: get_resource_id_from_args('dropboxes'), name: '')
               end
             when :send
-              package_data = value_create_modify(command: package_command)
+              package_data = value_create_modify(command: package_command, schema: Schema::Registry.req_body(Schema::Registry::AOC, 'packages.post'))
               new_user_option = options.get_option(:new_user_option)
               option_validate = options.get_option(:validate_metadata)
               # Works for both normal user auth and link auth.

data/lib/aspera/cli/plugins/base.rb

@@ -37,15 +37,15 @@ module Aspera
         # Global objects
         attr_reader :context
 
-        # @return [Manager]
+        # @return [Aspera::Cli::Manager]
         def options; @context.options; end
-        # @return [TransferAgent]
+        # @return [Aspera::Cli::TransferAgent]
         def transfer; @context.transfer; end
-        # @return [Config]
+        # @return [Aspera::Cli::Plugins::Config]
         def config; @context.config; end
-        # @return [Formatter]
+        # @return [Aspera::Cli::Formatter]
         def formatter; @context.formatter; end
-        # @return [PersistencyFolder]
+        # @return [Aspera::PersistencyFolder]
         def persistency; @context.persistency; end
 
         def add_manual_header(has_options = true)
@@ -57,20 +57,23 @@ module Aspera
         end
 
         # For create and delete operations: execute one action or multiple if bulk is yes
-        # @param command   [Symbol] Operation: :create, :delete, ...
-        # @param descr     [String] Description of the value
-        # @param values    [Object] Value(s), or type of value to get from user
-        # @param id_result [String] Key in result hash to use as identifier
-        # @param fields    [Array]  Fields to display
-        # @param block     [Proc]   Block to execute for each value
-        def do_bulk_operation(command:, descr: nil, values: Hash, id_result: 'id', fields: :default, &block)
+        # @param command [Symbol] Operation: :create, :delete, ...
+        # @param descr [String, nil] Description of the value
+        # @param values [Class, Array, Symbol] Type, or list of values, or :identifier, result is given to the block in loop
+        # @param id_result [String] Key in result Hash to use as identifier
+        # @param fields [Symbol, Array] Fields to display
+        # @param schema [Hash, nil] JSON schema for validation
+        # @yieldparam param [Object] The parameter value to process
+        # @yieldreturn [Hash, nil] Result hash for the operation (optional)
+        # @return [Hash] Result suitable for CLI output
+        def do_bulk_operation(command:, descr: nil, values: Hash, id_result: 'id', fields: :default, schema: nil, &block)
           Aspera.assert(block_given?){'missing block'}
           is_bulk = options.get_option(:bulk)
           case values
           when :identifier
             values = options.instance_identifier(description: descr)
           when Class
-            values = value_create_modify(command: command, description: descr, type: values, bulk: is_bulk)
+            values = value_create_modify(command: command, description: descr, type: values, bulk: is_bulk, schema: schema)
           end
           # If not bulk, there is a single value
           params = is_bulk ? values : [values]
@@ -105,15 +108,17 @@ module Aspera
         end
 
         # Operations: Create, Delete, Show, List, Modify
-        # @param api            [Rest]    api to use
-        # @param entity         [String]  sub path in URL to resource relative to base url
-        # @param command        [Symbol]  command to execute: create show list modify delete
-        # @param display_fields [Array]   fields to display by default
-        # @param items_key      [String]  result is in a sub key of the json
-        # @param delete_style   [String]  If set, the delete operation by array in payload
-        # @param id_as_arg      [String]  If set, the id is provided as url argument ?<id_as_arg>=<id>
-        # @param is_singleton   [Boolean] If `true`, entity is the full path to the resource
-        # @param &block         [Proc]    Block to search for identifier based on attribute value
+        # @param api [Aspera::Rest] API to use
+        # @param entity [String] Sub path in URL to resource relative to base url
+        # @param command [Symbol, nil] Command to execute: :create, :show, :list, :modify, :delete
+        # @param display_fields [Array, nil] Fields to display by default
+        # @param items_key [String, nil] Result is in a sub key of the JSON
+        # @param delete_style [String, nil] If set, the delete operation by array in payload
+        # @param id_as_arg [Boolean, String] If set, the id is provided as url argument ?<id_as_arg>=<id>
+        # @param is_singleton [Boolean] If `true`, entity is the full path to the resource
+        # @param list_query [Hash, nil] Query parameters for list operation
+        # @yieldparam value [String] Value to search for identifier
+        # @yieldreturn [String] The identifier
         # @return [Hash] Result suitable for CLI result
         def entity_execute(
           api:,
@@ -189,6 +194,8 @@ module Aspera
         end
 
         # Query parameters in URL suitable for REST: list/`GET` and delete/`DELETE`
+        # @param default [Hash, nil] Default query parameters
+        # @return [Hash, nil] Query parameters
         def query_read_delete(default: nil)
           # Dup default, as it could be frozen
           query = options.get_option(:query) || default.dup
@@ -202,27 +209,29 @@ module Aspera
           return query
         end
 
-        # Retrieves an extended value from command line, used for creation or modification of entities
-        # @param command [Symbol]  command name for error message
-        # @param type    [Class]   expected type of value, either a Class, an Array of Class
-        # @param bulk    [Boolean] if true, value must be an Array of <type>
-        # @param default [Object]  default value if not provided
-        def value_create_modify(command:, description: nil, type: Hash, bulk: false, default: nil)
+        # Retrieves an extended value from command line.
+        # Used for creation or modification of entities.
+        # @param command [Symbol] Command name for error message
+        # @param description [String, nil] Description of the value
+        # @param type [Class, nil] Expected type of value
+        # @param bulk [Boolean] If `true`, value must be an Array of `type`
+        # @param default [Object, nil] Default value if not provided
+        # @param schema [Hash, nil] JSON schema for validation
+        # @return [Hash, Array<Hash>] The value(s) to create object(s)
+        def value_create_modify(command:, description: nil, type: Hash, bulk: false, default: nil, schema: nil)
           value = options.get_next_argument(
-            "parameters for #{command}#{" (#{description})" unless description.nil?}", mandatory: default.nil?,
-            validation: bulk ? Array : type
+            "parameters for #{command}#{" (#{description})" unless description.nil?}",
+            mandatory: default.nil?,
+            validation: bulk ? Array : type,
+            schema: schema
           )
           value = default if value.nil?
           unless type.nil?
-            type = [type] unless type.is_a?(Array)
-            Aspera.assert_array_all(type, Class){'check types'}
+            Aspera.assert_type(type, Class){'type'}
             if bulk
-              Aspera.assert_type(value, Array, type: Cli::BadArgument)
-              value.each do |v|
-                Aspera.assert_values(v.class, type, type: Cli::BadArgument)
-              end
+              Aspera.assert_array_all(value, type, type: Cli::BadArgument){'type'}
             else
-              Aspera.assert_values(value.class, type, type: Cli::BadArgument)
+              Aspera.assert_type(value, type, type: Cli::BadArgument){'type'}
             end
           end
           return value

data/lib/aspera/cli/plugins/config.rb

@@ -16,7 +16,7 @@ require 'aspera/sync/operations'
 require 'aspera/products/transferd'
 require 'aspera/transfer/parameters'
 require 'aspera/transfer/spec'
-require 'aspera/transfer/spec_doc'
+require 'aspera/schema/documentation'
 require 'aspera/keychain/macos_security'
 require 'aspera/proxy_auto_config'
 require 'aspera/environment'
@@ -436,7 +436,7 @@ module Aspera
         end
 
         def set_preset_key(preset, param_name, param_value)
-          Aspera.assert_values(param_name.class, [String, Symbol]){'parameter'}
+          Aspera.assert_type(param_name, String, Symbol){'parameter'}
           param_name = param_name.to_s
           selected_preset = @config_presets[preset]
           if selected_preset.nil?
@@ -598,10 +598,10 @@ module Aspera
           when :install
             return install_transfer_sdk
           when :spec
-            fields, data = Transfer::SpecDoc.man_table(Formatter, include_option: true)
-            return Main.result_object_list(data, fields: fields.map(&:to_s))
+            builder = Schema::Documentation.new(TerminalFormatter, Transfer::Spec::SCHEMA, include_option: true, agent_columns: true).build
+            return Main.result_object_list(builder.rows, fields: builder.columns)
           when :schema
-            schema = Transfer::Spec::SCHEMA.merge({'$comment'=>'DO NOT EDIT, this file was generated from the YAML.'})
+            schema = Transfer::Spec::SCHEMA.current.merge({'$comment'=>'DO NOT EDIT, this file was generated from the YAML.'})
             agent = options.get_next_argument('transfer agent name', mandatory: false)
             schema['properties'] = schema['properties'].select{ |_k, v| CommandLineBuilder.supported_by_agent(agent, v)} unless agent.nil?
             schema['properties'] = schema['properties'].sort.to_h
@@ -834,8 +834,8 @@ module Aspera
                 plugin_class = Plugins::Factory.instance.plugin_class(name)
                 result.push({
                   plugin: name,
-                  detect: Formatter.tick(plugin_class.respond_to?(:detect)),
-                  wizard: Formatter.tick(plugin_class.method_defined?(:wizard)),
+                  detect: TerminalFormatter.tick(plugin_class.respond_to?(:detect)),
+                  wizard: TerminalFormatter.tick(plugin_class.method_defined?(:wizard)),
                   path:   Plugins::Factory.instance.plugin_source(name)
                 })
               end
@@ -878,8 +878,8 @@ module Aspera
           when :sync
             case options.get_next_command(%i[spec admin translate])
             when :spec
-              fields, data = Transfer::SpecDoc.man_table(Formatter, include_option: true, agent_columns: false, schema: Sync::Operations::CONF_SCHEMA)
-              return Main.result_object_list(data, fields: fields.map(&:to_s))
+              builder = Schema::Documentation.new(TerminalFormatter, Sync::Operations::CONF_SCHEMA, include_option: true).build
+              return Main.result_object_list(builder.rows, fields: builder.columns)
             when :admin
               return execute_sync_admin
             when :translate

data/lib/aspera/cli/plugins/faspex.rb

@@ -165,7 +165,7 @@ module Aspera
         def mailbox_filtered_entries(stop_at_id: nil)
           recipient_names = [options.get_option(:recipient) || options.get_option(:username, mandatory: true)]
           # some workgroup messages have no star in recipient name
-          recipient_names.push(recipient_names.first[1..-1]) if recipient_names.first.start_with?('*')
+          recipient_names.push(recipient_names.first.delete_prefix('*')) if recipient_names.first.start_with?('*')
           # mailbox is in ATOM_MAILBOXES
           mailbox = options.get_option(:box, mandatory: true)
           # parameters

data/lib/aspera/cli/plugins/faspex5.rb

@@ -234,8 +234,8 @@ module Aspera
           result_transfer = []
           param_file_list = {}
           begin
-            param_file_list['paths'] = transfer.source_list.map{ |source| {'path'=>source}}
-          rescue Cli::BadArgument
+            param_file_list['paths'] = transfer.ts_source_paths
+          rescue Cli::MissingArgument
             # paths is optional
           end
           box = options.get_option(:box)
@@ -270,7 +270,7 @@ module Aspera
         end
 
         def package_send
-          parameters = value_create_modify(command: :send)
+          parameters = value_create_modify(command: :send, schema: Schema::Registry.req_body(Schema::Registry::FASPEX, 'packages.post'))
           # autofill recipient for public url
           if @api_v5.pub_link_context&.key?('recipient_type') && !parameters.key?('recipients')
             parameters['recipients'] = [{
@@ -494,8 +494,7 @@ module Aspera
           when :invite_external_collaborator
             # :shared_inboxes, :workgroups
             shared_inbox_id = options.instance_identifier{ |field, value| @api_v5.lookup_entity_by_field(entity: res_sym.to_s, field: field, value: value, query: res_id_query)['id']}
-            creation_payload = value_create_modify(command: res_command, type: [Hash, String])
-            creation_payload = {'email_address' => creation_payload} if creation_payload.is_a?(String)
+            creation_payload = value_create_modify(command: res_command)
             result = @api_v5.create("#{res_sym}/#{shared_inbox_id}/external_collaborator", creation_payload)
             formatter.display_status(result['message'])
             result = @api_v5.lookup_entity_by_field(

data/lib/aspera/cli/plugins/node.rb

@@ -41,7 +41,7 @@ module Aspera
 
           def remove_in_object_list!(obj_list)
             obj_list.each do |item|
-              item['path'] = item['path'][@root.length..-1] if item['path'].start_with?(@root)
+              item['path'] = item['path'].delete_prefix(@root) if item['path'].start_with?(@root)
             end
           end
         end

data/lib/aspera/cli/sync_actions.rb

@@ -27,7 +27,7 @@ module Aspera
       # @return [Hash] sync info
       def async_info_from_args(direction: nil)
         path = options.get_next_argument('path')
-        sync_info = options.get_next_argument('sync info', mandatory: false, validation: Hash, default: {})
+        sync_info = options.get_next_argument('sync info', mandatory: false, validation: Hash, default: {}, schema: Schema::Registry::SYNC_CONF)
         # is the positional path a remote path ?
         path_is_remote = direction.eql?(:pull)
         if sync_info.key?('sessions') || sync_info.key?('instance')

data/lib/aspera/cli/transfer_agent.rb

@@ -5,6 +5,7 @@ require 'aspera/transfer/spec'
 require 'aspera/cli/info'
 require 'aspera/log'
 require 'aspera/assert'
+require 'aspera/schema/registry'
 
 module Aspera
   module Cli
@@ -12,9 +13,9 @@ module Aspera
     # one of the supported transfer agents.
     # Provide CLI options to select one of the transfer agents (FASP/ascp client)
     class TransferAgent
-      # @args special value for --sources : read file list from arguments
+      # `@args` special value for --sources : read file list from arguments
       FILE_LIST_FROM_ARGS = '@args'
-      # @ts special value for --sources : read file list from transfer spec (--ts)
+      # `@ts` special value for --sources : read file list from transfer spec (--ts)
       FILE_LIST_FROM_TRANSFER_SPEC = '@ts'
       FILE_LIST_OPTIONS = [FILE_LIST_FROM_ARGS, FILE_LIST_FROM_TRANSFER_SPEC, 'Array'].freeze
       DEFAULT_TRANSFER_NOTIFY_TEMPLATE = <<~END_OF_TEMPLATE
@@ -63,12 +64,12 @@ module Aspera
         @transfer_paths = nil
         # HTTPGW URL provided by webapp
         @httpgw_url_lambda = nil
-        @opt_mgr.declare(:ts, 'Override transfer spec values', allowed: Hash, handler: {o: self, m: :user_transfer_spec})
+        @opt_mgr.declare(:ts, 'Override transfer spec values', allowed: Hash, handler: {o: self, m: :user_transfer_spec}, schema: Schema::Registry::TRANSFER_SPEC)
         @opt_mgr.declare(:to_folder, 'Destination folder for transferred files')
         @opt_mgr.declare(:sources, "How list of transferred files is provided (#{FILE_LIST_OPTIONS.join(',')})", default: FILE_LIST_FROM_ARGS)
         @opt_mgr.declare(:src_type, 'Type of file list', allowed: %i[list pair], default: :list)
         @opt_mgr.declare(:transfer, 'Type of transfer agent', allowed: Agent::Factory::ALL.keys, default: :direct)
-        @opt_mgr.declare(:transfer_info, 'Parameters for transfer agent', allowed: Hash, handler: {o: self, m: :transfer_info})
+        @opt_mgr.declare(:transfer_info, 'Parameters for transfer agent', allowed: Hash, handler: {o: self, m: :transfer_info}, schema: Schema::Registry::TRANSFER_INFO)
         @opt_mgr.parse_options!
         @notification_cb = nil
         if !@opt_mgr.get_option(:notify_to).nil?
@@ -154,24 +155,25 @@ module Aspera
       end
 
       # Transform the list of paths to a list of hash with source/dest
-      # @param file_list [Array]
+      # @param file_list [Array<Hash>]
       def list_to_paths(file_list)
         source_type = @opt_mgr.get_option(:src_type, mandatory: true)
-        case source_type
-        when :list
-          # when providing a list, just specify source
-          @transfer_paths = file_list.map{ |i| {'source' => i}}
-        when :pair
-          Aspera.assert(file_list.length.even?, type: Cli::BadArgument){"When using pair, provide an even number of paths: #{file_list.length}"}
-          @transfer_paths = file_list.each_slice(2).map{ |s, d| {'source' => s, 'destination' => d}}
-        else Aspera.error_unexpected_value(source_type)
-        end
+        @transfer_paths =
+          case source_type
+          when :list
+            # when providing a list, just specify source
+            file_list.map{ |i| {'source' => i}}
+          when :pair
+            Aspera.assert(file_list.length.even?, type: Cli::BadArgument){"When using pair, provide an even number of paths: #{file_list.length}"}
+            file_list.each_slice(2).map{ |s, d| {'source' => s, 'destination' => d}}
+          else Aspera.error_unexpected_value(source_type)
+          end
       end
 
       # This is how the list of files to be transferred is specified
       # get paths suitable for transfer spec from command line
       # computation is done only once, cache is kept in @transfer_paths
-      # @param default [Array] of [String] if set, used as default file for --sources=@args
+      # @param default [nil, Array<String>] If set, used as default file for --sources=@args
       # @return [Array, nil] of Hash {source: (mandatory), destination: (optional)}
       def ts_source_paths(default: nil)
         # return cache if set

data/lib/aspera/cli/version.rb

@@ -4,6 +4,6 @@ module Aspera
   module Cli
     # For beta add extension : .beta1
     # For dev version add extension : .pre
-    VERSION = '4.26.0'
+    VERSION = '4.26.1'
   end
 end

data/lib/aspera/command_line_builder.rb

@@ -2,6 +2,7 @@
 
 require 'aspera/log'
 require 'aspera/assert'
+require 'aspera/schema/registry'
 require 'yaml'
 module Aspera
   # Helper class to build command line from a parameter list (key-value hash)
@@ -35,9 +36,9 @@ module Aspera
 
     class << self
       # Called by provider of definition before constructor of this class so that schema has all mandatory fields
-      def read_schema(folder, name, ascp: false)
-        schema = YAML.load_file(File.join(folder, "#{name}.schema.yaml"))
-        validate_schema(schema, ascp: ascp)
+      # @return [Aspera::Schema::Reader]
+      def read_schema(name_sym, ascp: false)
+        validate_schema(Schema::Registry.instance.reader(name_sym), ascp: ascp)
       end
 
       # @param agent      [Symbol] Transfer agent name
@@ -49,29 +50,32 @@ module Aspera
 
       private
 
+      DIRECT_PROPERTIES = %w[x-cli-option x-cli-envvar x-cli-special].freeze
+
       # Fill default values for some fields in the schema
-      # @param schema [Hash]    The JSON schema
-      # @param ascp   [Boolean] `true` if ascp
+      # @param schema [Schema::Reader] The JSON schema
+      # @param ascp [Boolean] `true` if `ascp`
+      # @return [Schema::Reader] The JSON schema
       def validate_schema(schema, ascp: false)
-        direct_props = %w[x-cli-option x-cli-envvar x-cli-special].freeze
-        schema['properties'].each do |name, info|
-          Aspera.assert_type(info, Hash){"#{info.class} for #{name}"}
-          unsupported_keys = info.keys - PROPERTY_KEYS
+        Aspera.assert_type(schema, Schema::Reader){'schema'}
+        Aspera.assert(schema.current.key?('properties')){"Schema must have 'properties': #{schema}"}
+        schema.each_property do |property_schema, name, _full_name|
+          node = property_schema.current
+          unsupported_keys = node.keys - PROPERTY_KEYS
           Aspera.assert(unsupported_keys.empty?){"Unsupported definition keys: #{unsupported_keys}"}
-          Aspera.assert(info.key?('type') || info.key?('enum')){"Missing type for #{name} in #{schema['description']}"}
-          Aspera.assert(info['type'].eql?('boolean')){"switch must be bool: #{name}"} if info['x-cli-switch'] && !info['x-cli-special']
-          info['x-cli-option'] = "--#{name.to_s.tr('_', '-')}" if info['x-cli-option'].eql?(true) || (info['x-cli-switch'].eql?(true) && !info.key?('x-cli-option'))
-          Aspera.assert(direct_props.any?{ |i| info.key?(i)}, type: :warn){name} if ascp && supported_by_agent(:direct, info)
-          info.freeze
-          validate_schema(info, ascp: ascp) if info['type'].eql?('object') && info['properties']
-          validate_schema(info['items'], ascp: ascp) if info['type'].eql?('array') && info['items'] && info['items']['properties']
+          Aspera.assert(node.key?('type') || node.key?('enum')){"Missing type for #{name} in #{schema.current.dig('description').current}"}
+          Aspera.assert(node['type'].eql?('boolean')){"switch must be bool: #{name}"} if node['x-cli-switch'] && !node['x-cli-special']
+          node['x-cli-option'] = "--#{name.to_s.tr('_', '-')}" if node['x-cli-option'].eql?(true) || (node['x-cli-switch'].eql?(true) && !node.key?('x-cli-option'))
+          Aspera.assert(DIRECT_PROPERTIES.any?{ |i| node.key?(i)}, type: :warn){name} if ascp && supported_by_agent(:direct, node)
+          node.freeze
         end
         schema
       end
     end
 
-    # @param [Hash] object with parameters
-    # @param [Hash] schema JSON schema
+    # @param object [Hash] object with parameters
+    # @param schema [Schema::Reader] JSON schema
+    # @param convert [Object] function to convert value
     def initialize(object, schema, convert)
       @object = object # keep reference so that it can be modified by caller before calling `process_params`
       @schema = schema

data/lib/aspera/environment.rb

@@ -151,7 +151,7 @@ module Aspera
       # @param path [String] the file path
       # @param force [Boolean] if true, overwrite the file
       # @param mode [Integer] the file mode (permissions)
-      # @block [Proc] return the content to write to the file
+      # @yieldreturn [String] The content to write to the file
       def write_file_restricted(path, force: false, mode: nil)
         Aspera.assert(block_given?, type: Aspera::InternalError)
         if force || !File.exist?(path)
@@ -280,7 +280,7 @@ module Aspera
       when Environment::OS_MACOS then return self.class.secure_execute('open', uri.to_s)
       when Environment::OS_WINDOWS then return self.class.secure_execute('start', 'explorer', %Q{"#{uri}"})
       when Environment::OS_LINUX   then return self.class.secure_execute('xdg-open', uri.to_s)
-      else Assert.error_unexpected_value(os){'no graphical open method'}
+      else Aspera.error_unexpected_value(os){'no graphical open method'}
       end
     end
 
@@ -334,7 +334,7 @@ module Aspera
       filename = filename.chop while filename.end_with?(' ', '.')
       if @file_illegal_characters&.size.to_i >= 2
         # replace all illegal characters with safe_char
-        filename = filename.tr(@file_illegal_characters[1..-1], safe_char)
+        filename = filename.tr(@file_illegal_characters[1..], safe_char)
       end
       # ensure only one safe_char is used at a time
       return filename.gsub(/#{Regexp.escape(safe_char)}+/, safe_char).chomp(safe_char)

data/lib/aspera/formatter_interface.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'aspera/assert'
+
+module Aspera
+  # Common interface for documentation formatters
+  # Used by Schema::Documentation to format tables
+  module FormatterInterface
+    Aspera.require_method!(:tick)
+    Aspera.require_method!(:special_format)
+    Aspera.require_method!(:check_row)
+    Aspera.require_method!(:markdown_text)
+  end
+end

data/lib/aspera/hash_ext.rb

@@ -9,6 +9,12 @@ class ::Hash
     merge!(second){ |_key, v1, v2| v1.is_a?(Hash) && v2.is_a?(Hash) ? v1.deep_merge!(v2) : v2}
   end
 
+  # Recursively iterate through hash and execute block on leaf values
+  # @param memory [Object, nil] Optional memory object passed to block
+  # @yieldparam hash [Hash] The current hash
+  # @yieldparam key [Object] The current key
+  # @yieldparam value [Object] The current value (non-Hash)
+  # @yieldparam memory [Object, nil] The memory object
   def deep_do(memory = nil, &block)
     each do |key, value|
       if value.is_a?(Hash)

data/lib/aspera/log.rb

@@ -77,7 +77,7 @@ module Aspera
       # @param name   [String, Symbol]  Name of object dumped
       # @param object [Hash, nil]       Data to dump
       # @param level  [Symbol]          Debug level
-      # @param block  [Proc, nil]       Give computed object
+      # @yieldreturn [Object] Computed object to dump (alternative to object parameter)
       def dump(name, object = nil, level: :debug, &block)
         return unless instance.logger.send(:"#{level}?")
         Aspera.assert(object.nil? || block.nil?){'Use either object, or block, not both'}
@@ -93,12 +93,13 @@ module Aspera
             JSON.pretty_generate(object) rescue PP.pp(object, +'')
           when :ruby
             PP.pp(object, +'')
-          else error_unexpected_value(instance.dump_format){'dump format'}
+          else Aspera.error_unexpected_value(instance.dump_format){'dump format'}
           end
         "#{name.to_s.green}(#{instance.dump_format})#{object.class}=\n#{dump_text}"
       end
 
       # Capture the output of $stderr and log it at debug level
+      # @yieldreturn [void] Code block whose stderr output will be captured
       def capture_stderr
         real_stderr = $stderr
         $stderr = StringIO.new
@@ -192,7 +193,7 @@ module Aspera
         end
         # Use `local2` facility, like other Aspera components
         @logger = Syslog::Logger.new(@program_name, Syslog::LOG_LOCAL2)
-      else error_unexpected_value(new_log_type){"log type (#{LOG_TYPES.join(', ')})"}
+      else Aspera.error_unexpected_value(new_log_type){"log type (#{LOG_TYPES.join(', ')})"}
       end
       @logger.level = current_severity_integer
       @logger_type = new_log_type