taro 2.4.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c7750f1403fa65519d22915908d5aeb6cf5bbeec5497d68369bf5a4e37fb0e8
-  data.tar.gz: 0b6d6b440c1f4fcdb965af8fb1aaf2d26f2ca3a9d2a2fb924bfe9456cb811090
+  metadata.gz: 66112afc92f209f1cea91ae5483f54c37e8d5a79635ebf616afa0b868bc13637
+  data.tar.gz: fe46dcf993a314c1b2a5a08088010c523041a90bda55c121d81cf91ed665c11d
 SHA512:
-  metadata.gz: 1f37ffe80f9f14ef49bd3131f0a64f5254219c4851de19ec6523143d508440cb263741c2ca56858eeff917cf0a4d1002b642b4e6f87498e47b62b3ffc5fbc4c8
-  data.tar.gz: 59fbfef1126825880c2d5b64b1d2a3799c25502d094f9758fa9181d7e1e3fa44b2b2504ccbf24c1d18925a5e53ceef1e1ca309cd8980f8950d385d1f3197aadb
+  metadata.gz: 48d2ba7713e024656b49845ff1053b42076450e23367fb01063f1dce4ac3b74cd1a13351ddc43eac11e678052da76ac51508af1ba41b746e05a10cccc4c2ae4a
+  data.tar.gz: '08bd1115dcbb4240ed10edb7dbd52471c597cf5de98c85ef87be76dce9b4aef938cdc6b38ff8089c5ccfa3b684c887f75104e5ac5f9bc42eb8e3abe72e61a61c'

data/CHANGELOG.md

@@ -1,5 +1,45 @@
 ## [Unreleased]
 
+## [3.0.0] - 2026-03-03
+
+### Changed
+
+- there is a new `required:` property for input / param fields that defaults to `true`
+  - this is a major breaking change!
+  - `null: true` previously also allowed completely omitting a parameter
+  - now `null: true` only allows the parameter to be `null`, but it still has to be submitted
+  - set `required: false` to make parameters optional
+  - your requests will now fail by default if parameters are missing, even with `null: true`
+  - to exactly preserve the previous behavior:
+    - replace `null: true` with `null: true, required: false` in all your definitions
+    - replace `null: false` with `required: true` in all your definitions
+  - `required:` also defines which fields are marked as required in the OpenAPI export
+    - previously, all nullable fields were exported as non-required and vice versa
+  - if a `default:` is given, `required:` becomes `false` automatically
+- missing parameters are no longer added to `@api_params` with `nil` values
+  - this is a minor breaking change
+  - previously, if a nullable param `foo` was omitted, taro added `foo: nil` to `@api_params`
+  - now, if the param is not required and not sent, it will simply be missing from `@api_params`
+  - if you relied on the previous behavior, you can set `default: nil` for the param
+
+### Added
+
+- there is now a default for `null` - all fields (input & output) now default to `null: false`
+  - this is a non-breaking change because `null:` was previously a required keyword argument
+  - as a result, `null:` is now an optional argument and setting `null: false` is now redundant
+- config options `Taro.config.default_value_for_null` and `Taro.config.default_value_for_required`
+- option to mark whole endpoints as deprecated (`api 'My endpoint', deprecated: true`)
+
+### Fixed
+
+- improved some error messages by ensuring the field name and type are mentioned
+
+## [2.5.0] - 2025-04-16
+
+### Added
+
+- Support for setting `openapi_format` for types and during export
+
 ## [2.4.0] - 2025-03-11
 
 ### Added

data/README.md

@@ -37,12 +37,13 @@ class BikesController < ApplicationController
   api     'Update a bike', desc: 'My longer text', tags: ['Bikes']
 
   # Params can come from the path, e.g. /bike/:id.
-  # Some types, like UUID in this case, are predefined. See below for more types.
-  param   :id, type: 'UUID', null: false, desc: 'ID of the bike to update'
+  # Some types, like UUID in this case, are predefined.
+  # See below for a list of all included types.
+  param   :id, type: 'UUID', desc: 'ID of the bike to update'
 
   # Params can also come from the query string or request body.
-  # This describes a Hash param:
-  param   :bike, type: 'BikeInputType', null: false
+  # This is a Hash param, implemented below.
+  param   :bike, type: 'BikeInputType'
 
   # Return types can differ by status code:
   returns code: :ok, type: 'BikeType', desc: 'update success'
@@ -56,10 +57,11 @@ class BikesController < ApplicationController
     success = bike.update(@api_params[:bike])
 
     # Types are also used to render responses.
+    # Taro validates that the correct type is used for the declared status code.
     if success
       render json: BikeType.render(bike), status: :ok
     else
-      render json: { error: MyErrorType.render(bike.errors.first) }, status: :unprocessable_entity
+      render json: { error: MyErrorType.render(bike.errors.first) }, status: :unprocessable_content
     end
   end
 
@@ -72,29 +74,30 @@ class BikesController < ApplicationController
 end
 ```
 
-Notice the multiple roles of types: They are used to describe the structure of API requests and responses, and render the response. Both the input and output of the API are validated against the schema by default (see below).
+Notice the multiple roles of types: They are used to describe the structure of API requests and responses, as well as to render the response. Both the input and output of the API are validated against the schema by default (see below).
 
-Here is an example of the `BikeType` from the controller above:
+Here is an example of the `BikeType` that is used to render the success response of the controller above:
 
 ```ruby
 class BikeType < ObjectType
-  # Optional description of BikeType (for the OpenAPI export)
+  # Optional description of the type (for the OpenAPI export)
   self.desc = 'A bike and all relevant information about it'
 
-  # Object types have fields. Each field has a name, its own type,
-  # and a `null:` setting to indicate if it can be nil.
-  # Providing a description is optional.
+  # Object types have fields. Each field has a name and its own type
+  field :wheels, type: 'Integer'
+
+  # Fields can be made nullable and can have a description
   field :brand, type: 'String', null: true, desc: 'The brand name'
 
-  # Fields can reference other types and arrays of values
-  field :users, array_of: 'UserType', null: false
+  # Fields can reference other custom types and arrays of values
+  field :users, array_of: 'UserType'
 
   # Custom methods can be chosen to resolve fields
-  field :has_brand, type: 'Boolean', null: false, method: :brand?
+  field :has_brand, type: 'Boolean', method: :brand?
 
   # Field resolvers can also be implemented or overridden on the type.
   # The object passed in to `BikeType.render` is available as `object`.
-  field :fancy_info, type: 'String', null: false
+  field :fancy_info, type: 'String'
   def fancy_info
     "A bike named #{object.name} with #{object.parts.count} parts."
   end
@@ -103,14 +106,14 @@ end
 
 ### Input and response types
 
-You can use object types for input and output. However, if you want added control, you can also define dedicated input and response types.
+You can use object types for both input and output. However, if you want added control, you can also define dedicated input and response types.
 
 Note the use of `BikeInputType` in the `param` declaration above? It could look like so:
 
 ```ruby
 class BikeInputType < InputType
-  field :brand,  type: 'String',  null: true,  desc: 'The brand name'
-  field :wheels, type: 'Integer', null: false, default: 2
+  field :brand,  type: 'String',  null: true, desc: 'The brand name'
+  field :wheels, type: 'Integer', default: 2
 end
 ```
 
@@ -121,7 +124,7 @@ Likewise, there is a special type for responses, which can't be used in input de
 ```ruby
 class BikeSearchResponseType < ResponseType
   field :bike, type: 'BikeType', null: true, desc: 'The found bike'
-  field :search_duration, type: 'Integer', null: false
+  field :search_duration, type: 'Integer'
 end
 ```
 
@@ -193,7 +196,7 @@ Response validation can be disabled:
 Taro.config.validate_responses = false
 ```
 
-### Common error declarations
+#### Common error declarations
 
 `::common_return` can be used to add a return declaration to all actions in a controller and its subclasses, and all related OpenAPI exports.
 
@@ -207,6 +210,53 @@ class AuthenticatedApiBaseController < ApiBaseController
 end
 ```
 
+#### Nullable and required fields
+
+By default, all fields are required and non-nullable. "Required" means the field must be part of the input/output, and "non-nullable" means it can't be set to null.
+
+To make a field nullable, use `null: true`. This goes for both input and output fields, e.g.:
+
+```ruby
+param :brand, type: 'String', null: true
+```
+
+This means that the `brand` param can be set to null. If you want to allow the param to be omitted entirely in requests, set `required: false`.
+
+```ruby
+param :brand, type: 'String', null: true, required: false
+```
+
+If you want to support partial updates of an attribute, but not setting it to null, you would only specify `required: false`. This will allow the param to be omitted, but submitting null for it will raise an error.
+
+```ruby
+param :brand, type: 'String', required: false
+def update
+  bike.update!(@api_params)
+  # ...
+end
+```
+
+The `required` option is only relevant for input fields. When rendering output, taro automatically inserts null values for missing but nullable fields, e.g.
+
+```ruby
+BikeType.render(wheels: 2)
+# => { "wheels": 2, "brand": null }
+```
+
+It is also possible to change the default values for `null` and `required`:
+
+```ruby
+Taro.config.default_value_for_null = true
+Taro.config.default_value_for_required = false
+```
+
+Set defaults to nil to enforce explicit declaration on every param and field:
+
+```ruby
+Taro.config.default_value_for_null = nil
+param :foo, type: 'String' # => error: null has to be specified
+```
+
 ### Included type options
 
 The following type names are available by default and can be used as `type:`, `array_of:`, or `page_of:` arguments:
@@ -237,7 +287,7 @@ class SeverityEnumType < EnumType
 end
 
 class ErrorType < ObjectType
-  field :severity, type: 'SeverityEnumType', null: false
+  field :severity, type: 'SeverityEnumType'
 end
 ```
 
@@ -245,7 +295,7 @@ Inline enums are also possible. Unlike EnumType classes, these are inlined in th
 
 ```ruby
 class ErrorType < ObjectType
-  field :severity, type: 'String', enum: %w[info warning debacle], null: false
+  field :severity, type: 'String', enum: %w[info warning debacle]
 end
 ```
 
@@ -316,6 +366,16 @@ class BikeType < ObjectType
 end
 ```
 
+### Can I mark things as deprecated?
+
+Yes. Endpoints, params, fields, and types can all be marked as deprecated.
+
+```ruby
+api 'Legacy bike index, to be removed in 2043', deprecated: true
+
+PennyFarthingType.deprecated = true
+```
+
 ### How do I migrate from apipie-rails?
 
 First of all, if you don't need a better OpenAPI export, or better support for hashes and arrays, or less repetitive definitions, it might not be worth it.
@@ -330,7 +390,6 @@ If you want to migrate anyway:
 
 - extract complex param declarations into InputTypes
 - extract complex response declarations into ObjectTypes or ResponseTypes
-- replace `required: true` with `null: false` and `required: false` with `null: true`
 
 Taro uses some of the same DSL as `apipie`, so for a step-by-step migration, you might want to make `taro` use a different one. This initializer will change the `taro` DSL to `taro_api`, `taro_param`, and `taro_returns` and leave `api`, `param`, and `returns` to `apipie`:
 
@@ -410,8 +469,7 @@ end
   - mixed arrays
   - mixed enums
   - nullable enums
-  - string format specifications (e.g. binary, int64, password ...)
-  - string minLength and maxLength (substitute: `self.pattern = /\A.{3,5}\z/`)
+  - string minLength and maxLength (substitute: `MyType.pattern = /\A.{3,5}\z/`)
   - number minimum, exclusiveMinimum, maximum, multipleOf
   - readOnly, writeOnly
 

data/lib/taro/config.rb

@@ -2,6 +2,8 @@ module Taro::Config
   singleton_class.attr_accessor(
     :api_name,
     :api_version,
+    :default_value_for_null,
+    :default_value_for_required,
     :export_format,
     :export_path,
     :parse_params,
@@ -12,6 +14,8 @@ module Taro::Config
   # defaults
   self.api_name = 'Taro-based API'
   self.api_version = '1.0'
+  self.default_value_for_null = false
+  self.default_value_for_required = true
   self.export_format = :yaml
   self.export_path = 'api.yml'
   self.parse_params = true

data/lib/taro/declaration.rb

@@ -2,7 +2,7 @@
 # Descendants must implement #endpoint and (only for openapi export) #routes.
 # See Taro::Rails::Declaration for an example.
 class Taro::Declaration
-  attr_reader :desc, :summary, :params, :return_defs, :return_descriptions, :tags
+  attr_reader :deprecated, :desc, :summary, :params, :return_defs, :return_descriptions, :tags
 
   def initialize(for_klass = nil)
     @params = Class.new(Taro::Types::RailsParamsType)
@@ -12,9 +12,10 @@ class Taro::Declaration
     Taro::CommonReturns.for(for_klass).each { |rd| add_return_def(rd) }
   end
 
-  def add_info(summary, desc: nil, tags: nil)
+  def add_info(summary, deprecated: nil, desc: nil, tags: nil)
     summary.is_a?(String) || raise(Taro::ArgumentError, 'api summary must be a String')
     @summary = summary
+    @deprecated = true if deprecated
     @desc = desc
     @tags = Array(tags) if tags
   end

data/lib/taro/export/open_api_v3.rb

@@ -26,6 +26,7 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
   def export_route(route, declaration)
     {
       route.verb.to_sym => {
+        deprecated: declaration.deprecated,
         description: declaration.desc,
         summary: declaration.summary,
         tags: declaration.tags,
@@ -70,7 +71,7 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
       name: field.name,
       deprecated: field.deprecated,
       description: field.desc,
-      required: !field.null,
+      required: field.required,
       schema: export_field(field).except(:deprecated, :description),
     }.compact
   end
@@ -129,7 +130,7 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
 
   def export_type(type)
     if type < Taro::Types::ScalarType && !custom_scalar_type?(type)
-      { type: type.openapi_type }
+      { type: type.openapi_type, format: type.openapi_format }.compact
     else
       extract_component_ref(type)
     end
@@ -148,7 +149,7 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
   end
 
   def export_scalar_field(field)
-    base = { type: field.openapi_type }
+    base = { type: field.openapi_type, format: field.openapi_format }.compact
     # Using oneOf seems more correct than an array of types
     # as it puts props like format together with the main type.
     # https://github.com/OAI/OpenAPI-Specification/issues/3148
@@ -199,7 +200,7 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
   end
 
   def object_type_details(type)
-    required = type.fields.values.reject(&:null).map(&:name)
+    required = type.fields.values.select(&:required).map(&:name)
     {
       type: type.openapi_type,
       deprecated: type.deprecated,

data/lib/taro/rails/generators/templates/error_type.erb

@@ -5,6 +5,6 @@
 # You can customize these files to fit your needs, or delete them.
 class ErrorType < ObjectType
   field :attribute, type: 'String', null: true, desc: 'Attribute name'
-  field :code, type: 'String', null: false, method: :type, desc: 'Error code'
+  field :code, type: 'String', method: :type, desc: 'Error code'
   field :message, type: 'String', null: true, desc: 'Error message'
 end

data/lib/taro/return_def.rb

@@ -14,7 +14,7 @@ class Taro::ReturnDef
   def evaluate
     if nesting
       Class.new(Taro::Types::NestedResponseType).tap do |type|
-        type.field(nesting, defined_at:, null: false, **params)
+        type.field(nesting, defined_at:, **params)
       end
     else
       Taro::Types::Coercion.call(params)

data/lib/taro/types/base_type.rb

@@ -17,6 +17,7 @@ Taro::Types::BaseType = Struct.new(:object) do
   extend Taro::Types::Shared::Description
   extend Taro::Types::Shared::Equivalence
   extend Taro::Types::Shared::Name
+  extend Taro::Types::Shared::OpenAPIFormat
   extend Taro::Types::Shared::OpenAPIName
   extend Taro::Types::Shared::OpenAPIType
   extend Taro::Types::Shared::Rendering

data/lib/taro/types/field.rb

@@ -1,25 +1,58 @@
-require_relative 'field_validation'
+require_relative 'field_value_validation'
 
-Taro::Types::Field = Data.define(:name, :type, :null, :method, :default, :enum, :defined_at, :desc, :deprecated) do
-  include Taro::Types::FieldValidation
+Taro::Types::Field = Data.define(
+  :name, :type,
+  :default, :defined_at, :deprecated, :desc, :enum, :null, :required, :resolver,
+) do
+  include Taro::Types::FieldValueValidation
   include Taro::Types::Shared::Errors
   include Taro::Types::Shared::TypeClass
 
-  def initialize(name:, type:, null:, method: name, default: Taro::None, enum: nil, defined_at: nil, desc: nil, deprecated: nil)
+  def initialize(
+    name:,
+    type:,
+    default: Taro::None,
+    defined_at: nil,
+    deprecated: nil,
+    desc: nil,
+    enum: nil,
+    method: name, # note: `method` is stored as #resolver to avoid overriding Object#method
+    null: Taro.config.default_value_for_null,
+    required: default == Taro::None ? Taro.config.default_value_for_required : false
+  )
     enum = coerce_to_enum(enum)
-    super(name:, type:, null:, method:, default:, enum:, defined_at:, desc:, deprecated:)
+    super(
+      name:,
+      type:,
+      default:,
+      defined_at:,
+      deprecated: (true if deprecated),
+      desc:,
+      enum:,
+      null: !!null,
+      required: !!required,
+      resolver: method,
+    )
   end
 
   def value_for_input(object)
-    value = object[name] if object
+    unless object&.key?(name)
+      fail_if_required
+      return default_specified? ? default : Taro::None
+    end
+    value = object[name]
     value = coerce_value(value, true)
     validated_value(value)
+  rescue Taro::ValidationError => e
+    reraise_recursively_with_path_info(e)
   end
 
   def value_for_response(object, context: nil, object_is_hash: true)
     value = retrieve_response_value(object, context, object_is_hash)
     value = coerce_value(value, false)
     validated_value(value, false)
+  rescue Taro::ValidationError => e
+    reraise_recursively_with_path_info(e)
   end
 
   def default_specified?
@@ -30,6 +63,10 @@ Taro::Types::Field = Data.define(:name, :type, :null, :method, :default, :enum,
     type.openapi_type
   end
 
+  def openapi_format
+    type.openapi_format
+  end
+
   private
 
   def coerce_to_enum(arg)
@@ -42,22 +79,22 @@ Taro::Types::Field = Data.define(:name, :type, :null, :method, :default, :enum,
   end
 
   def retrieve_response_value(object, context, object_is_hash)
-    if context&.resolve?(method)
-      context.public_send(method)
+    if context&.resolve?(resolver)
+      context.public_send(resolver)
     elsif object_is_hash
       retrieve_hash_value(object)
-    elsif object.respond_to?(method, true)
-      object.public_send(method)
+    elsif object.respond_to?(resolver, true)
+      object.public_send(resolver)
     else
-      response_error "No such method or resolver `:#{method}`", object
+      response_error "No such method or resolver `:#{resolver}`", object
     end
   end
 
   def retrieve_hash_value(object)
-    if object.key?(method.to_s)
-      object[method.to_s]
+    if object.key?(resolver.to_s)
+      object[resolver.to_s]
     else
-      object[method]
+      object[resolver]
     end
   end
 
@@ -67,8 +104,6 @@ Taro::Types::Field = Data.define(:name, :type, :null, :method, :default, :enum,
 
     type_obj = type.new(value)
     from_input ? type_obj.coerce_input : type_obj.cached_coerce_response
-  rescue Taro::ValidationError => e
-    reraise_recursively_with_path_info(e)
   end
 
   def reraise_recursively_with_path_info(error)

data/lib/taro/types/field_def.rb

@@ -1,5 +1,9 @@
+require_relative 'field_def_validation'
+
 # Lazily-evaluated field definition.
 class Taro::Types::FieldDef
+  include Taro::Types::FieldDefValidation
+
   attr_reader :attributes, :defined_at
 
   def initialize(defined_at: nil, **attributes)
@@ -23,40 +27,4 @@ class Taro::Types::FieldDef
   def ==(other)
     other.is_a?(self.class) && attributes == other.attributes
   end
-
-  private
-
-  def validate
-    validate_name
-    validate_null
-    validate_type_key
-  end
-
-  def validate_name
-    name.is_a?(Symbol) || raise(Taro::ArgumentError, <<~MSG)
-      field name must be a Symbol, got #{name.class} at #{defined_at}
-    MSG
-  end
-
-  def validate_null
-    [true, false].include?(attributes[:null]) || raise(Taro::ArgumentError, <<~MSG)
-      null has to be specified as true or false for field #{name} at #{defined_at}"
-    MSG
-  end
-
-  def validate_type_key
-    attributes[type_key].class == String || raise(Taro::ArgumentError, <<~MSG)
-      #{type_key} must be a String for field #{name} at #{defined_at}
-    MSG
-  end
-
-  def type_key
-    possible_keys = Taro::Types::Coercion.keys
-    keys = attributes.keys & possible_keys
-    keys.size == 1 || raise(Taro::ArgumentError, <<~MSG)
-      Exactly one of #{possible_keys.join(', ')} must be given
-      for field #{name} at #{defined_at}
-    MSG
-    keys.first
-  end
 end

data/lib/taro/types/field_def_validation.rb

@@ -0,0 +1,65 @@
+module Taro::Types::FieldDefValidation
+  private
+
+  def validate
+    validate_name
+    validate_null
+    validate_required
+    validate_required_default_conflict
+    validate_type_key
+  end
+
+  def validate_name
+    name.is_a?(Symbol) || raise(Taro::ArgumentError, <<~MSG)
+      field name must be a Symbol, got #{name.class} at #{defined_at}
+    MSG
+  end
+
+  def validate_null
+    if attributes.key?(:null)
+      [true, false].include?(attributes[:null]) || raise(Taro::ArgumentError, <<~MSG)
+        null has to be specified as true or false for field #{name} at #{defined_at}"
+      MSG
+    elsif Taro.config.default_value_for_null.nil?
+      raise(Taro::ArgumentError, <<~MSG)
+        null has to be specified for field #{name} at #{defined_at} because there is no default
+      MSG
+    end
+  end
+
+  def validate_required
+    if attributes.key?(:required)
+      [true, false].include?(attributes[:required]) || raise(Taro::ArgumentError, <<~MSG)
+        required has to be specified as true or false for field #{name} at #{defined_at}
+      MSG
+    elsif Taro.config.default_value_for_required.nil?
+      raise(Taro::ArgumentError, <<~MSG)
+        required has to be specified for field #{name} at #{defined_at} because there is no default
+      MSG
+    end
+  end
+
+  def validate_required_default_conflict
+    return unless attributes[:required] && attributes.key?(:default)
+
+    raise(Taro::ArgumentError, <<~MSG)
+      required: true cannot be combined with a default for field #{name} at #{defined_at}
+    MSG
+  end
+
+  def validate_type_key
+    attributes[type_key].class == String || raise(Taro::ArgumentError, <<~MSG)
+      #{type_key} must be a String for field #{name} at #{defined_at}
+    MSG
+  end
+
+  def type_key
+    possible_keys = Taro::Types::Coercion.keys
+    keys = attributes.keys & possible_keys
+    keys.size == 1 || raise(Taro::ArgumentError, <<~MSG)
+      Exactly one of #{possible_keys.join(', ')} must be given
+      for field #{name} at #{defined_at}
+    MSG
+    keys.first
+  end
+end

data/lib/taro/types/{field_validation.rb → field_value_validation.rb}

@@ -1,4 +1,4 @@
-module Taro::Types::FieldValidation
+module Taro::Types::FieldValueValidation
   # Validate the value against the field properties. This method will raise
   # a Taro::InputError or Taro::ResponseError if the value is not matching.
   def validated_value(value, for_input = true)
@@ -22,4 +22,8 @@ module Taro::Types::FieldValidation
     msg = "field expects one of #{enum.inspect}, got #{value.inspect}"
     for_input ? input_error(msg, value) : response_error(msg, value)
   end
+
+  def fail_if_required
+    required && input_error('field is required but key is missing', nil)
+  end
 end

data/lib/taro/types/object_types/page_info_type.rb

@@ -1,8 +1,8 @@
 class Taro::Types::ObjectTypes::PageInfoType < Taro::Types::ResponseType
   self.openapi_name = 'PageInfo'
 
-  field :has_previous_page, type: 'Boolean', null: false, desc: 'Whether there is a previous page of results'
-  field :has_next_page, type: 'Boolean', null: false, desc: 'Whether there is another page of results'
+  field :has_previous_page, type: 'Boolean', desc: 'Whether there is a previous page of results'
+  field :has_next_page, type: 'Boolean', desc: 'Whether there is another page of results'
   field :start_cursor, type: 'String', null: true, desc: 'The first cursor in the current page of results (null if zero results)'
   field :end_cursor, type: 'String', null: true, desc: 'The last cursor in the current page of results (null if zero results)'
 end

data/lib/taro/types/object_types/page_type.rb

@@ -9,8 +9,8 @@ class Taro::Types::ObjectTypes::PageType < Taro::Types::ResponseType
 
   def self.derive_from(from_type)
     super
-    field(:page, array_of: from_type.name, null: false)
-    field(:page_info, type: 'Taro::Types::ObjectTypes::PageInfoType', null: false)
+    field(:page, array_of: from_type.name)
+    field(:page_info, type: 'Taro::Types::ObjectTypes::PageInfoType')
   end
 
   def self.render(relation, **)

data/lib/taro/types/object_types/page_with_total_count_type.rb

@@ -11,7 +11,7 @@
 class Taro::Types::ObjectTypes::PageWithTotalCountType < Taro::Types::ObjectTypes::PageType
   def self.derive_from(from_type)
     super
-    field(:total_count, type: 'Integer', null: false)
+    field(:total_count, type: 'Integer')
   end
 
   def self.paginate(relation, **)

data/lib/taro/types/shared/deprecation.rb

@@ -1,3 +1,7 @@
 module Taro::Types::Shared::Deprecation
-  attr_accessor :deprecated
+  attr_reader :deprecated
+
+  def deprecated=(value)
+    @deprecated = value ? true : nil
+  end
 end

data/lib/taro/types/shared/object_coercion.rb

@@ -2,9 +2,12 @@
 module Taro::Types::Shared::ObjectCoercion
   def coerce_input
     validate_no_undeclared_params
-    self.class.fields.transform_values do |field|
-      field.value_for_input(object)
+    result = {}
+    self.class.fields.each do |name, field|
+      value = field.value_for_input(object)
+      result[name] = value unless value.equal?(Taro::None)
     end
+    result
   end
 
   # Render the object into a hash.

data/lib/taro/types/shared/openapi_format.rb

@@ -0,0 +1,61 @@
+# Provides a setter and getter for type classes' `openapi_format`,
+# for use in the OpenAPI export.
+module Taro::Types::Shared::OpenAPIFormat
+  OPENAPI_STRING_FORMATS = %i[
+    date
+    date-time
+    password
+    byte
+    binary
+    email
+    uuid
+    uri
+    hostname
+    ipv4
+    ipv6
+  ].freeze
+
+  OPENAPI_INTEGER_FORMATS = %i[
+    int32
+    int64
+  ].freeze
+
+  OPENAPI_NUMBER_FORMATS = %i[
+    float
+    double
+  ].freeze
+
+  def openapi_format
+    return unless @openapi_format
+
+    unless valid_formats_for_openapi_type.include?(@openapi_format)
+      raise(Taro::ArgumentError, "openapi_format #{@openapi_format.inspect} is invalid for openapi_type #{@openapi_type.inspect}, must be one for #{valid_formats_for_openapi_type}")
+    end
+
+    @openapi_format
+  end
+
+  def openapi_format=(arg)
+    @openapi_format = arg
+  end
+
+  def inherited(subclass)
+    subclass.instance_variable_set(:@openapi_format, @openapi_format)
+    super
+  end
+
+  private
+
+  def valid_formats_for_openapi_type
+    case @openapi_type
+    when :string
+      OPENAPI_STRING_FORMATS
+    when :integer
+      OPENAPI_INTEGER_FORMATS
+    when :number
+      OPENAPI_NUMBER_FORMATS
+    else
+      []
+    end
+  end
+end

data/lib/taro/version.rb

@@ -1,4 +1,4 @@
 # :nocov:
 module Taro
-  VERSION = "2.4.0"
+  VERSION = "3.0.0"
 end

data/tasks/benchmark.rake

@@ -6,11 +6,11 @@ task :benchmark do
   data = JSON.load_file("#{__dir__}/benchmark_1kb.json", symbolize_names: true)
 
   item_type = Class.new(Taro::Types::ObjectType) do
-    field :name, type: 'String', null: false
-    field :language, type: 'String', null: false
-    field :id, type: 'String', null: false
-    field :bio, type: 'String', null: false
-    field :version, type: 'Float', null: false
+    field :name, type: 'String'
+    field :language, type: 'String'
+    field :id, type: 'String'
+    field :bio, type: 'String'
+    field :version, type: 'Float'
   end
 
   type = item_type.array

metadata

@@ -1,15 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: taro
 version: !ruby/object:Gem::Version
-  version: 2.4.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Janosch Müller
 - Johannes Opper
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-03-11 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -27,7 +26,6 @@ dependencies:
         version: '3.0'
 description: This library provides an object-based type system for RESTful Ruby APIs,
   with built-in parameter parsing, response rendering, and OpenAPI schema export.
-email:
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -80,7 +78,8 @@ files:
 - lib/taro/types/enum_type.rb
 - lib/taro/types/field.rb
 - lib/taro/types/field_def.rb
-- lib/taro/types/field_validation.rb
+- lib/taro/types/field_def_validation.rb
+- lib/taro/types/field_value_validation.rb
 - lib/taro/types/input_type.rb
 - lib/taro/types/list_type.rb
 - lib/taro/types/nested_response_type.rb
@@ -115,6 +114,7 @@ files:
 - lib/taro/types/shared/item_type.rb
 - lib/taro/types/shared/name.rb
 - lib/taro/types/shared/object_coercion.rb
+- lib/taro/types/shared/openapi_format.rb
 - lib/taro/types/shared/openapi_name.rb
 - lib/taro/types/shared/openapi_type.rb
 - lib/taro/types/shared/pattern.rb
@@ -131,7 +131,6 @@ metadata:
   homepage_uri: https://github.com/taro-rb/taro
   source_code_uri: https://github.com/taro-rb/taro
   changelog_uri: https://github.com/taro-rb/taro/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -146,8 +145,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Typed Api using Ruby Objects.
 test_files: []