json_schema_view 0.1.0

data/lib/json_schema_view/configuration/schema_set_dictionary.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module JsonSchemaView
+  class Configuration
+    # :nodoc:
+    class SchemaSetDictionary < Delegator
+      attr_reader :hash
+
+      # @param contents [Hash, nil]
+      def initialize(contents = nil)
+        @hash = ActiveSupport::HashWithIndifferentAccess.new(contents)
+        super
+      end
+
+      # @overload {Delegator#__getobj__}
+      # @return [HashWithIndifferentAccess{Symbol => Symbol}]
+      def __getobj__
+        hash
+      end
+
+      # @overload {Delegator#__setobj__}
+      def __setobj__(_)
+        # noop
+      end
+
+      # @param key [#to_sym] The alias name of SchemaSet
+      # @param value [String, Symbol] The name of SchemaSet class
+      def []=(key, value)
+        raise TypeError, "key (#{key}) cannot be converted to a symbol" unless key.respond_to?(:to_sym)
+
+        if !value.is_a?(String) && !value.is_a?(Symbol)
+          raise TypeError,
+                "value (#{value}) must be the name of SchemaSet class"
+        end
+
+        hash[key.to_sym] = value.to_sym
+      end
+
+      # @return [SchemaSet]
+      def fetch_instance(key)
+        klass = fetch(key).constantize
+
+        raise TypeError, "#{klass} is not the name of SchemaSet class" unless klass < JsonSchemaView::SchemaSet
+
+        klass.new
+      end
+    end
+  end
+end

data/lib/json_schema_view/configuration.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module JsonSchemaView
+  # The singleton holds the configuration for the gem.
+  # it can be accessed by both its class methods and Rails's configuration.
+  class Configuration
+    require_relative "configuration/schema_set_dictionary"
+
+    class << self
+      # @return [JsonSchemaView::Configuration]
+      def instance
+        @instance ||= new
+      end
+
+      # @yield [configuration]
+      # @yieldparam configuration [JsonSchemaView::Configuration]
+      def configure(&block)
+        instance.configure(&block)
+      end
+    end
+
+    def initialize
+      @schema_sets = SchemaSetDictionary.new
+      @validate_by_default = false
+    end
+
+    # @return [SchemaSetDictionary{Symbol => Symbol}] The renderers.
+    attr_reader :schema_sets
+
+    # @return [Boolean] Whether if validate components with its schema on render by default.
+    attr_accessor :validate_by_default
+
+    # @param new_sets [Hash{String, Symbol => String, Symbol}]
+    def schema_sets=(new_sets)
+      @schema_sets = SchemaSetDictionary.new(new_sets)
+    end
+
+    # @yield [configuration]
+    # @yieldparam configuration [JsonSchemaView::Configuration]
+    def configure
+      yield self
+    end
+  end
+end

data/lib/json_schema_view/json_schema_definable.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "json_world"
+
+require_relative "json_world_extensions"
+
+module JsonSchemaView
+  # @abstract
+  module JsonSchemaDefinable
+    extend ActiveSupport::Concern
+
+    include ::JsonWorld::DSL
+    include JsonWorldExtensions::Schema202012
+    include JsonWorldExtensions::CompactOptionalProperties
+    include JsonWorldExtensions::Camelizable
+    include JsonWorldExtensions::Validatable
+
+    included do
+      additional_properties(false)
+    end
+  end
+end

data/lib/json_schema_view/json_world_extensions/additional_properties.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "active_support"
+
+module JsonSchemaView
+  module JsonWorldExtensions
+    # Define JSON Schema's additionalProperties property.
+    # @see https://json-schema.org/understanding-json-schema/reference/object.html#additional-properties
+    #
+    # @example
+    #   class Zoo
+    #     include JsonWorld::DSL
+    #     include JsonSchemaView::JsonWorldExtensions::MapType::DSL
+    #
+    #     additional_properties(false)
+    #     property(
+    #       :dogMap,
+    #       type: map_type(Dog),
+    #     )
+    #   end
+    module AdditionalProperties
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # @override {Class.override}
+        def inherited(child)
+          super
+          child.additional_properties(additional_properties)
+        end
+
+        # Return the additionalProperties property.
+        # Set the additionalProperties property if arguments are given.
+        # @see https://json-schema.org/draft/2020-12/json-schema-core.html#additionalProperties
+        # @see https://json-schema.org/understanding-json-schema/reference/object.html#id5
+        #
+        # @param value [false, Hash]
+        # @param value_keywords [Hash]
+        def additional_properties(value = nil, **value_keywords)
+          return @additional_properties = value unless value.nil?
+          return @additional_properties = value_keywords unless value_keywords.empty?
+
+          @additional_properties
+        end
+
+        # @override {JsonWorld::DSL::ClassMethods#as_json_schema}
+        def as_json_schema
+          # Do not allow undefined properities.
+          # @see https://json-schema.org/understanding-json-schema/reference/object.html#additionalproperties
+          if @additional_properties.nil?
+            super
+          else
+            super.merge("additionalProperties": @additional_properties)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/json_schema_view/json_world_extensions/any_of.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module JsonSchemaView
+  module JsonWorldExtensions
+    # This class implements `anyOf` schema composition.
+    # Instances of this class acts as an json world compatible object and prints the schema for anyOf combination.
+    # @see https://json-schema.org/understanding-json-schema/reference/combining.html#id6
+    # @example
+    #   class Zoo
+    #     include JsonWorld::DSL
+    #     include JsonSchemaView::JsonWorldExtensions::MapType::DSL
+    #     property(
+    #       :animal,
+    #       type: any_of.new(Dog, Cat),
+    #     )
+    #   end
+    class AnyOf
+      module DSL
+        extend ActiveSupport::Concern
+
+        class_methods do
+          def any_of(*types)
+            JsonWorldExtensions::AnyOf.new(*types)
+          end
+        end
+      end
+
+      attr_reader :types
+
+      def initialize(*types)
+        @types = types
+      end
+
+      def as_json_schema
+        { "anyOf" => types.map(&:as_json_schema) }
+      end
+
+      alias as_json_schema_without_links as_json_schema
+    end
+  end
+end

data/lib/json_schema_view/json_world_extensions/camelizable.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "active_support"
+
+module JsonSchemaView
+  module JsonWorldExtensions
+    # Make the object to be serialized with camelized properties.
+    module Camelizable
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # @param (see JsonWorld::DSL::ClassMethods#property)
+        # @param camelize [Boolean] if true, camelize the property name on json format.
+        def property(raw_property_name, camelize: true, **options)
+          raw_property_name = raw_property_name.to_sym
+          property_name = camelize ? camelize_name(raw_property_name) : raw_property_name
+
+          super(property_name, **options)
+
+          # Define a method with camelized name as an alias of the method with raw name.
+          if camelize && property_name != raw_property_name
+            define_method(property_name) do
+              public_send(raw_property_name)
+            end
+          end
+        end
+
+        # @param name [String, Symbol]
+        # @return [Symbol]
+        def camelize_name(name)
+          ActiveSupport::Inflector.camelize(name.to_s, false).to_sym
+        end
+      end
+    end
+  end
+end

data/lib/json_schema_view/json_world_extensions/compact_optional_properties.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module JsonSchemaView
+  module JsonWorldExtensions
+    # This module automatically removes properties with null value from encoded json if the property is optional.
+    #
+    # JSON Schema distinguishs a optional property and a nullable property.
+    # If the value of a optional property is empty, you should remove the property from the encoded json.
+    # This module make safe such the optional properties.
+    # @see https://json-schema.org/understanding-json-schema/reference/object.html#required-properties
+    module CompactOptionalProperties
+      # @note Overrides {JsonWorld::JsonEncodable#properties}
+      def properties(options)
+        optional_property_names = self.class.property_definitions.select(&:optional?).map(&:property_name)
+
+        super(options).reject { |key, value| value.nil? && optional_property_names.include?(key) }
+      end
+    end
+  end
+end

data/lib/json_schema_view/json_world_extensions/constant_property.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module JsonSchemaView
+  module JsonWorldExtensions
+    # This module allows {JsonWorld::DSL::ClassMethods#property} to define constant values.
+    # Defined constant values are reflect to JSON Schema.
+    # @see https://json-schema.org/understanding-json-schema/reference/generic.html#constant-values
+    module ConstantProperty
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # If property is defined with `const` parameter, define an instance method to return the value.
+        # @note Overrides {JsonWorld::DSL::ClassMethods#property}
+        def property(name, **options)
+          if options[:const]
+            const = options[:const].freeze
+            define_method(name) { const }
+          end
+
+          super(name, **options)
+        end
+
+        # Add constant values informations JSON Schema
+        # @note Overrides {JsonWorld::DSL::ClassMethods#as_json_schema}
+        def as_json_schema
+          property_hash = property_definitions.map do |property|
+            if (const = property.raw_options[:const])
+              # For now, use enumerated values instead of constant values.
+              [property.property_name, { const: const }]
+            else
+              nil
+            end
+          end.compact.to_h
+          super.deep_merge(properties: property_hash)
+        end
+      end
+    end
+  end
+end

data/lib/json_schema_view/json_world_extensions/declarable.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module JsonSchemaView
+  module JsonWorldExtensions
+    # Add methods to declare a common schema. Declared schema are exported as `$defs` property.
+    #
+    # @see: https://json-schema.org/understanding-json-schema/structuring.html#defs
+    module Declarable
+      extend ::ActiveSupport::Concern
+
+      class_methods do
+        attr_writer :declarations
+
+        # @override {Class.inherited}
+        def inherited(child)
+          super
+          child.declarations = declarations.clone
+        end
+
+        # @param type_or_name [Class<JsonWorld::DSL>, Symbol]
+        # @param (see JsonWorld::DSL::ClassMethods#property)
+        def declare(type_or_name, **options)
+          property_type = options[:type] || type_or_name
+          property_name = type_or_name.is_a?(Module) ? type_or_name.name.demodulize.to_sym : type_or_name.to_sym
+
+          declaration = JsonWorld::PropertyDefinition.new(property_name: property_name, type: property_type, **options)
+          declarations << declaration
+        end
+
+        # @override {JsonWorld::DSL::ClassMethods#as_json_schema}
+        def as_json_schema
+          decls = declarations_as_json_schema
+          if decls.present?
+            super.merge("$defs": decls)
+          else
+            super
+          end
+        end
+
+        def declarations_as_json_schema
+          declarations.inject({}) do |result, declaration|
+            result.merge(
+              declaration.property_name => declaration.as_json_schema,
+            )
+          end
+        end
+
+        # @return [Array<PropertyDefinition>]
+        def declarations
+          @declarations ||= []
+        end
+      end
+    end
+  end
+end

data/lib/json_schema_view/json_world_extensions/enum_type.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module JsonSchemaView
+  module JsonWorldExtensions
+    # This module allows {JsonWorld::DSL::ClassMethods#property} to define enum values.
+    # Defined constant values are reflect to JSON Schema.
+    # @see https://json-schema.org/understanding-json-schema/reference/generic.html#enumerated-values
+    # @example
+    #   class Zoo
+    #     include JsonWorld::DSL
+    #     include JsonSchemaView::JsonWorldExtensions::EnumType::DSL
+    #     property(
+    #       :animal,
+    #       type: enum_type("Dog", "Cat"),
+    #     )
+    #   end
+    class EnumType
+      module DSL
+        extend ActiveSupport::Concern
+
+        class_methods do
+          def enum_type(*args)
+            JsonWorldExtensions::EnumType.new(*args)
+          end
+        end
+      end
+
+      attr_reader :candidates
+
+      # @param type [String, Symbol, #as_json_schema]
+      # @param candidates [Array<Object>]
+      def initialize(*candidates)
+        @candidates = candidates
+      end
+
+      def as_json_schema
+        {
+          enum: candidates
+        }
+      end
+
+      alias as_json_schema_without_links as_json_schema
+    end
+  end
+end

data/lib/json_schema_view/json_world_extensions/map_type.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module JsonSchemaView
+  module JsonWorldExtensions
+    # This class implements map type (string keys to values with the given type) in JSON Schema.
+    # You can specify the type of values but you cannot specify the type of keys,
+    # because JSON and JSON Schema only support String keys in objects.
+    #
+    # @see https://json-schema.org/understanding-json-schema/reference/object.html#additional-properties
+    #
+    # @example
+    #   class Zoo
+    #     include JsonWorld::DSL
+    #     include JsonSchemaView::JsonWorldExtensions::MapType::DSL
+    #     property(
+    #       :dogMap,
+    #       type: map_type(Dog),
+    #     )
+    #   end
+    class MapType
+      module DSL
+        extend ActiveSupport::Concern
+
+        class_methods do
+          def map_type(type)
+            JsonWorldExtensions::MapType.new(type)
+          end
+        end
+      end
+
+      attr_reader :type
+
+      def initialize(type)
+        @type = type
+      end
+
+      def as_json_schema
+        {
+          type: "object",
+          additionalProperties: JsonWorld::PropertyDefinition.new(type: type).as_json_schema
+        }
+      end
+
+      alias as_json_schema_without_links as_json_schema
+    end
+  end
+end

data/lib/json_schema_view/json_world_extensions/validatable.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "json"
+require "json-schema"
+
+module JsonSchemaView
+  module JsonWorldExtensions
+    # Add method to validate self properties with {JSON::Validator}.
+    module Validatable
+      # @raise [JSON::Schema::ValidationError] if self is not valid.
+      # @return [void]
+      def validate_json!
+        JSON::Validator.validate!(self.class.as_json_schema, as_json)
+      end
+    end
+  end
+end

data/lib/json_schema_view/json_world_extensions.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "active_support"
+
+module JsonSchemaView
+  # A collection of extensions for {JsonWorld::DSL} to support recent JSON Schema.
+  # @private
+  module JsonWorldExtensions
+    require_relative "json_world_extensions/additional_properties"
+    require_relative "json_world_extensions/any_of"
+    require_relative "json_world_extensions/camelizable"
+    require_relative "json_world_extensions/compact_optional_properties"
+    require_relative "json_world_extensions/constant_property"
+    require_relative "json_world_extensions/declarable"
+    require_relative "json_world_extensions/enum_type"
+    require_relative "json_world_extensions/map_type"
+    require_relative "json_world_extensions/validatable"
+
+    # @see https://json-schema.org/specification.html
+    module Schema202012
+      extend ActiveSupport::Concern
+
+      include AdditionalProperties
+      include AnyOf::DSL
+      include ConstantProperty
+      include Declarable
+      include EnumType::DSL
+      include MapType::DSL
+    end
+  end
+end

data/lib/json_schema_view/rails/generators/install/USAGE

@@ -0,0 +1,5 @@
+Description:
+  Generates the configuration file (config/initializers/json_schema_view.rb) and setup components dir (app/components).:
+
+Example:
+  `bin/rails generate json_schema_view:install`

data/lib/json_schema_view/rails/generators/install/install_generator.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module JsonSchemaView
+  module Generators
+    # Install files to setup json_schema_view gem.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :components_path, type: :string, default: "app/components"
+      class_option :export_path, type: :string, default: "json_schema"
+      class_option :renderer_type, type: :string, default: "react_on_rails"
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/json_schema_view.rb"
+      end
+
+      def create_base_classes
+        template "base_component.rb", File.join(components_path, "base_component.rb")
+        template "base_props.rb", File.join(components_path, "base_props.rb")
+        template "component_schema_set.rb", File.join(components_path, "component_schema_set.rb")
+      end
+
+      def create_exmaples
+        template "example/todo_list_component.rb", File.join(components_path, "example_todo_list_component.rb")
+        template "example/todo_item_resource.rb",
+                 File.join(components_path, "example_todo_list_component", "todo_item_resource.rb")
+      end
+
+      private
+
+      def components_path
+        options[:components_path]
+      end
+
+      def export_path
+        options[:export_path]
+      end
+
+      def renderer_type
+        options[:renderer_type]
+      end
+
+      def schema_set_class_name
+        "ComponentSchemaSet"
+      end
+    end
+  end
+end

data/lib/json_schema_view/rails/generators/install/templates/base_component.rb.tt

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "json_schema_view"
+
+# @abstract
+class BaseComponent < ::JsonSchemaView::BaseComponent
+  # You can configure how this components is rendered.
+  # 
+  # There are some preset renderers:
+  # * `:json` - serialize the component as json text.
+  # * `:react_on_rails` - render the component by using react_on_rails gem.
+  renderer_class(:<%= renderer_type %>)
+
+  def base_props_class
+    BaseProps
+  end
+end

data/lib/json_schema_view/rails/generators/install/templates/base_props.rb.tt

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "json_schema_view"
+
+# @abstract
+class BaseProps < ::JsonSchemaView::BaseProps
+end

data/lib/json_schema_view/rails/generators/install/templates/component_schema_set.rb.tt

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "json_schema_view"
+
+# Configure what resource to export its JSON Schema and where directory to export.
+class <%= schema_set_class_name %> < ::JsonSchemaView::SchemaSet
+  # <%= schema_set_class_name %> looks up component classses in this directory.
+  def root_path
+    __dir__
+  end
+
+  # <%= schema_set_class_name %> exports JSON Schema of these component classes.
+  def resource_classes_to_export
+    [
+      # Export all component classes (except for BaseComopnent) in `root_path`.
+      *search_component_classes.excluding(BaseComponent),
+      # You can add extra classes including {JsonSchemaDefinable} here to export their JSON Schemas.
+    ]
+  end
+
+  # <%= schema_set_class_name %> exports JSON Schema to this directory.
+  def export_path
+    Rails.root.join("<%= export_path %>")
+  end
+end

data/lib/json_schema_view/rails/generators/install/templates/example/todo_item_resource.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "json_schema_view"
+
+class ExampleTodoListComponent
+  # This is an example definition of a resource.
+  #
+  # A class that includes {JsonSchemaView::JsonSchemaDefinable} can generate its JSON Schema
+  # and it can be used as a type in another resource's property.
+  class TodoItemResource
+    include JsonSchemaView::JsonSchemaDefinable
+
+    property(
+      :name,
+      description: "The title of TODO item.",
+      type: String,
+    )
+
+    property(
+      :done,
+      description: "Whether the TODO item is done or not.",
+      type: [TrueClass, FalseClass],
+    )
+
+    property(
+      :note,
+      description: "The additional description of TODO item.",
+      type: String,
+      optional: true,
+    )
+
+    # @param todo_item [Hash] A todo item ({ name: String, done: Boolean, note: String or nil }).
+    def initialize(todo_item)
+      @todo_item = todo_item
+    end
+
+    # @return [String] The title of TODO item.
+    def title
+      @todo_item[:title]
+    end
+
+    # @return [Boolean] Whether the TODO item is done or not.
+    def done
+      @todo_item[:done]
+    end
+
+    # @param note [String, nil] The additional description of TODO item.
+    def note
+      @todo_item[:note]
+    end
+  end
+end