easy_talk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6fcc0c59463e51453f3a5242447abf42b06ea093e6573b3c887136e3036ad963
+  data.tar.gz: 62aea206f5db132804b9ceae927f3de2f2eefc429e137ff121b325b689eb458f
+SHA512:
+  metadata.gz: 8996f94f698b255160f318add11bab15b4b182a1127919885196d5ace961ca41f092a4d1f28eed553ed6848b36b3ae75ae49bbe82b5dbb60c32c89b75263b1c7
+  data.tar.gz: 4b81dc4128e4f9455d7bf7c814957e5ed38989ce5cd3de63ed5d2deb789706a360af1df16ded68f6ae0cbf1ec1ab728cac9216f71e3e9cda6250953620b5c235

data/.rubocop.yml

@@ -0,0 +1,14 @@
+AllCops:
+  TargetRubyVersion: 3.2
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+
+Lint/ConstantDefinitionInBlock:
+  Exclude:
+    - 'spec/**/*'
+
+Layout/LineLength:
+  Exclude:
+    - 'spec/**/*'

data/CONSTRAINTS.md

@@ -0,0 +1,70 @@
+The following constraints are supported by the JSON Schema generator:
+
+## String Properties
+
+| Constraint    |   Description |
+|---------------|---------------|
+| format        |   Specifies the format that the string should match (e.g., email, uuid). |
+| pattern       |	A regular expression pattern that the string must match. |
+| min_length    |	The minimum number of characters for the string. |
+| max_length	|   The maximum number of characters for the string. |
+| enum          |	An array that specifies the enumerated values the string can take. |
+| const         |	Specifies a single constant value the string must be equal to. |
+| default       |	The default value for the string. |
+
+## Integer and Number Properties
+| Constraint            |	Description |
+|-----------------------|---------------|
+| minimum               |	The minimum value the integer can be. |
+| maximum               |	The maximum value the integer can be. |
+| exclusive_minimum     |	If true, the value must be strictly greater than the minimum value. |
+| exclusive_maximum     |	If true, the value must be strictly less than the maximum value. |
+| multiple_of           |	A number that the integer must be a multiple of. |
+| enum                  |	An array that specifies the enumerated values the integer can take. |
+| const                 |	Specifies a single constant value the integer must be equal to. |
+| default               |	The default value for the integer. |
+
+
+## Array Properties
+| Constraint            |	Description |
+|-----------------------|---------------|
+| min_items             |	The minimum number of items in the array. |
+| max_items             |	The maximum number of items in the array. |
+| unique_items          |	If true, all items in the array must be unique. |
+| items                 |	An object that specifies the schema for each item in the array. |
+| enum                  |	An array that specifies the enumerated values the array can take. |
+| const                 |	Specifies a single constant value the array must be equal to. |
+| default               |	The default value for the array. |
+
+
+## Boolean Properties
+| Constraint            |	Description |
+|-----------------------|---------------|
+| enum                  |	An array that specifies the enumerated values the boolean can take. |
+| const                 |	Specifies a single constant value the boolean must be equal to. |
+| default               |	The default value for the boolean. |
+
+## Object Properties
+
+| Constraint            |	Description |
+|-----------------------|---------------|
+| properties            |	An object that specifies the schema for each property in the object. |
+| required              |	An array that specifies the required properties in the object. |
+| min_properties        |	The minimum number of properties in the object. |
+| max_properties        |	The maximum number of properties in the object. |
+| additional_properties |	An object that specifies the schema for additional properties in the object. |
+| pattern_properties    |	An object that specifies the schema for properties that match a regular expression pattern. |
+
+## Null Properties
+| Constraint            |	Description |
+|-----------------------|---------------|
+| enum                  |	An array that specifies the enumerated values the null can take. |
+| const                 |	Specifies a single constant value the null must be equal to. |
+| default               |	The default value for the null. |
+
+
+## All Properties 
+| Constraint    |	Description |
+|---------------|---------------|
+| title         |	A short summary of what the property represents. |
+| description   |	A detailed description of what the property represents. |

data/LICENSE.txt

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

data/README.md

@@ -0,0 +1,186 @@
+# EasyTalk
+
+EasyTalk is a Ruby library for defining and generating JSON Schema.
+
+Example Use:
+
+```ruby
+class User
+  include EasyTalk::Model
+
+  define_schema do
+    title "User"
+    description "A user of the system"
+    property :name, String, description: "The user's name", title: "Full Name"
+    property :email, String, description: "The user's email", format: "email", title: "Email Address"
+    property :group, String, enum: [1, 2, 3], default: 1, description: "The user's group"
+    property :age, Integer, minimum: 18, maximum: 100, description: "The user's age"
+    property :tags, T::Array[String], min_items: 1, unique_item: true, description: "The user's tags"
+  end
+end
+```
+
+Calling `User.json_schema` will return the JSON Schema for the User class:
+
+```json
+{
+    "title": "User",
+    "description": "A user of the system",
+    "type": "object",
+    "properties": {
+        "name": {
+            "title": "Full Name",
+            "description": "The user's name",
+            "type": "string"
+        },
+        "email": {
+            "title": "Email Address",
+            "description": "The user's email",
+            "type": "string",
+            "format": "email"
+        },
+        "group": {
+            "type": "number",
+            "enum": [1, 2, 3],
+            "default": 1,
+            "description": "The user's group"
+        },
+        "age": {
+            "type": "integer",
+            "minimum": 18,
+            "maximum": 100,
+            "description": "The user's age"
+        },
+        "tags": {
+            "type": "array",
+            "items": {
+                "type": "string"
+            },
+            "minItems": 1,
+            "uniqueItems": true,
+            "description": "The user's tags"
+        }
+    },
+    "required:": [
+        "name",
+        "email",
+        "group",
+        "age",
+        "tags"
+    ]
+}
+```
+
+## Installation
+
+ install the gem by running the following command in your terminal:
+
+    $ gem install easy_talk
+
+## Usage
+
+Simply include the `EasyTalk::Model` module in your Ruby class, define the schema using the `define_schema` block and call the `json_schema` class method to generate the JSON Schema document.
+
+
+## Schema Definition
+
+In the example above, the `define_schema` method is used to add a description and a title to the schema document. The `property` method is used to define the properties of the schema document. The `property` method accepts the name of the property as a symbol, the type, which can be a generic Ruby type or a [Sorbet type](https://sorbet.org/docs/stdlib-generics), and a hash of constraints as options.
+
+## Property Constraints
+
+Property constraints are type-dependent. Refer to the [CONSTRAINTS.md](CONSTRAINTS.md) file for a list of constraints supported by the JSON Schema generator.
+
+
+## Schema Composition
+
+EasyTalk supports schema composition. You can define a schema for a nested object by defining a new class and including the `EasyTalk::Model` module. You can then reference the nested schema in the parent schema using the following special types:
+
+- T::OneOf[Model1, Model2, ...] - The property must match at least one of the specified schemas.
+- T::AnyOf[Model1, Model2, ...] - The property can match any of the specified schemas.
+- T::AllOf[Model1, Model2, ...] - The property must match all of the specified schemas.
+
+Here is an example where we define a schema for a payment object that can be a credit card, a PayPal account, or a bank transfer. The first three classes represent the schemas for the different payment methods. The `Payment` class represents the schema for the payment object where the `Details` property can be any of the payment method schemas.
+
+```ruby
+  class CreditCard
+    include EasyTalk::Model
+
+    define_schema do
+      property :CardNumber, String
+      property :CardType, String, enum: %w[Visa MasterCard AmericanExpress]
+      property :CardExpMonth, Integer, minimum: 1, maximum: 12
+      property :CardExpYear, Integer, minimum: Date.today.year, maximum: Date.today.year + 10
+      property :CardCVV, String, pattern: '^[0-9]{3,4}$'
+      additional_properties false
+    end
+  end
+
+  class Paypal
+    include EasyTalk::Model
+
+    define_schema do
+      property :PaypalEmail, String, format: 'email'
+      property :PaypalPasswordEncrypted, String
+      additional_properties false
+    end
+  end
+
+  class BankTransfer
+    include EasyTalk::Model
+
+    define_schema do
+      property :BankName, String
+      property :AccountNumber, String
+      property :RoutingNumber, String
+      property :AccountType, String, enum: %w[Checking Savings]
+      additional_properties false
+    end
+  end
+
+  class Payment
+    include EasyTalk::Model
+
+    define_schema do
+      title 'Payment'
+      description 'Payment info'
+      property :PaymentMethod, String, enum: %w[CreditCard Paypal BankTransfer]
+      property :Details, T::AnyOf[CreditCard, Paypal, BankTransfer]
+    end
+  end
+
+```
+
+## Type Checking and Schema Constraints
+
+EasyTalk uses [Sorbet](https://sorbet.org/) to perform type checking on the property constraint values. The `property` method accepts a type as the second argument. The type can be a Ruby class or a Sorbet type. For example, `String`, `Integer`, `T::Array[String]`, etc.
+
+EasyTalk raises an error if the constraint values do not match the property type. For example, if you specify the `enum` constraint with the values [1,2,3], but the property type is `String`, EasyTalk will raise a type error.
+
+EasyTalk also raises an error if the constraints are not valid for the property type. For example, if you define a property with a `minimum` or a `maximum` constraint, but the type is `String`, EasyTalk will raise an error.
+
+## Schema Validation
+
+EasyTalk does not yet perform JSON validation. So far, it only aims to generate a valid JSON Schema document. You can use the `json_schema` method to generate the JSON Schema and use a JSON Schema validator library like [JSONSchemer](https://github.com/davishmcclurg/json_schemer) to validate JSON against. See https://json-schema.org/implementations#validators-ruby for a list of JSON Schema validator libraries for Ruby.
+
+The goal is to introduce JSON validation in the near future.
+
+## JSON Schema Specifications
+
+EasyTalk is currently very loose about JSON Schema specifications. It does not enforce the use of the latest JSON Schema specifications. Support for the dictionary of JSON Schema keywords varies depending on the keyword. The goal is to have robust support for the latest JSON Schema specifications in the near future.
+
+To learn about the current EasyTalk capabilities, take a look at the [spec/easy_talk/examples](https://github.com/sergiobayona/easy_talk/tree/main/spec/easy_talk/examples) folder. The examples are used to test the JSON Schema generation.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/sergiobayona/easy_talk. 
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/easy_talk.gemspec

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative 'lib/easy_talk/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'easy_talk'
+  spec.version = EasyTalk::VERSION
+  spec.authors = ['Sergio Bayona']
+  spec.email = ['bayona.sergio@gmail.com']
+
+  spec.summary = 'Generate json-schema from Ruby classes.'
+  spec.description = 'Generate json-schema from plain Ruby classes.'
+  spec.homepage = 'https://github.com/sergiobayona/easy_talk'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.2'
+
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/sergiobayona/easy_talk'
+  spec.metadata['changelog_uri'] = 'https://github.com/sergiobayona/easy_talk/blob/main/CHANGELOG.md'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ spec/ .git .github Gemfile])
+    end
+  end
+
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'activesupport', '~> 6.0'
+  spec.add_dependency 'sorbet-runtime'
+  spec.add_development_dependency 'pry-byebug', '>= 3.10.1'
+  spec.add_development_dependency 'rake', '~> 13.1'
+end

data/lib/easy_talk/builder.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative 'property'
+require_relative 'builders/object_builder'
+
+module EasyTalk
+  # The Builder class is responsible for building a schema for a class.
+  class Builder
+    extend T::Sig
+
+    sig { params(schema_definition: SchemaDefinition).void }
+    # Initializes a new instance of the Builder class.
+    #
+    # @param schema_definition [SchemaDefinition] The schema definition.
+    def initialize(schema_definition)
+      @schema_definition = schema_definition
+    end
+
+    sig { returns(Hash) }
+    # Retrieves the schema document.
+    #
+    # @return [Hash] The schema document.
+    def schema
+      @schema = schema_document
+    end
+
+    sig { returns(String) }
+    # Returns the JSON representation of the schema document.
+    #
+    # @return [String] The JSON schema.
+    def json_schema
+      @json_schema ||= schema_document.to_json
+    end
+
+    sig { returns(Hash) }
+    # Returns the schema document, building it if necessary.
+    #
+    # @return [Hash] The schema document.
+    def schema_document
+      @schema_document ||= build_schema
+    end
+
+    sig { returns(Hash) }
+    # Builds the schema using the schema definition.
+    #
+    # Returns the built schema.
+    def build_schema
+      Builders::ObjectBuilder.new(@schema_definition).build
+    end
+  end
+end

data/lib/easy_talk/builders/all_of_builder.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative 'composition_builder'
+
+module EasyTalk
+  module Builders
+    # Builder class for integer properties.
+    class AllOfBuilder < CompositionBuilder
+    end
+  end
+end

data/lib/easy_talk/builders/any_of_builder.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative 'composition_builder'
+
+module EasyTalk
+  module Builders
+    # Builder class for integer properties.
+    class AnyOfBuilder < CompositionBuilder
+    end
+  end
+end

data/lib/easy_talk/builders/base_builder.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+# typed: true
+
+module EasyTalk
+  module Builders
+    # BaseBuilder is a class that provides a common structure for building schema properties
+    class BaseBuilder
+      extend T::Sig
+
+      # BaseBuilder is a class that provides a common structure for building objects
+      # representing schema properties.
+      COMMON_OPTIONS = {
+        title: { type: T.nilable(String), key: :title },
+        description: { type: T.nilable(String), key: :description }
+      }.freeze
+
+      attr_reader :name, :schema, :options
+
+      sig do
+        params(
+          name: Symbol,
+          schema: T::Hash[Symbol, T.untyped],
+          options: T::Hash[Symbol, String],
+          valid_options: T::Hash[Symbol, T.untyped]
+        ).void
+      end
+      # Initializes a new instance of the BaseBuilder class.
+      #
+      # @param name [Symbol] The name of the property.
+      # @param schema [Hash] A hash representing a json schema object.
+      # @param options [Hash] The options for the builder (default: {}).
+      # @param valid_options [Hash] The acceptable options for the given property type (default: {}).
+      def initialize(name, schema, options = {}, valid_options = {})
+        @valid_options = COMMON_OPTIONS.merge(valid_options)
+        options.assert_valid_keys(@valid_options.keys)
+        @name = name
+        @schema = schema
+        @options = options
+      end
+
+      # Builds the schema object based on the provided options.
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      def build
+        @valid_options.each_with_object(schema) do |(key, value), obj|
+          next if @options[key].nil?
+
+          # Work around for Sorbet's default inability to type check the items inside an array
+
+          if value[:type].respond_to?(:recursively_valid?) && !value[:type].recursively_valid?(@options[key])
+            raise TypeError, "Invalid type for #{key}"
+          end
+
+          obj[value[:key]] = T.let(@options[key], value[:type])
+        end
+      end
+    end
+  end
+end

data/lib/easy_talk/builders/boolean_builder.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative 'base_builder'
+
+module EasyTalk
+  module Builders
+    # Builder class for boolean properties.
+    class BooleanBuilder < BaseBuilder
+      extend T::Sig
+
+      # VALID_OPTIONS defines the valid options for a boolean property.
+      VALID_OPTIONS = {
+        enum: { type: T::Array[T::Boolean], key: :enum },
+        const: { type: T::Boolean, key: :const },
+        default: { type: T::Boolean, key: :default }
+      }.freeze
+
+      sig { params(name: Symbol, _type: T.untyped, constraints: Hash).void }
+      def initialize(name, _type = nil, constraints = {})
+        super(name, { type: 'boolean' }, constraints, VALID_OPTIONS)
+      end
+    end
+  end
+end

data/lib/easy_talk/builders/composition_builder.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative 'base_builder'
+
+module EasyTalk
+  module Builders
+    # This class represents a builder for composing JSON schemas using the "allOf", "anyOf", or "oneOf" keywords.
+    class CompositionBuilder
+      extend T::Sig
+
+      COMPOSER_TO_KEYWORD = {
+        'AllOfBuilder' => 'allOf',
+        'AnyOfBuilder' => 'anyOf',
+        'OneOfBuilder' => 'oneOf'
+      }.freeze
+
+      sig { params(name: Symbol, type: T.untyped, _constraints: Hash).void }
+      # Initializes a new instance of the CompositionBuilder class.
+      #
+      # @param name [Symbol] The name of the composition.
+      # @param type [Class] The type of the composition.
+      # @param _constraints [Hash] The constraints for the composition (not used in this method).
+      def initialize(name, type, _constraints)
+        @composer_type = self.class.name.split('::').last
+        @name = name
+        @type = type
+        @context = {}
+      end
+
+      # Builds the composed JSON schema.
+      #
+      # @return [void]
+      def build
+        @context[@name.to_sym] = {
+          type: 'object',
+          composer_keyword => schemas
+        }
+      end
+
+      # Returns the composer keyword based on the composer type.
+      #
+      # @return [String] The composer keyword.
+      def composer_keyword
+        COMPOSER_TO_KEYWORD[@composer_type]
+      end
+
+      # Returns an array of schemas for the composed JSON schema.
+      #
+      # @return [Array<Hash>] The array of schemas.
+      def schemas
+        items.map do |type|
+          type.respond_to?(:schema) ? type.schema : { type: type.to_s.downcase }
+        end
+      end
+
+      # Returns the items of the type.
+      #
+      # @return [T.untyped] The items of the type.
+      def items
+        @type.items
+      end
+    end
+  end
+end

data/lib/easy_talk/builders/date_builder.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'base_builder'
+
+module EasyTalk
+  module Builders
+    # Builder class for date properties.
+    class DateBuilder < StringBuilder
+      # Modifies the schema to include the format constraint for a date property.
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      def schema
+        super.tap do |schema|
+          schema[:format] = 'date'
+        end
+      end
+    end
+  end
+end

data/lib/easy_talk/builders/datetime_builder.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'base_builder'
+
+module EasyTalk
+  module Builders
+    # Builder class for datetime properties.
+    class DatetimeBuilder < StringBuilder
+      # Modifies the schema to include the format constraint for a datetime property.
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      def schema
+        super.tap do |schema|
+          schema[:format] = 'date-time'
+        end
+      end
+    end
+  end
+end

data/lib/easy_talk/builders/integer_builder.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'base_builder'
+
+module EasyTalk
+  module Builders
+    # Builder class for integer properties.
+    class IntegerBuilder < BaseBuilder
+      extend T::Sig
+      VALID_OPTIONS = {
+        minimum: { type: Integer, key: :minimum },
+        maximum: { type: Integer, key: :maximum },
+        exclusive_minimum: { type: Integer, key: :exclusiveMinimum },
+        exclusive_maximum: { type: Integer, key: :exclusiveMaximum },
+        multiple_of: { type: Integer, key: :multipleOf },
+        enum: { type: T::Array[Integer], key: :enum },
+        const: { type: Integer, key: :const },
+        default: { type: Integer, key: :default }
+      }.freeze
+
+      # Initializes a new instance of the IntegerBuilder class.
+      sig { params(name: Symbol, _type: T.untyped, constraints: Hash).void }
+      def initialize(name, _type = nil, constraints = {})
+        super(name, { type: 'integer' }, constraints, VALID_OPTIONS)
+      end
+    end
+  end
+end

data/lib/easy_talk/builders/null_builder.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'base_builder'
+
+module EasyTalk
+  module Builders
+    # builder class for Null properties.
+    class NullBuilder < BaseBuilder
+      # Initializes a new instance of the NullBuilder class.
+      sig { params(name: Symbol, _type: T.untyped, _constraints: Hash).void }
+      def initialize(name, _type = nil, _constraints = {})
+        super(name, { type: 'null' }, {}, {})
+      end
+    end
+  end
+end