openapi-sourcetools 0.12.1 → 0.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44a305843fc718a7b958b3afbaf42f6f215f5a23e23c5485799222b7030a1757
-  data.tar.gz: 68d37c654b903c17d8aa64d96fdcecbca2c3e7c56b2b5629e2e80f243d3993e1
+  metadata.gz: edfaf16a37a66c6f64cddb2580cd5a85c6daf21937a403358ea03d28b35a47d6
+  data.tar.gz: 6e81dcc098183b9547fbc9dd956fb0f11e2ccf556dbf7d8baaf73821bfe9334e
 SHA512:
-  metadata.gz: 274b22fbac33a899c3a2102772d2b3e6bd44aab656b67e74a1e65fbd07edcab86bc7fcde94e41184a51e3435ec7cbc5d826c407bbbbed322ff0e2eeec1168156
-  data.tar.gz: a41c84712831166ef6ab0b2233a9c491ea1d87b73d6f1d67bab2ef821a937d2216e99a471ed9210427cb7b8c9824160c257cc6ef856a971d4804812a9b9a5a5a
+  metadata.gz: 13c4fd8d5a67c9af5072a8d7e29bee3bec6a82e0a7e9a39284e492871cfb7f9dfca736293d2218df5d91efa2fc200ec0c90b0e8887e0991793dec11a714a692f
+  data.tar.gz: 22ff4d3552d478a72d1e7b5c5d413e4de0c912479da1469ebbb3afa3311e23bd3cb769c69ec40547448e63cd4fbde038383cfef1122fb4a3a8de5297d14d1134

data/bin/openapi-addschemas

@@ -16,6 +16,14 @@ def remove_subitem(obj, path)
   parent.delete(path.last) || {}
 end
 
+def replace_child_inlines(obj, components)
+  return true unless obj.is_a?(Hash)
+  obj.keys.sort!.each do |name|
+    return false unless replace_inlines(obj[name], components)
+  end
+  true
+end
+
 def replace_inlines(obj, components, top_level_name = nil)
   if obj.is_a?(Array)
     obj.each do |o|
@@ -29,22 +37,30 @@ def replace_inlines(obj, components, top_level_name = nil)
     return true
   end
   # Is inlined, process parts recursively.
-  %w[allOf anyOf oneOf items prefixItems additionalProperties unevaluatedItems
-    unevaluatedProperties if then else not
-  ].each do |prop_name|
-    return false unless replace_inlines(obj[prop_name], components)
+  looks_like_type = false
+  # Array-valued.
+  OpenAPISourceTools::Schemas::ARRAY_VALUED.each do |prop_name|
+    value = obj[prop_name]
+    next unless value.is_a?(Array)
+    return false unless replace_inlines(value, components)
+    looks_like_type = true
+  end
+  # Other-valued things.
+  OpenAPISourceTools::Schemas::OTHER_VALUED.each do |prop_name|
+    value = obj[prop_name]
+    next if value.nil? || value.is_a?(Array)
+    return false unless replace_inlines(value, components)
+    looks_like_type = true
   end
-  %w[properties patternProperties dependentSchemas].each do |prop_name|
+  # Keys of these have object values that should be processed.
+  OpenAPISourceTools::Schemas::KEY2SCHEMA.each do |prop_name|
     props = obj[prop_name]
-    next if props.nil?
-    props.keys.sort!.each do |name|
-      return false unless replace_inlines(props[name], components)
-    end
+    next if props.nil? || !props.is_a?(Hash)
+    return false unless replace_child_inlines(props, components)
+    looks_like_type = true
   end
-  looks_like_type = false
   # required is omitted since it is in schema and in parameters.
-  %w[type items prefixItems properties patternProperties additionalProperties
-    unevaluatedItems unevaluatedProperties enum const minimum maximum multipleOf
+  %w[type enum const minimum maximum multipleOf
     exclusiveMinimum exclusiveMaximum maxLength minLength pattern maxItems minItems
     uniqueItems maxContains minContains maxProperties minProperties propertyNames
     dependentRequired format contentEncoding contentMediaType contentSchema
@@ -57,7 +73,7 @@ def replace_inlines(obj, components, top_level_name = nil)
   unless looks_like_type
     # Some kind of intermediate-level object.
     obj.keys.sort! { |a, b| a.to_s <=> b.to_s }.each do |key|
-      next if key == 'securitySchemes'
+      next if key == 'securitySchemes' || OpenAPISourceTools::Schemas::IGNORED.include?(key) || OpenAPISourceTools::Schemas::HANDLED.include?(key)
       return false unless replace_inlines(obj[key], components)
     end
     return true

data/bin/openapi-logicsplit

@@ -0,0 +1,96 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Copyright © 2026 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require_relative '../lib/openapi/sourcetools/apiobjects'
+require_relative '../lib/openapi/sourcetools/common'
+require 'optparse'
+include OpenAPISourceTools
+
+
+def mixture?(schema)
+  has_logic = false
+  has_other = false
+  schema.each_key do |key|
+    if OpenAPISourceTools::ApiObjects::LOGIC_KEYS.member?(key)
+      has_logic = true
+      return true if has_other
+    elsif !OpenAPISourceTools::ApiObjects::DOCUMENT_KEYS.include?(key)
+      has_other = true
+      return true if has_logic
+    end
+  end
+  has_logic && has_other
+end
+
+def split(name, schema, added_schemas, schema_path)
+  logic = {}
+  other = {}
+  schema.each do |key, value|
+    if OpenAPISourceTools::ApiObjects::LOGIC_KEYS.member?(key)
+      logic[key] = value
+    else
+      other[key] = value
+    end
+  end
+  logic_name = "#{name}Logic"
+  other_name = "#{name}Other"
+  added_schemas[logic_name] = logic
+  added_schemas[other_name] = other
+  schema.clear
+  schema['allOf'] = [
+    { '$ref' => "#{schema_path}/#{logic_name}" },
+    { '$ref' => "#{schema_path}/#{other_name}" }
+  ]
+end
+
+def main
+  input_name = nil
+  output_name = nil
+  schema_path = '#/components/schemas'
+
+  parser = OptionParser.new do |opts|
+    opts.summary_indent = '  '
+    opts.summary_width = 26
+    opts.banner = 'Usage: openapi-logicsplit [options]'
+    opts.separator ''
+    opts.separator 'Options:'
+    opts.on('-i', '--input FILE', 'Read API spec from FILE, not stdin.') do |f|
+      input_name = f
+    end
+    opts.on('-o', '--output FILE', 'Output to FILE, not stdout.') do |f|
+      output_name = f
+    end
+    opts.on('-h', '--help', 'Print this help and exit.') do
+      $stdout.puts %(#{opts}
+
+Loads API document in OpenAPI format and splits each schema with a mixture of
+logic keywords and other keywords so that the schema has only allOf with
+references to logic and other schema. The aim is to simplify code generation.
+
+The openapi-addschemas must have been run. Processes "#{schema_path}".
+)
+      return 0
+    end
+  end
+  parser.order!
+
+  doc = Common.load_source(input_name)
+  return 2 if doc.nil?
+
+  path = schema_path.split('/').reject { |x| x == '#' || x.empty? }
+  schemas = doc.dig(*path)
+  added_schemas = {}
+  unless schemas.nil?
+    schemas.keys.sort.each do |name|
+      s = schemas[name]
+      split(name, s, added_schemas, schema_path) if mixture?(s)
+    end
+    schemas.merge!(added_schemas)
+  end
+  Common.dump_result(output_name, doc, 3)
+end
+
+exit(main) if File.basename(__FILE__) == File.basename($PROGRAM_NAME)

data/bin/openapi-order

@@ -53,6 +53,7 @@ def default_order_data(order_key, regexp_prefix)
   server: *ServerObject
   parameters:
     #{order_key}: &ParameterObject_order
+    - required: '>' # True before false.
     - name
     - in
     '*': &ParameterObject
@@ -216,7 +217,7 @@ def default_order_data(order_key, regexp_prefix)
       - re:^x-openapi-sourcetools.*$
       '*':
         #{order_key}: &OperationObject
-        - '$ref'
+        - '\$ref'
         - operationId
         - summary
         - description
@@ -349,7 +350,7 @@ end
 
 # This needs to extract all path/order pairs, store and sort.
 
-def extract_orders(path, order, collection, order_key, regexp_prefix)
+def extract_orders(path, order, collection, order_key, regexp_prefix, visited)
   return true unless order.is_a?(Hash)
   order.each do |key, value|
     if key == order_key
@@ -357,9 +358,13 @@ def extract_orders(path, order, collection, order_key, regexp_prefix)
         OpenAPISourceTools::Common.aargh("Not an array: #{path.join('.')}.#{order_key} =\n#{YAML.dump(value)}")
         return false
       end
+      return true if visited.member?(value.object_id)
+      visited.add(value.object_id)
       value.each_with_index do |v, k|
-        next if v.is_a?(String)
-        OpenAPISourceTools::Common.aargh("Not a string: #{path}.#{order_key}[#{k}] =\n#{YAML.dump(v)}")
+        ov = OpenAPISourceTools::Ordering::Order.ordervalue(v)
+        value[k] = ov
+        next unless ov.nil?
+        OpenAPISourceTools::Common.aargh("Not valid order value: #{path}.#{order_key}[#{k}] =\n#{YAML.dump(v)}")
         return false
       end
       key_path = OpenAPISourceTools::Ordering::KeyPath.new(path, regexp_prefix)
@@ -368,7 +373,7 @@ def extract_orders(path, order, collection, order_key, regexp_prefix)
     else
       key = key.to_s unless key.is_a?(String)
       path.push(key)
-      return false unless extract_orders(path, value, collection, order_key, regexp_prefix)
+      return false unless extract_orders(path, value, collection, order_key, regexp_prefix, visited)
       path.pop
     end
   end
@@ -473,14 +478,17 @@ def main
       regexp_prefix = p
     end
     opts.on('-h', '--help', 'Print this help and exit.') do
-      $stdout.puts %(#{opts}
+      $stdout.puts <<EOF
+#{opts}
 Loads YAML document and applies ordering to object keys, and arrays with
 objects, when an order matches the key path to object.
 
 Can be used on generic YAML or JSON files. Default order is for OpenAPI
 documents.
 
-The order instructions key "#{order_key}" value must be an array of strings.
+The order instructions key "#{order_key}" value must be an array of strings
+or single-item map from string to "<" or ">" to indicate ascending (default)
+or descending order. Hence any 'key' is same as 'key: "<"'.
 The values can be any combination of the following:
 - Literal key name.
 - Regular expression starting with "#{regexp_prefix}".
@@ -493,13 +501,13 @@ position are sorted within that position.
 The path to the "#{order_key}" can have any combination of the following:
 - Literal key name.
 - Regular expression starting with "#{regexp_prefix}".
-- "*" that matches one key of any value.
-- "**" that matches one or more keys of any value.
+- "*" that matches one key of any content.
+- "**" that matches one or more keys of any content.
 The path is used to determine if a value in the document should be ordered
 using the instructions. At top level the path is empty and applies to the root
 of the document. Long paths are considered to be more specific than short
 paths, because they supposedly contain more literal keys or limiting regular
-expressions so thay are intended for a specific case. Of paths of same length
+expressions so they are intended for a specific case. Of paths of same length
 one with "**" is considered less specific than one without.
 
 The path to a value in the document is matched against paths to "#{order_key}"
@@ -539,7 +547,7 @@ so provide it if you want to keep it. Useful for readability.
 
 When reading an order file, --key and --regexp are over-ridden by root-level
 object "#{metadata}" keys "#{metadata_key}" and "#{metadata_regexp}" values.
-)
+EOF
       exit 0
     end
   end
@@ -562,7 +570,7 @@ object "#{metadata}" keys "#{metadata_key}" and "#{metadata_regexp}" values.
     order_key = md.fetch(metadata_key, order_key)
     regexp_prefix = md.fetch(metadata_regexp, regexp_prefix)
     path_orders = []
-    return 4 unless extract_orders([], order, path_orders, order_key, regexp_prefix)
+    return 4 unless extract_orders([], order, path_orders, order_key, regexp_prefix, Set.new)
     path_orders.sort!.reverse! # Longest key pattern sequence first.
     order_document(path_orders, [], doc)
     doc = formats[format].call(doc, line_width)

data/bin/openapi-schema-in

@@ -0,0 +1,143 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Copyright © 2026 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require_relative '../lib/openapi/sourcetools/common'
+require_relative '../lib/openapi/sourcetools/schemaio'
+require 'optparse'
+include OpenAPISourceTools
+
+
+# Functions related to saving the output.
+
+def to_json(doc, _line_width)
+  JSON.dump(doc)
+end
+
+def to_pretty_json(doc, _line_width)
+  JSON.pretty_generate(doc)
+end
+
+def to_yaml(doc, line_width)
+  YAML.dump(doc, line_width: line_width)
+end
+
+def main
+  input_file = nil
+  schema_file = nil
+  output_file = nil
+  name = nil
+  refs = true
+  format = 'yaml'
+  formats = {
+    'yaml' => method(:to_yaml),
+    'json' => method(:to_json),
+    'pretty_json' => method(:to_pretty_json)
+  }
+  line_width = 80
+  doc_paths = :openapi
+  schema_paths = :jsonschema
+  drops = []
+
+  parser = OptionParser.new do |opts|
+    opts.summary_indent = '  '
+    opts.summary_width = 26
+    opts.banner = 'Usage: openapi-schema-in [options]'
+    opts.separator ''
+    opts.separator 'Options:'
+    opts.on('-i', '--input FILE', 'Read input from FILE, not stdin.') do |f|
+      input_file = f
+    end
+    opts.on('-s', '--schema FILE', 'Read schema from FILE, not stdin.') do |f|
+      schema_file = f
+    end
+    opts.on('-o', '--output FILE', 'Write result to FILE, not stdout.') do |f|
+      output_file = f
+    end
+    opts.on('-n', '--name NAME', 'Use schema NAME.') do |n|
+      name = n
+    end
+    opts.on('--[no-]refs', "Include referred schemas (default #{Common.yesno(refs)}).") do |r|
+      refs = r
+    end
+    opts.on('-f', '--format FORMAT', "Document output format: #{formats.keys.sort!.join(', ')}.") do |fmt|
+      format = fmt
+    end
+    opts.on('-w', '--width WIDTH', "Set YAML line width, default: #{line_width}") do |w|
+      line_width = w.to_i
+    end
+    opts.on('--inputpaths DATA', 'Input path data.') do |data|
+      doc_paths = data
+    end
+    opts.on('--schemapaths DATA', 'Schema path data.') do |data|
+      schema_paths = data
+    end
+    opts.on('-d', '--drop KEY', 'Drop KEY from chosen schema.') do |k|
+      drops.push(k)
+    end
+    opts.on('-h', '--help', 'Print this help and exit.') do
+      $stdout.puts <<EOF
+#{opts}
+Takes schema with name and places it into document.
+
+The document and schema paths DATA is either a file name, internal data name,
+or a JSON-encoded object containing paths data. Internal data names are:
+#{SchemaIO::BUILTINS.keys.sort!.join(', ')}
+
+Depending on input, schema NAME is used to find and store the schema in the
+location indicated by DATA for input and output.
+
+DATA values default to input and output being OpenAPI format, schema file is
+JSON schema with the named schema at root.
+
+Dropping keys can be used to remove for example "$schema" and "$id" keys from
+the chosen schema, if present.
+EOF
+      return 0
+    end
+  end
+  parser.order!
+
+  drops.sort!.uniq! unless drops.size < 2
+
+  return Common.aargh('Cannot read both document and schema from stdin.', 1) if input_file.nil? && schema_file.nil?
+  return Common.aargh('Schema name must be given.', 1) if name.nil?
+
+  return Common.aargh("Unknown format: #{format}", 1) unless formats.key?(format)
+
+  dp = SchemaIO.key_data(doc_paths)
+  return Common.aargh("Not file or internal format name or format as JSON object: #{doc_paths}", 2) if dp.nil?
+  sp = SchemaIO.key_data(schema_paths)
+  return Common.aargh("Not file or internal format name or format as JSON object: #{schema_paths}", 2) if sp.nil?
+
+  return Common.aargh(%(Name "#{name}" has document path separator "#{dp.separator}"), 1) if name.include?(dp.separator)
+  return Common.aargh(%(Name "#{name}" has schema path separator "#{sp.separator}"), 1) if name.include?(sp.separator)
+
+  doc = Common.load_source(input_file)
+  return 2 if doc.nil?
+  return Common.aargh('Document is not an object.', 2) unless doc.is_a?(Hash)
+  schema = Common.load_source(schema_file)
+  return 2 if schema.nil?
+  return Common.aargh('Schema is not an object.', 2) unless schema.is_a?(Hash)
+
+  tgt = SchemaIO::SchemaAccess.new(dp, doc)
+  src = SchemaIO::SchemaAccess.new(sp, schema)
+
+  desired = src.find_named_schema(name)
+  return Common.aargh("Schema not found: #{name}", 1) if desired.nil?
+  drops.each { |k| desired.delete(k) }
+  tgt.put_named_schema(name, desired)
+
+  if refs
+    refd = src.find_referenced_schemas(name, desired)
+    refd.each { |n, s| tgt.put_referenced_schema(n, s) }
+  end
+  SchemaIO.alter_refs(tgt.document, src, tgt) # After referenced schemas have been found.
+
+  out = formats[format].call(tgt.document, line_width)
+  Common.dump_result(output_file, out, 3)
+end
+
+exit(main) if File.basename(__FILE__) == File.basename($PROGRAM_NAME)

data/bin/openapi-schema-ls

@@ -0,0 +1,100 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Copyright © 2026 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require_relative '../lib/openapi/sourcetools/common'
+require_relative '../lib/openapi/sourcetools/schemaio'
+require 'optparse'
+require 'yaml'
+require 'json'
+include OpenAPISourceTools
+
+
+# Functions related to saving the document path dump.
+
+def to_json(doc)
+  JSON.dump(doc)
+end
+
+def to_pretty_json(doc)
+  JSON.pretty_generate(doc)
+end
+
+def to_yaml(doc)
+  YAML.dump(doc)
+end
+
+def main
+  input_file = nil
+  output_file = nil
+  doc_paths = :openapi
+  output_default = nil
+  format = 'pretty_json'
+  formats = {
+    'yaml' => method(:to_yaml),
+    'json' => method(:to_json),
+    'pretty_json' => method(:to_pretty_json)
+  }
+
+  parser = OptionParser.new do |opts|
+    opts.summary_indent = '  '
+    opts.summary_width = 22
+    opts.banner = 'Usage: openapi-schema-ls [options]'
+    opts.separator ''
+    opts.separator 'Options:'
+    opts.on('-i', '--input FILE', 'Read input from FILE, not stdin.') do |f|
+      input_file = f
+    end
+    opts.on('-o', '--output FILE', 'Write result to FILE, not stdout.') do |f|
+      output_file = f
+    end
+    opts.on('--inputpaths DATA', 'Input path data.') do |data|
+      doc_paths = data
+    end
+    opts.on('--dump DATA', 'Dump internal path data to output and exit.') do |data|
+      output_default = data
+    end
+    opts.on('-f', '--format FORMAT', "DATA output format: #{formats.keys.sort!.join(', ')}.") do |fmt|
+      format = fmt
+    end
+    opts.on('-h', '--help', 'Print this help and exit.') do
+      $stdout.puts <<EOF
+#{opts}
+Lists named schemas in the input document.
+
+The document paths DATA is either a file name, internal data name, or a
+JSON-encoded object with necessary keys. Same data also applies to both
+openapi-schema-in and openapi-schema-out. Internal data names are:
+#{SchemaIO::BUILTINS.keys.sort!.join(', ')}
+
+DATA defaults to OpenAPI format.
+EOF
+      return 0
+    end
+  end
+  parser.order!
+
+  return Common.aargh("Unknown format: #{format}", 1) unless formats.key?(format)
+
+  unless output_default.nil?
+    doc = SchemaIO.get(output_default)
+    return Commpon.aargh("Not internal data format: #{output_default}", 1) if doc.nil?
+    out = (format == 'yaml') ? doc : formats[format].call(YAML.safe_load(doc))
+    return Common.dump_result(output_file, out, 3)
+  end
+
+  dp = SchemaIO.key_data(doc_paths)
+  return Common.aargh("Not file or internal format name or format as JSON object: #{doc_paths}", 2) if dp.nil?
+
+  doc = Common.load_source(input_file)
+  return 2 if doc.nil?
+
+  src = SchemaIO::SchemaAccess.new(dp, doc)
+  out = src.list_schema_names.join("\n")
+
+  Common.dump_result(output_file, out, 3)
+end
+
+exit(main) if File.basename(__FILE__) == File.basename($PROGRAM_NAME)

data/bin/openapi-schema-out

@@ -0,0 +1,144 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Copyright © 2026 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require_relative '../lib/openapi/sourcetools/common'
+require_relative '../lib/openapi/sourcetools/schemaio'
+require 'optparse'
+require 'yaml'
+require 'json'
+include OpenAPISourceTools
+
+
+# Functions related to saving the output.
+
+def to_json(doc, _line_width)
+  JSON.dump(doc)
+end
+
+def to_pretty_json(doc, _line_width)
+  JSON.pretty_generate(doc)
+end
+
+def to_yaml(doc, line_width)
+  YAML.dump(doc, line_width: line_width)
+end
+
+def main
+  input_file = nil
+  output_file = nil
+  name = nil
+  refs = true
+  format = 'pretty_json'
+  formats = {
+    'yaml' => method(:to_yaml),
+    'json' => method(:to_json),
+    'pretty_json' => method(:to_pretty_json)
+  }
+  line_width = 80
+  doc_paths = :openapi
+  schema_paths = :jsonschema
+  additions = {}
+
+  parser = OptionParser.new do |opts|
+    opts.summary_indent = '  '
+    opts.summary_width = 27
+    opts.banner = 'Usage: openapi-schema-out [options]'
+    opts.separator ''
+    opts.separator 'Options:'
+    opts.on('-i', '--input FILE', 'Read input from FILE, not stdin.') do |f|
+      input_file = f
+    end
+    opts.on('-o', '--output FILE', 'Write result to FILE, not stdout.') do |f|
+      output_file = f
+    end
+    opts.on('-n', '--name NAME', 'Use schema NAME.') do |n|
+      name = n
+    end
+    opts.on('--[no-]refs', "Include referred schemas (default #{Common.yesno(refs)}).") do |r|
+      refs = r
+    end
+    opts.on('-f', '--format FORMAT', "Schema output format: #{formats.keys.sort!.join(', ')}.") do |fmt|
+      format = fmt
+    end
+    opts.on('-w', '--width WIDTH', "Set YAML line width, default: #{line_width}") do |w|
+      line_width = w.to_i
+    end
+    opts.on('--inputpaths DATA', 'Input path data.') do |data|
+      doc_paths = data
+    end
+    opts.on('--schemapaths DATA', 'Schema path data.') do |data|
+      schema_paths = data
+    end
+    opts.on('-a', '--add KEY:[json:]VALUE', 'Add KEY with (JSON) VALUE to output schema.') do |kv|
+      k, v = kv.split(':', 2)
+      return Common.aargh("Invalid key-value pair: #{kv}", 1) if k.nil? || v.nil?
+      return Common.aargh("Empty key: #{kv}", 1) if k.empty?
+      v = JSON.parse(v[5..]) if v.downcase.start_with?('json:')
+      additions[k] = v
+    rescue JSON::ParserError
+      return Common.aargh("Invalid JSON in argument value: #{kv}", 1)
+    end
+    opts.on('-h', '--help', 'Print this help and exit.') do
+      $stdout.puts <<EOF
+#{opts}
+Takes schema with name from input and places it into output.
+
+The document and schema paths DATA is either a file name, internal data name,
+or a JSON-encoded object with necessary keys. Internal data names are:
+#{SchemaIO::BUILTINS.keys.sort!.join(', ')}
+
+Depending on input, schema NAME is used to find and store the schema in the
+location indicated by DATA for output.
+
+DATA values default to input being OpenAPI format and output is JSON schema
+with schema at root and referenced schemas, if output, under "$defs" key.
+
+Adding KEY:VALUE pairs can be used to add keys to the output schema with
+string values. Using KEY:json:VALUE will parse VALUE as JSON and use that.
+The format indicator is case-insensitive. Value can be empty but key cannot
+be empty. Pass value starting with "json:" as 'key:json:"json:the_rest"'.
+Usable for adding "$schema" and "$id" keys to the output schema.
+EOF
+      return 0
+    end
+  end
+  parser.order!
+
+  return Common.aargh('Schema name must be given.', 1) if name.nil?
+
+  return Common.aargh("Unknown format: #{format}", 1) unless formats.key?(format)
+
+  dp = SchemaIO.key_data(doc_paths)
+  return Common.aargh("Not file or internal format name or format as JSON object: #{doc_paths}", 2) if dp.nil?
+  sp = SchemaIO.key_data(schema_paths)
+  return Common.aargh("Not file or internal format name or format as JSON object: #{schema_paths}", 2) if sp.nil?
+
+  return Common.aargh(%(Name "#{name}" has document path separator "#{dp.separator}"), 1) if name.include?(dp.separator)
+  return Common.aargh(%(Name "#{name}" has schema path separator "#{sp.separator}"), 1) if name.include?(sp.separator)
+
+  doc = Common.load_source(input_file)
+  return 2 if doc.nil?
+  return Common.aargh('Document is not an object.', 2) unless doc.is_a?(Hash)
+
+  src = SchemaIO::SchemaAccess.new(dp, doc)
+  tgt = SchemaIO::SchemaAccess.new(sp, {})
+
+  desired = src.find_named_schema(name)
+  return Common.aargh("Schema not found: #{name}", 1) if desired.nil?
+  desired.merge!(additions) unless additions.empty?
+  tgt.put_named_schema(name, desired)
+
+  if refs
+    refd = src.find_referenced_schemas(name, desired)
+    refd.each { |n, s| tgt.put_referenced_schema(n, s) }
+  end
+  SchemaIO.alter_refs(tgt.document, src, tgt) # After referenced schemas have been found.
+
+  out = formats[format].call(tgt.document, line_width)
+  Common.dump_result(output_file, out, 3)
+end
+
+exit(main) if File.basename(__FILE__) == File.basename($PROGRAM_NAME)

data/lib/openapi/sourcetools/apiobjects.rb

@@ -1,12 +1,23 @@
 # frozen_string_literal: true
 
-# Copyright © 2024-2025 Ismo Kärkkäinen
+# Copyright © 2024-2026 Ismo Kärkkäinen
 # Licensed under Universal Permissive License. See LICENSE.txt.
 
 module OpenAPISourceTools
+  # Various schema-related constants.
+  module Schemas
+    ARRAY_VALUED = %w[allOf anyOf oneOf prefixItems].freeze
+    OTHER_VALUED = %w[items additionalProperties unevaluatedItems unevaluatedProperties if then else not].freeze
+    KEY2SCHEMA = %w[properties patternProperties dependentSchemas].freeze
+    HANDLED = [].concat(ARRAY_VALUED, OTHER_VALUED, KEY2SCHEMA).freeze
+    IGNORED = %w[example examples].freeze
+  end
+
   # Various classes for handling objects in the API specification.
   # Used in various programs.
   module ApiObjects
+    LOGIC_KEYS = Set.new(%w[allOf anyOf oneOf not if then else dependentSchemas]).freeze
+    DOCUMENT_KEYS = %w[example examples title summary description deprecated readOnly writeOnly].freeze
 
     def self.same(a, b, ignored_keys = Set.new(%w[summary description]))
       return a == b unless a.is_a?(Hash) && b.is_a?(Hash)
@@ -89,7 +100,7 @@ module OpenAPISourceTools
               next if value.key?('$ref')
               @components.to_reference_object(value)
             end
-          else
+          elsif !Schemas::IGNORED.include?(key)
             replace(value)
           end
         end
@@ -114,6 +125,7 @@ module OpenAPISourceTools
         obj.each do |key, value|
           if key == @key && value.is_a?(Hash)
             value.keys.sort!.each do |sub_key|
+              next if Schemas::IGNORED.include?(sub_key)
               sub_value = value[sub_key]
               next unless sub_value.is_a?(Hash)
               next if sub_value.key?('$ref')
@@ -173,7 +185,7 @@ module OpenAPISourceTools
         @items.each do |k, v|
           return ref_string(k) if ApiObjects.same(obj, v, @ignored_keys)
         end
-        # One of the numbers will not match existing keys. More number than keys.
+        # One of the numbers will not match existing keys. More numbers than keys.
         (@items.size + 1).times do |n|
           # 'x' is to simplify find and replace (Schema1x vs Schema1 and Schema10)
           cand = "#{@prefix}#{n}x"

data/lib/openapi/sourcetools/order.rb

@@ -10,7 +10,7 @@ module OpenAPISourceTools
     # Used as replacement for '*'.
     ANY = Regexp.new('^.*$')
 
-    def self.array_item_compare(a, b)
+    def self.array_item_compare(a, b, patterns)
       a[:values].size.times do |k|
         av = a[:values][k]
         bv = b[:values][k]
@@ -18,8 +18,14 @@ module OpenAPISourceTools
           return 1 unless bv.nil?
         else
           return -1 if bv.nil?
-          r = av <=> bv
-          return r unless r.nil? || r.zero?
+          if (av.is_a?(TrueClass) || av.is_a?(FalseClass)) && (bv.is_a?(TrueClass) || bv.is_a?(FalseClass))
+            r = (av ? 1 : 0) <=> (bv ? 1 : 0)
+          else
+            r = av <=> bv
+          end
+          next if r.nil? || r.zero?
+          r = -r unless patterns[k].ascending
+          return r
         end
       end
       0
@@ -129,18 +135,23 @@ module OpenAPISourceTools
         # Hence items.size, and the more multiple, the earlier.
         d = @items.size <=> other.items.size
         return d unless d.zero?
-        -@items.count(:multi) <=> -other.items.count(:multi)
+        d = -@items.count(:multi) <=> -other.items.count(:multi)
+        return d unless d.zero?
+        # Questionable if I should compare to the object_id or equality.
+        # Now if you use same regular expression, they are the same.
+        -@items.count(ANY) <=> -other.items.count(ANY)
       end
     end
 
     # Book-keeping class for pattern and its location.
     class KeyPattern
-      attr_reader :pattern, :index, :priority
+      attr_reader :pattern, :index, :priority, :ascending
 
-      def initialize(pattern, index, priority)
+      def initialize(pattern, index, priority, sort_operator)
         @pattern = pattern
         @index = index
         @priority = priority
+        @ascending = sort_operator == '<'
       end
 
       def match?(string)
@@ -160,22 +171,34 @@ module OpenAPISourceTools
         false
       end
 
+      def self.ordervalue(item)
+        return [ item, '<' ] if item.is_a?(String)
+        return nil unless item.is_a?(Hash)
+        return nil unless item.size == 1
+        key = item.keys.first
+        return nil unless key.is_a?(String)
+        return nil unless ['<', '>'].include?(item[key])
+        [ key, item[key] ]
+      end
+
       attr_reader :patterns
 
       def initialize(keys, regexp_prefix)
         @patterns = []
         has_asterisk = false
-        keys.each_with_index do |string, idx|
+        keys.each_with_index do |ov, idx|
+          string = ov.first
+          sort_operator = ov.last
           if string.start_with?(regexp_prefix)
-            @patterns.push(KeyPattern.new(Regexp.new(string[regexp_prefix.size..]), idx, idx))
+            @patterns.push(KeyPattern.new(Regexp.new(string[regexp_prefix.size..]), idx, idx, sort_operator))
           elsif string == '*'
-            @patterns.push(KeyPattern.new(Regexp.new('^.*$'), idx, keys.size)) unless has_asterisk # First used.
+            @patterns.push(KeyPattern.new(Regexp.new('^.*$'), idx, keys.size, sort_operator)) unless has_asterisk # First used.
             has_asterisk = true
           else
-            @patterns.push(KeyPattern.new(Regexp.new("^#{Regexp.escape(string)}$"), idx, idx))
+            @patterns.push(KeyPattern.new(Regexp.new("^#{Regexp.escape(string)}$"), idx, idx, sort_operator))
           end
         end
-        @patterns.push(KeyPattern.new(Regexp.new('^.*$'), @patterns.size, keys.size + 1)) unless has_asterisk
+        @patterns.push(KeyPattern.new(Regexp.new('^.*$'), @patterns.size, keys.size + 1, '<')) unless has_asterisk
       end
 
       def apply_array(array)
@@ -207,13 +230,13 @@ module OpenAPISourceTools
           end
           values.push(amended)
         end
-        values.sort! { |a, b| OpenAPISourceTools::Ordering.array_item_compare(a, b) }
+        values.sort! { |a, b| OpenAPISourceTools::Ordering.array_item_compare(a, b, @patterns) }
         values.each_with_index { |amended, i| array[i] = amended[:item] }
         true
       end
 
-      def apply_hash(hash)
-        return true if hash.size < 2
+      def apply_hash(unordered_hash)
+        return true if unordered_hash.size < 2
         groups = @patterns.map do |kp|
           {
             kp: kp,
@@ -221,7 +244,7 @@ module OpenAPISourceTools
           }
         end
         s2orig = {}
-        hash.each_key do |key|
+        unordered_hash.each_key do |key|
           skey = key.is_a?(String) ? key : key.to_s
           s2orig[skey] = key
           best_priority = groups.size + 1
@@ -238,10 +261,11 @@ module OpenAPISourceTools
         ordered = {}
         groups.each do |group|
           group[:keys].sort!
-          group[:keys].each { |k| ordered[s2orig[k]] = hash[s2orig[k]] }
+          group[:keys].reverse! unless group[:kp].ascending
+          group[:keys].each { |k| ordered[s2orig[k]] = unordered_hash[s2orig[k]] }
         end
-        hash.clear
-        hash.merge!(ordered)
+        unordered_hash.clear
+        unordered_hash.merge!(ordered)
         true
       end
 

data/lib/openapi/sourcetools/schemaio.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+# Copyright © 2026 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require_relative 'common'
+require 'yaml'
+require 'json'
+
+
+# Gem namespace.
+module OpenAPISourceTools
+  # Methods and classes to get schemas in and out of documents.
+  module SchemaIO
+    OPENAPI_PATHS = <<EOF
+---
+separator: "/" # For splitting paths.
+ignore: "#" # What to ignore in split paths.
+named: "#/components/schemas" # Before named schema.
+reference: "$ref" # Reference key name.
+referenced: "#/components/schemas" # Reference path before schema name.
+EOF
+
+    JSON_SCHEMA_PATHS = <<EOF
+---
+separator: "/"
+ignore: "#"
+named: ~
+reference: "$ref"
+referenced: "#/$defs"
+EOF
+
+    JSON_SCHEMA_DEFS_PATHS = <<EOF
+---
+separator: "/"
+ignore: "#"
+named: "#/$defs"
+reference: "$ref"
+referenced: "#/$defs"
+EOF
+
+    BUILTINS = {
+      openapi: OPENAPI_PATHS,
+      jsonschema: JSON_SCHEMA_PATHS,
+      jsonschemadefs: JSON_SCHEMA_DEFS_PATHS
+    }.freeze
+
+    def self.get(name)
+      BUILTINS[name.is_a?(String) ? name.downcase.to_sym : name]
+    end
+
+    # Checks format and does some convenience preparations.
+    class SchemaFormat
+      attr_reader :separator, :named, :reference, :referenced
+
+      def initialize(format)
+        f = format.is_a?(Hash) ? format : YAML.safe_load(format)
+        raise ArgumentError, 'Format is not an object.' unless f.is_a?(Hash)
+        errors = []
+        @separator = f['separator']
+        errors.push('separator must be a non-empty string.') unless @separator.is_a?(String) && !@separator.empty?
+        @ignore = f['ignore']
+        errors.push('ignore must be a string or an array of strings.') unless @ignore.is_a?(String) || @ignore.is_a?(Array)
+        if @ignore.is_a?(Array)
+          errors.push('ignore array values must be non-empty strings') unless @ignore.index { |v| !v.is_a?(String) || v.empty? }.nil?
+        else
+          @ignore = [ @ignore ]
+        end
+        @ignore.push('')
+        @named = f['named']
+        @reference = f['reference']
+        errors.push('Reference key must be non-empty string.') if @reference.nil?
+        @referenced = f['referenced']
+        raise ArgumentError, errors.join("\n") unless errors.empty?
+        @named = '' if @named.nil?
+        @named += @separator unless @named.empty? || @named.end_with?(@separator)
+        @referenced += @separator unless @referenced.nil? || @referenced.empty? || @referenced.end_with?(@separator)
+      end
+
+      def ignore?(str)
+        @ignore.include?(str)
+      end
+
+      def path(str)
+        str.split(@separator).reject { |p| ignore?(p) }
+      end
+
+      def reference?(key, value)
+        # Accurate enough for now.
+        @reference == key && value.is_a?(String) && value.start_with?(@referenced)
+      end
+
+      def reference_name(ref)
+        ref[@referenced.size..]
+      end
+
+      def make_reference(name)
+        "#{@referenced}#{name}"
+      end
+
+      def root_schema?
+        @named.empty?
+      end
+    end
+
+    def self.load_data(data)
+      # File name?
+      if data.is_a?(String)
+        begin
+          return YAML.safe_load_file(data)
+        rescue StandardError
+          # Was not a file, it is ok.
+        end
+      end
+      # Internal key?
+      d = get(data)
+      return YAML.safe_load(d) unless d.nil?
+      # Try to parse as JSON.
+      if data.is_a?(String)
+        begin
+          return JSON.parse(data)
+        rescue JSON::ParserError
+          # Was not.
+        end
+      end
+      nil
+    end
+
+    def self.key_data(data)
+      d = load_data(data)
+      d.nil? ? nil : SchemaFormat.new(d)
+    rescue ArgumentError => e
+      Common.aargh(e.to_s)
+      nil
+    end
+
+    # Changes references from source format to target format.
+    def self.alter_refs(schema, source_access, target_access)
+      if schema.is_a?(Array)
+        schema.each do |v|
+          alter_refs(v, source_access, target_access)
+        end
+      end
+      return unless schema.is_a?(Hash)
+      schema.keys.each do |key|
+        value = schema[key]
+        if source_access.format.reference?(key, value)
+          # Change the prefix in the reference, unless equal.
+          unless target_access.format.referenced == source_access.format.referenced
+            value = target_access.format.make_reference(source_access.format.reference_name(value))
+          end
+          # Change reference key name if needed.
+          if source_access.format.reference == target_access.format.reference
+            schema[key] = value
+          else
+            schema.delete(key)
+            schema[target_access.format.reference] = value
+          end
+        elsif value.is_a?(Hash) || value.is_a?(Array)
+          alter_refs(value, source_access, target_access)
+        end
+      end
+    end
+
+    # Handles document with schemas in stated places. Reads or modifies.
+    class SchemaAccess
+      attr_reader :document, :format
+
+      def initialize(format, document)
+        @document = document
+        @format = format
+      end
+
+      # Used when reading from given document.
+
+      def list_schema_names
+        schemas = @document.dig(*@format.path(@format.referenced))
+        schemas.keys.sort!
+      end
+
+      def find_named_schema(name)
+        if @format.root_schema?
+          # Make a copy and remove the root key to referenced definitions.
+          out = {}.merge!(@document)
+          first = @format.path(@format.referenced).first
+          out.delete(first) unless first.nil?
+          out
+        else
+          find_by_reference(@format.make_reference(name))
+        end
+      end
+
+      def find_referenced_schemas(name, schema)
+        name2schema = {}
+        return name2schema if schema.nil?
+        existing = Set.new # Stops loops.
+        existing.add(name) unless @format.root_schema?
+        todo = [ schema ]
+        until todo.empty?
+          s = todo.pop
+          refs = Set.new
+          gather_refs(s, refs, existing)
+          # Add all new references to the todo list, if present in the file.
+          refs.each do |r|
+            existing.add(r)
+            idx = r.rindex(@format.separator)
+            next if idx.nil?
+            refd = find_by_reference(r)
+            next if refd.nil?
+            todo.push(refd)
+            name2schema[r[(idx + 1)..]] = todo.last
+          end
+        end
+        name2schema
+      end
+
+      # Used when writing to given document.
+
+      def put_named_schema(name, schema)
+        if @format.root_schema?
+          # If clear was to be done we'd need to retain "$defs" or such.
+          # In intended use, JSON schema document is empty when writing to root.
+          @document.merge!(schema)
+        else
+          path = make_path(@format.named, name)
+          OpenAPISourceTools::Common.bury(@document, path, schema)
+        end
+      end
+
+      # Call only after put_named_schema.
+      def put_referenced_schema(name, schema)
+        path = make_path(@format.referenced, name)
+        OpenAPISourceTools::Common.bury(@document, path, schema)
+      end
+
+      private
+
+      def make_path(start, name)
+        @format.path(start).push(name)
+      end
+
+      def find_by_reference(ref)
+        # Implicitly expects that references always have same start followed by name.
+        @document.dig(*@format.path(ref))
+      end
+
+      def gather_refs(schema, found, existing)
+        if schema.is_a?(Array)
+          schema.each do |v|
+            gather_refs(v, found, existing)
+          end
+        end
+        return unless schema.is_a?(Hash)
+        schema.each do |key, value|
+          if @format.reference?(key, value)
+            found.add(value) unless existing.member?(value)
+          elsif value.is_a?(Hash) || value.is_a?(Array)
+            gather_refs(value, found, existing)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openapi/sourcetools/version.rb

@@ -6,7 +6,7 @@
 # Gem namespace.
 module OpenAPISourceTools
   NAME = 'openapi-sourcetools'
-  VERSION = '0.12.1'
+  VERSION = '0.13'
 
   def self.info(separator = ': ')
     "#{NAME}#{separator}#{VERSION}"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openapi-sourcetools
 version: !ruby/object:Gem::Version
-  version: 0.12.1
+  version: '0.13'
 platform: ruby
 authors:
 - Ismo Kärkkäinen
@@ -48,11 +48,15 @@ executables:
 - openapi-frequencies
 - openapi-generate
 - openapi-generate-checkconfig
+- openapi-logicsplit
 - openapi-merge
 - openapi-modifypaths
 - openapi-order
 - openapi-patterntests
 - openapi-processpaths
+- openapi-schema-in
+- openapi-schema-ls
+- openapi-schema-out
 extensions: []
 extra_rdoc_files: []
 files:
@@ -69,11 +73,15 @@ files:
 - bin/openapi-frequencies
 - bin/openapi-generate
 - bin/openapi-generate-checkconfig
+- bin/openapi-logicsplit
 - bin/openapi-merge
 - bin/openapi-modifypaths
 - bin/openapi-order
 - bin/openapi-patterntests
 - bin/openapi-processpaths
+- bin/openapi-schema-in
+- bin/openapi-schema-ls
+- bin/openapi-schema-out
 - lib/openapi/sourcetools.rb
 - lib/openapi/sourcetools/apiobjects.rb
 - lib/openapi/sourcetools/common.rb
@@ -85,6 +93,7 @@ files:
 - lib/openapi/sourcetools/loaders.rb
 - lib/openapi/sourcetools/order.rb
 - lib/openapi/sourcetools/output.rb
+- lib/openapi/sourcetools/schemaio.rb
 - lib/openapi/sourcetools/task.rb
 - lib/openapi/sourcetools/version.rb
 homepage: https://xn--ismo-krkkinen-gfbd.fi/openapi-sourcetools/index.html