json-schema_dsl 1.0.0

data/lib/json/schema_dsl/configuration.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module JSON
+  module SchemaDsl
+    class Configuration
+    end
+  end
+end

data/lib/json/schema_dsl/entity.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module JSON
+  module SchemaDsl
+    # The basic entity type for json schemas.
+    #
+    # This is mostly used in cases where you don't exactly know what type a property will have,
+    # for example if the property is an `anyOf` of different types.
+    #
+    # Internally it is used as the superclass of all other types.
+    class Entity < Dry::Struct
+      include AstNode
+
+      class << self
+        # nodoc
+        def required_type
+          (Types::Bool | Types::Coercible::Array.of(Types::Coercible::String).default { [] })
+        end
+      end
+
+      attribute(:enum,     Types::Coercible::Array.default { [] })
+      attribute(:all_of,   Types::Coercible::Array.default { [] })
+      attribute(:any_of,   Types::Coercible::Array.default { [] })
+      attribute(:one_of,   Types::Coercible::Array.default { [] })
+      attribute(:children, Types::Coercible::Array.default { [] })
+      attribute?(:nullable,    Types::Bool.default(false))
+      attribute?(:name,        (Types.Instance(Regexp) | Types::Coercible::String))
+      attribute?(:type,        Types::Coercible::String)
+      attribute?(:title,       Types::Coercible::String)
+      attribute?(:description, Types::Coercible::String)
+      attribute?(:default,     Types::Coercible::String)
+      attribute?(:required,    required_type)
+      attribute?(:not_a,       Types::String)
+      attribute?(:ref,         Types::String)
+      attribute?(:definitions, Types::String)
+
+      # @return [Hash<Symbol, Object>] Returns this entity as a hash and all children and
+      #   properties as simple values. This structure is used to render the eventual
+      #   schema by the renderer.
+      # @see JSON::SchemaDsl::Rederer#initialize
+      def to_h
+        super.transform_values do |v|
+          is_array = v.is_a?(::Array)
+          if (is_array ? v.first : v).respond_to?(:to_h)
+            is_array ? v.map(&:to_h) : v.to_h
+          else
+            v
+          end
+        end
+      end
+      delegate :as_json, to: :to_h
+    end
+  end
+end

data/lib/json/schema_dsl/integer.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module JSON
+  module SchemaDsl
+    # The primitive integer type for json schema.
+    #
+    # @see https://json-schema.org/understanding-json-schema/reference/numeric.html
+    class Integer < Entity
+      attribute?(:multiple_of,       Types::Integer)
+      attribute?(:minimum,           Types::Integer)
+      attribute?(:maximum,           Types::Integer)
+      attribute?(:exclusive_minimum, Types::Integer)
+      attribute?(:exclusive_maximum, Types::Integer)
+    end
+  end
+end

data/lib/json/schema_dsl/null.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module JSON
+  module SchemaDsl
+    # Null primitive of JSON-Schema
+    #
+    # @see https://json-schema.org/understanding-json-schema/reference/null.html
+    class Null < Entity
+    end
+  end
+end

data/lib/json/schema_dsl/numeric.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module JSON
+  module SchemaDsl
+    # Number primitive of Json-Schema
+    #
+    # @see https://json-schema.org/understanding-json-schema/reference/numeric.html#number
+    class Numeric < Entity
+      attribute?(:multiple_of,       Types::Integer)
+      attribute?(:minimum,           Types::Integer)
+      attribute?(:maximum,           Types::Integer)
+      attribute?(:exclusive_minimum, Types::Integer)
+      attribute?(:exclusive_maximum, Types::Integer)
+    end
+
+    # Type alias of numeric.
+    #
+    # @see https://json-schema.org/understanding-json-schema/reference/numeric.html#number
+    class Number < Numeric
+    end
+  end
+end

data/lib/json/schema_dsl/object.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module JSON
+  module SchemaDsl
+    # Object type of JSON-Schema
+    #
+    # @see https://json-schema.org/understanding-json-schema/reference/object.html
+    class Object < Entity
+      attribute(:pattern_properties, Types::Array.of(Types.Instance(Regexp)).default { [] })
+      attribute?(:min_properties, Types::Integer)
+      attribute?(:max_properties, Types::Integer)
+      attribute?(:additional_properties, Types::Bool)
+    end
+  end
+end

data/lib/json/schema_dsl/proxy.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module JSON
+  module SchemaDsl
+    # A small proxy for the dsl that enables a nicer api for building schemas on the fly
+    class Proxy
+      include ::JSON::SchemaDsl
+    end
+  end
+end

data/lib/json/schema_dsl/renderer.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+%w[base desugar multiplexer alias filter].each do |file|
+  require "json/schema_dsl/renderers/#{file}"
+end
+
+module JSON
+  module SchemaDsl
+    # Main entry point for the rendering chain of JSON::SchemaDsl.
+    #
+    # This will in turn apply the registered renderers one by one, updating the
+    # entity-tree to result in json-schema.
+    class Renderer
+      attr_reader :entity, :scope
+
+      # @param [Entity] entity The root entity-tree of this render run.
+      # @param [Object] scope Used as a fallback for renderers that need access
+      #   to helper methods.
+      def initialize(entity, scope = nil)
+        @entity = entity.to_h
+        @scope = scope
+      end
+
+      # @see #render
+      def self.render(entity)
+        new(entity).render
+      end
+
+      # Applies the renderer chain in turn to produce valid json-schema.
+      # Each renderer traverses the whole tree before passing the resulting structure to
+      # the next renderer
+      # @return [Hash] The resulting json schema structure after each render is applied.
+      def render
+        render_chain.inject(entity) do |structure, renderer|
+          renderer.new(scope).visit(structure)
+        end
+      end
+
+      private
+
+      # @return [Array<Class>] Each rendering class that will be applied to the given entity.
+      # @see ::JSON::SchemaDsl.registered_renderers
+      def render_chain
+        ::JSON::SchemaDsl.registered_renderers
+      end
+    end
+  end
+end

data/lib/json/schema_dsl/renderers/alias.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module JSON
+  module SchemaDsl
+    module Renderers
+      # Aliases certain attributes and camel-cases all others.
+      # The only exception are property names which are set by the user and
+      # will not be camel-cased.
+      class Alias < Base
+        ALIASES = {
+          'ref' => '$ref'
+        }.freeze
+
+        # Camel-case and/or alias the attribute names of the given structure.
+        def visit(entity)
+          traverse(entity
+            .transform_keys { |key| ALIASES[key.to_s]&.to_sym || key }
+            .transform_keys { |key| camelize_snake_cased(key) })
+        end
+
+        private
+
+        def camelize_snake_cased(key)
+          key = key.to_s
+          (key.capitalize == key ? key : key.camelize(:lower)).to_sym
+        end
+
+        def traverse(entity)
+          entity.map do |key, value|
+            if key.to_s.match?(/properties$/i) && value.is_a?(Hash)
+              [key, value.transform_values { |v| visit(v) }]
+            else
+              [key, step(value)]
+            end
+          end.to_h
+        end
+      end
+    end
+  end
+end

data/lib/json/schema_dsl/renderers/base.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module JSON
+  module SchemaDsl
+    module Renderers
+      # The abstract base renderer that provides common behaviour
+      # to all renderers like the depth-first-traversal and
+      # access to the scope.
+      # @abstract
+      class Base
+        attr_reader :scope
+        # @param [Object] scope The scope used as a fallback for helper methods.
+        def initialize(scope)
+          @scope = scope
+        end
+
+        # @param [Hash] entity The entity-structure given as a tree.
+        #   This method will recursively visit each value in the structure until
+        #   all have been visited.
+        # @return [Hash] The hash-tree with all values visited.
+        def traverse(entity)
+          entity.transform_values { |v| step(v) }
+        end
+
+        protected
+
+        # @param [Object] value The value that should be visited. Behaves differently
+        #   for each renderer, since #visit holds the core logic of each.
+        # @return [Object] The visited object.
+        def step(value)
+          case value
+          when ::Array
+            value.first.is_a?(Hash) ? value.map { |v| visit(v) } : value
+          when Hash then visit(value)
+          else value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/json/schema_dsl/renderers/desugar.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module JSON
+  module SchemaDsl
+    module Renderers
+      # By default the first renderer that visits the tree.
+      # This renderer will translate all kinds of `syntax sugar` to
+      # a uniform format that fits json-schema.
+      class Desugar < Base
+        # Desugars all syntax sugar in that entity. This resolves concepts
+        # like `children` and `nullable` that are not present in the json
+        # schema specification itself but are used by the builder to ease
+        # the writing of schemas. In turn it
+        #
+        # * Transforms children to properties
+        # * Translates the `:required` attribute to the parent if true.
+        # * Collapses the item attribute of arrays into a single entity.
+        def visit(entity)
+          traverse(expand_children(nullable(entity)))
+        end
+
+        private
+
+        def expand_children(entity)
+          return entity unless entity[:children]
+          return collapse_items(entity) if entity[:items]
+
+          entity
+            .merge(required_properties(entity))
+            .merge(properties_properties(entity))
+        end
+
+        # Collapses the items into the first child for arrays.
+        def collapse_items(entity)
+          items = entity[:items]
+          items = items[:children].first if items[:children].to_a.count == 1
+          entity.merge(items: items)
+        end
+
+        # @param [Hash] entity An object entity-hash that has children.
+        # @return [Hash] The hash with children translated into properties and
+        # @todo Enable and fix rubocop warning about AbcSize
+        # rubocop:disable Metrics/AbcSize
+        def properties_properties(entity)
+          entity[:children]
+            .filter { |ch| ch[:name].present? }
+            .map { |ch| ch[:name] }
+            .zip(entity[:children].map { |c| visit(c) })
+            .map(&unrequire_property)
+            .group_by { |(name, _obj)| name.class }
+            .transform_keys { |k| k == Regexp ? :pattern_properties : :properties }
+            .transform_values(&:to_h)
+            .merge(children: nil)
+        end
+        # rubocop:enable Metrics/AbcSize
+
+        def unrequire_property
+          lambda do |(name, obj)|
+            obj = obj[:required] == true ? obj.merge(required: nil) : obj
+            [name, obj]
+          end
+        end
+
+        # Translates the required-properties of children into the required array
+        # of the parent structure.
+        def required_properties(entity)
+          requireds = entity[:children]
+                      .select { |ch| ch[:required] == true }
+                      .map { |ch| ch[:name].to_s }
+          pre_req = entity[:required].is_a?(Array) ? entity[:required] : []
+          { required: requireds | pre_req }
+        end
+
+        # Translates nullable property into a any_of: [null...]
+        def nullable(entity)
+          return entity unless entity[:nullable]
+
+          entity.merge(nullable: nil, any_of: [{ type: 'null' }]) do |k, old, new|
+            next unless k == :any_of
+
+            old + new
+          end
+        end
+      end
+    end
+  end
+end

data/lib/json/schema_dsl/renderers/filter.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module JSON
+  module SchemaDsl
+    module Renderers
+      # Filters out properties that are either used internally only or
+      # which are redundant (I.e. set to nil).
+      class Filter < Base
+        INVISIBLES = %w[Children Nullable Name].freeze
+
+        # Filters out properties that are either used internally only or
+        # which are redundant (I.e. set to nil).
+        def visit(entity)
+          traverse(filter(entity))
+        end
+
+        private
+
+        def filter(entity)
+          entity
+            .except(*(INVISIBLES + INVISIBLES.map(&:underscore).map(&:to_sym)))
+            .transform_values { |v| presence_of(v, preserve: [false]) }
+            .compact
+        end
+
+        def presence_of(obj, preserve: [])
+          return obj if preserve.include? obj
+
+          obj.presence
+        end
+      end
+    end
+  end
+end

data/lib/json/schema_dsl/renderers/multiplexer.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module JSON
+  module SchemaDsl
+    module Renderers
+      # Renderer that translates multiplexer properties (any_of, one_of or all_of)
+      # so that a new wrapping structure is returned that holds the original in
+      # one of these properties.
+      #
+      # @example Nullable object
+      #   obj = object :james, any_of: [null]
+      #   Multiplexer.new(nil).visit(obj)
+      #     #=> { type: 'entity', any_of: [{type: 'null'}, {type: 'object', ...}] }
+      #
+      class Multiplexer < Base
+        KEYS = %i[any_of one_of all_of].freeze
+
+        # Boxes the entity into a new one with the multiplexer attribute set
+        # to the entity, if required.
+        def visit(entity)
+          traverse(box(entity))
+        end
+
+        private
+
+        # Boxes the given entity unless it is of type 'entity' or has no
+        # multiplexer attributes. The entity itself will be added to the "box"
+        # if it has any other attributes set by the user.
+        # @param [Hash] entity The entity that may have a multiplexer attribute.
+        def box(entity)
+          present_key = entity[:type] != 'entity' && KEYS.find { |k| entity[k].present? }
+          return entity unless present_key
+
+          new_value = entity[present_key].map { |ch| visit(ch) }
+          unless container?(entity.except(present_key))
+            new_value.push(entity.except(present_key))
+          end
+
+          { type: 'entity', present_key => new_value.reject(&:blank?) }
+        end
+
+        # @return [Boolean] `true` if the object is only there to have the
+        #   boxing attribute, false otherwise.
+        def container?(entity)
+          cleaned_up = clean_up(entity)
+
+          cleaned_up[:type].to_s == 'object' && cleaned_up.keys.count <= 1
+        end
+
+        def clean_up(entity)
+          defaults = ::JSON::SchemaDsl.type_defaults[entity[:type].to_sym]
+          (entity.to_a - defaults.to_a).to_h.yield_self do |without_defaults|
+            Renderers::Filter.new(scope).visit(without_defaults)
+          end
+        end
+      end
+    end
+  end
+end