notion_ruby_mapping 4.0.1 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60caedd2da9ab654284cb0d15f93fdef648e3d93b85e73a2d8e0b074657b6658
-  data.tar.gz: 5b2474e262b7ed381d6ab266a898df26b736d5990c2cb441391c730615b40b8d
+  metadata.gz: 366fc4989968bff0fb71d9376b58d3e270fa3e7d91581d37ab75653ec06cb8e3
+  data.tar.gz: e36897b1704fafa277c1996459d148abac1fcf03d62d9e23a8ee67a7325e9a11
 SHA512:
-  metadata.gz: '0785e9cd53092787c84aedeba453559934d4501cc73f75ffed2be447d939dc817ee69ee05696af03025d21184d495fdd2c699336e756bca3d84511cc6595d7b0'
-  data.tar.gz: 69e57b27cfa5d4ff92e1c71b1de13ab44f6706fe2c83cde73aa82f65d24e02788898e8deafe8ed240ef9f752a3e919998d367aa099cd0efca87a226cc8ba93a6
+  metadata.gz: 531c093bf3a67cf10dba9208c1321c6f3a8d35f808195167947f761563cc961e3bac59be090c70dc7bfdee1f453bba964d160f912ad035ebdc114d441541765d
+  data.tar.gz: 3e7f35ff1b8bbcfc51052f34cc873da0f4436175faced7ac12140c34d0dff4b91f83b555ea888483643d068485c43a23714b7186dd9b8b950d957759a7c347dc

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 ## [Unreleased]
 
+## [4.1.0] - 2026-08-23
+
+### Removed
+
+- `Property#contents?`
+- `Property#assert_database_property`
+- `def_delegators :retrieve_page_property` and `extend Forwardable` in `Property`
+  (a workaround for the 2022-06-28 API version, made unnecessary by the 2022-08-31 update)
+
+### Changed
+
+- `Property.create_from_json` now raises a `StandardError` when the given JSON has no `type` key
+- Unsupported property types now raise a unified message:
+  `Unsupported property type: <type> (<name>). Please update notion_ruby_mapping.`
+- `Property#update_from_json` now assigns the value whenever the key exists,
+  so `false` and empty values are reflected correctly
+- `List#initialize` normalizes `query` to `Query.new` when `nil` is given
+- `assert_*` methods use positive conditions and a consistent
+  `Database or DataSource property` wording
+
 ## [0.1.0] - 2022-02-07
 
-- Initial release
+- Initial release

data/README.md

@@ -143,8 +143,10 @@ NotionRubyMapping.configuration { |c| c.notion_token = ENV["NOTION_API_TOKEN"] }
 
 ## 3. ChangeLog
 
-- 2027/5/4 [v4.0.1] Add retrieve / update / delete a comment
-- 2027/3/23 [v4.0.0] Add markdown support, headnig_4, toggle_heading_4, and position support for appending blocks
+- 2026/8/23 [v4.1.0] Refactor Property base class (remove def_delegators and contents?, raise for unsupported property type)
+- 2026/7/14 [v4.0.2] Add clear method for DateProperty
+- 2026/5/4 [v4.0.1] Add retrieve / update / delete a comment
+- 2026/3/23 [v4.0.0] Add markdown support, headnig_4, toggle_heading_4, and position support for appending blocks
 - 2026/1/25 [v3.0.6] add move page, list templates, and create child page to page
 - 2025/12/15 [v3.0.5] add AudioBlock
 - 2025/12/9 [v3.0.4] Fix the issue where page.parent could not be executed for pages with a data source as parent

data/lib/notion_ruby_mapping/blocks/list.rb

@@ -26,7 +26,7 @@ module NotionRubyMapping
       when "template"
         @template = value
       end
-      @query = query
+      @query = query || Query.new
       @index = 0
       @has_content = true
     end

data/lib/notion_ruby_mapping/controllers/mermaid_data_source.rb

@@ -96,7 +96,7 @@ module NotionRubyMapping
 
         when "multi_select"
           if property
-            (options - (property.multi_select_options.map { |h| h["name"] })).each do |select_name|
+            (options - property.multi_select_options.map { |h| h["name"] }).each do |select_name|
               property.add_multi_select_option name: select_name, color: "default"
             end
           else
@@ -145,7 +145,7 @@ module NotionRubyMapping
           end
         when "select"
           if property
-            (options - (property.select_options.map { |h| h["name"] })).each do |select_name|
+            (options - property.select_options.map { |h| h["name"] }).each do |select_name|
               property.add_select_option name: select_name, color: "default"
             end
           else
@@ -165,7 +165,7 @@ module NotionRubyMapping
         property = ps.values_at(forward).first
         if property
           if reverse
-            if property.data_source_id == db_is && property.synced_property_name == reverse
+            if property.relation_data_source_id == db_is && property.synced_property_name == reverse
               relation_ds.add_property "relation", reverse
               relation_ds.finish_flag[reverse] = true
             else

data/lib/notion_ruby_mapping/controllers/rich_text_array.rb

@@ -79,6 +79,10 @@ module NotionRubyMapping
       map(&:text).join ""
     end
 
+    def clear
+      self.rich_text_objects = []
+    end
+
     # @param [RichTextArray, String, Array<String>, RichTextObject, Array<RichTextObject>] text_info
     def rich_text_objects=(text_info)
       @will_update = true

data/lib/notion_ruby_mapping/properties/button_property.rb

@@ -9,13 +9,13 @@ module NotionRubyMapping
 
     ## Common methods
 
-    # @return [Boolean, Hash, nil]
+    # @return [Hash, nil]
     def button
       @json
     end
 
     # @param [String, Symbol] name Property name
-    # @param [Boolean, Hash] json
+    # @param [Hash, nil] json Button property object
     def initialize(name, will_update: false, base_type: "page", property_id: nil, property_cache: nil, json: nil)
       super name, will_update: will_update, base_type: base_type, property_id: property_id,
                   property_cache: property_cache

data/lib/notion_ruby_mapping/properties/checkbox_property.rb

@@ -10,7 +10,7 @@ module NotionRubyMapping
 
     ## Common methods
 
-    # @return [Boolean, Hash, nil]
+    # @return [Boolean, Hash] true/false for page property, schema hash for database/data_source property
     # @see https://www.notion.so/hkob/CheckboxProperty-ac1edbdb8e264af5ad1432b522b429fd#20da1bf0cbcc4d4eb22d9125386522c2
     def checkbox
       @json
@@ -18,7 +18,7 @@ module NotionRubyMapping
 
     ## Page property only methods
 
-    # @param [Boolean] flag
+    # @param [Boolean] flag Checkbox value. Use true or false.
     # @return [TrueClass, FalseClass] settled value
     # @see https://www.notion.so/hkob/CheckboxProperty-ac1edbdb8e264af5ad1432b522b429fd#f167c85c1d2d40dfb8b3b6ce582e0f15
     def checkbox=(flag)
@@ -39,7 +39,7 @@ module NotionRubyMapping
       @json = if database_or_data_source?
                 json || {}
               else
-                json || false
+                json.nil? ? false : json
               end
     end
 

data/lib/notion_ruby_mapping/properties/created_time_property.rb

@@ -9,7 +9,7 @@ module NotionRubyMapping
 
     ## Common methods
 
-    # @return [Date, Hash]
+    # @return [String, Hash]
     # @see https://www.notion.so/hkob/CreatedTimeProperty-bb979ff02dc04efa9733da1003efa871#f1e80400878346c3a9ba8e32b824ed2b
     def created_time
       @json

data/lib/notion_ruby_mapping/properties/date_property.rb

@@ -112,17 +112,26 @@ module NotionRubyMapping
 
     ## Page property only methods
 
+    def clear
+      self.start_date = nil
+      self
+    end
+
     # @return [Hash] created json
     def property_values_json
       assert_page_property __method__
       {
         @name => {
           "type" => TYPE,
-          "date" => {
-            "start" => value_str(@json["start"]),
-            "end" => value_str(@json["end"]),
-            "time_zone" => @json["time_zone"],
-          },
+          "date" => if @json["start"].nil?
+                      nil
+                    else
+                      {
+                        "start" => value_str(@json["start"]),
+                        "end" => value_str(@json["end"]),
+                        "time_zone" => @json["time_zone"],
+                      }
+                    end,
         },
       }
     end

data/lib/notion_ruby_mapping/properties/email_property.rb

@@ -13,14 +13,14 @@ module NotionRubyMapping
 
     ## Common methods
 
-    # @return [String, Hash]
+    # @return [String, Hash, nil] email address for page properties, empty hash for database/data source properties
     def email
       @json
     end
 
     ## Page property only methods
 
-    # @param [String] email
+    # @param [String, nil] email
     def email=(email)
       assert_page_property __method__
       @will_update = true
@@ -35,7 +35,7 @@ module NotionRubyMapping
     def initialize(name, will_update: false, base_type: "page", json: nil, property_id: nil, property_cache: nil)
       super name, will_update: will_update, base_type: base_type, property_id: property_id,
                   property_cache: property_cache
-      @json = json || {}
+      @json = database_or_data_source? ? {} : json
     end
 
     # @return [Hash]

data/lib/notion_ruby_mapping/properties/files_property.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module NotionRubyMapping
-  # Select property
+  # Files property
   class FilesProperty < Property
     include IsEmptyIsNotEmpty
     TYPE = "files"
@@ -12,6 +12,14 @@ module NotionRubyMapping
 
     ## Page property only methods
 
+    # Removes all files from the property.
+    #
+    # This method replaces the files array with an empty array.
+    def clear
+      assert_page_property __method__
+      self.files = []
+    end
+
     def files=(files = [])
       assert_page_property __method__
       @will_update = true
@@ -22,7 +30,7 @@ module NotionRubyMapping
     def file_names=(file_names = [])
       array_file_names = Array(file_names)
       unless @files.length == array_file_names.length
-        raise StandardError,
+        raise ArgumentError,
               "files and file_names must be the same sizes."
       end
 
@@ -75,19 +83,5 @@ module NotionRubyMapping
       @will_update = false
       self
     end
-
-    protected
-
-    # @param [String] url
-    # @return [Hash]
-    def url_to_hash(url)
-      {
-        "name" => url,
-        "type" => "external",
-        "external" => {
-          "url" => url,
-        },
-      }
-    end
   end
 end

data/lib/notion_ruby_mapping/properties/last_edited_by_property.rb

@@ -33,7 +33,6 @@ module NotionRubyMapping
                 UserObject.new user_id: user_id, json: json
               end
     end
-    attr_reader :user
 
     # @param [Hash] json
     def update_from_json(json)

data/lib/notion_ruby_mapping/properties/last_edited_time_property.rb

@@ -9,7 +9,7 @@ module NotionRubyMapping
 
     ## Common methods
 
-    # @return [Date, Hash]
+    # @return [String, Hash]
     # @see https://www.notion.so/hkob/LastEditedTimeProperty-5058fd594f6748a48fd4db52535f4c18#a7b568bf997c44d49cdbe4bfbf29824e
     def last_edited_time
       @json

data/lib/notion_ruby_mapping/properties/multi_property.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module NotionRubyMapping
-  # MultiSelect property
+  # Base class for multi-value properties
   class MultiProperty < Property
     include ContainsDoesNotContain
     include IsEmptyIsNotEmpty

data/lib/notion_ruby_mapping/properties/multi_select_property.rb

@@ -9,12 +9,12 @@ module NotionRubyMapping
 
     ## Common methods
 
-    # @return [Array, Hash]
+    # @return [Array<Hash>, Hash] raw multi_select array for page property, or multi_select schema object for database/data_source property
     def multi_select
       @json
     end
 
-    # @return [Array]
+    # @return [Array<String>] selected option names for page property, or schema option names for database/data_source property
     def multi_select_names
       mshs = @base_type == "page" ? @json : @json["options"]
       mshs.map { |h| h["name"] }
@@ -24,30 +24,30 @@ module NotionRubyMapping
 
     # @param [String] name
     # @param [String] color
-    # @return [Array] added array
+    # @return [Array<Hash>] updated multi_select options
     # @see https://www.notion.so/hkob/MultiSelectProperty-b90bba1c55d540ba97131bb013d4ca74#bcac830b00e04cb6bf7dbbb110d95667
     def add_multi_select_option(name:, color:)
       edit_multi_select_options << {"name" => name, "color" => color}
     end
 
-    # @return [Array] copyed multi select options
+    # @return [Array<Hash>] editable multi_select options
     def edit_multi_select_options
       assert_database_or_data_source_property __method__
       @will_update = true
       @json["options"] ||= []
     end
 
-    # @return [Array]
+    # @return [Array<Hash>] schema multi_select options
     # @see https://www.notion.so/hkob/MultiSelectProperty-b90bba1c55d540ba97131bb013d4ca74#5ff6ec299cf64049bde2416f61b30fa9
     def multi_select_options
-      assert_data_source_property __method__
+      assert_database_or_data_source_property __method__
       @json["options"] || []
     end
 
     ## Page property only methods
 
-    # @param [Hash] multi_select
-    # @return [Array, nil] settled array
+    # @param [String, Array<String>, nil] multi_select selected option name or names
+    # @return [Array<Hash>] settled array
     def multi_select=(multi_select)
       assert_page_property __method__
       @will_update = true
@@ -59,8 +59,8 @@ module NotionRubyMapping
     ## Common methods
 
     # @param [String, Symbol] name
-    # @param [Hash] json
-    # @param [Array<String>, String] multi_select
+    # @param [Hash, nil] json
+    # @param [String, Array<String>, nil] multi_select selected option name or names (optional)
     def initialize(name, will_update: false, base_type: "page", json: nil, multi_select: nil,
                    property_id: nil, property_cache: nil)
       super name, will_update: will_update, base_type: base_type, property_id: property_id,
@@ -89,7 +89,7 @@ module NotionRubyMapping
 
     ## Page property only methods
 
-    # @return [Hash] created json
+    # @return [Hash] page property values payload
     def property_values_json
       assert_page_property __method__
       {

data/lib/notion_ruby_mapping/properties/number_property.rb

@@ -38,8 +38,8 @@ module NotionRubyMapping
 
     ## Page property only methods
 
-    # @param [Numeric] num
-    # @return [Numeric] settled number
+    # @param [Numeric, nil] num Number value. nil clears the value.
+    # @return [Numeric, nil] settled number
     # @see https://www.notion.so/hkob/NumberProperty-964ebc1948074d7ca8340187aa352d40#a3f28cc7029046878dfd694b5b33e8d8
     def number=(num)
       assert_page_property __method__

data/lib/notion_ruby_mapping/properties/people_property.rb

@@ -9,7 +9,15 @@ module NotionRubyMapping
 
     ## Common methods
 
-    # @return [Array, Hash]
+    # Returns the people assigned to this property.
+    #
+    # For a page property, this returns an array of UserObject instances.
+    # For a database or data source property, this returns the schema payload.
+    #
+    # Do not modify the returned array directly. Use `people=` or `add_person`
+    # to update the property.
+    #
+    # @return [Array<UserObject>, Hash]
     # @see https://www.notion.so/hkob/PeopleProperty-144355d25f0e4feba9ae39fe28ca6ae7#7e3e56c2080d4834902cfa0223e807e5
     def people
       @json
@@ -17,8 +25,13 @@ module NotionRubyMapping
 
     ## Page property only methods
 
-    # @param [String, NotionRubyMapping::UserObject] user_id_or_uo
-    # @return [Array<UserObject>]
+    # Adds a person to this people property.
+    #
+    # This method marks the property as changed.
+    # This method does not remove duplicate users.
+    #
+    # @param [String, UserObject] user_id_or_uo user ID or user object to add
+    # @return [Array<UserObject>] updated people
     # @see https://www.notion.so/hkob/PeopleProperty-144355d25f0e4feba9ae39fe28ca6ae7#26344b145a254cc58dd845780e0a26ea
     def add_person(user_id_or_uo)
       assert_page_property __method__
@@ -26,8 +39,14 @@ module NotionRubyMapping
       @json << UserObject.user_object(user_id_or_uo)
     end
 
-    # @param [Hash] people
-    # @return [Array, nil] replaced array
+    # Replaces all people in this property.
+    #
+    # Passing nil or an empty array clears the people property.
+    # This method marks the property as changed.
+    #
+    # @param [String, UserObject, Array<String>, Array<UserObject>, nil] people
+    #   user ID, user object, array of them, or nil
+    # @return [Array<UserObject>] replaced people
     # @see https://www.notion.so/hkob/PeopleProperty-144355d25f0e4feba9ae39fe28ca6ae7#815acfef9a664e3e8915fb31b8fefc42
     def people=(people)
       assert_page_property __method__

data/lib/notion_ruby_mapping/properties/phone_number_property.rb

@@ -13,7 +13,7 @@ module NotionRubyMapping
 
     ## Common methods
 
-    # @return [String, Hash, nil] phone number (Page), {} (Database)
+    # @return [String, Hash, nil] phone number for page properties, empty hash for database/data source properties
     # @see https://www.notion.so/hkob/PhoneNumberProperty-5df14aaa938c4888aecd53ab6752d2e6#40bceda04fe04c64b932d6a1ed180eaa
     def phone_number
       @json
@@ -21,7 +21,7 @@ module NotionRubyMapping
 
     ## Page property only methods
 
-    # @param [String] phone_number
+    # @param [String, nil] phone_number
     # @see https://www.notion.so/hkob/PhoneNumberProperty-5df14aaa938c4888aecd53ab6752d2e6#dc7e00e0558d40f79ca5cade1fccef29
     def phone_number=(phone_number)
       assert_page_property __method__

data/lib/notion_ruby_mapping/properties/property.rb

@@ -1,12 +1,8 @@
 # frozen_string_literal: true
 
-require "forwardable"
-
 module NotionRubyMapping
   # abstract class for property
   class Property
-    extend Forwardable
-
     ### Public announced methods
 
     ## Common methods
@@ -14,18 +10,6 @@ module NotionRubyMapping
     attr_reader :name, :will_update, :property_id
     attr_accessor :property_cache
 
-    def_delegators :retrieve_page_property, :<<, :[], :add_person, :add_relation, :checkbox, :checkbox=, :created_by,
-                   :created_time, :date, :each, :email, :email=, :end_date, :end_date=, :files, :files=, :filter_after,
-                   :filter_before, :filter_contains, :filter_does_not_contain, :filter_does_not_equal,
-                   :filter_ends_with, :filter_equals, :filter_greater_than, :filter_greater_than_or_equal_to,
-                   :filter_is_empty, :filter_is_not_empty, :filter_less_than, :filter_less_than_or_equal_to,
-                   :filter_next_month, :filter_next_week, :filter_next_year, :filter_on_or_after, :filter_on_or_before,
-                   :filter_past_month, :filter_past_week, :filter_past_year, :filter_starts_with, :formula, :full_text,
-                   :last_edited_by, :last_edited_time, :multi_select, :multi_select=, :multi_select_names, :number,
-                   :number=, :people, :people=, :phone_number, :phone_number=, :property_values_json, :relation=,
-                   :rollup, :start_date, :start_date=, :time_zone, :time_zone=, :select, :select=, :select_name, :url,
-                   :url=, :start_date_obj, :end_date_obj
-
     ## Database property only methods
 
     # @param [String] new_name
@@ -72,12 +56,13 @@ module NotionRubyMapping
 
       type = input_json["type"]
       if type.nil?
-        new name, property_id: input_json["id"], base_type: base_type, property_cache: property_cache, query: query
+        raise StandardError, "Property value is not returned: #{name}"
       elsif type == "property_item"
         tmp = new name, property_id: input_json["property_item"]["id"], base_type: base_type,
                         property_cache: property_cache, query: query
         objects = List.new(json: input_json, type: "property", value: tmp, query: query).to_a
-        case input_json["property_item"]["type"]
+        input_type = input_json["property_item"]["type"]
+        case input_type
         when "people"
           PeopleProperty.new name, people: objects, base_type: base_type,
                                    property_cache: property_cache, query: query
@@ -94,7 +79,7 @@ module NotionRubyMapping
           TitleProperty.new name, text_objects: objects, base_type: base_type,
                                   property_cache: property_cache, query: query
         else
-          raise StandardError, "Irregular property type: #{input_json["property_item"]["type"]}"
+          raise StandardError, "Unsupported property type: #{input_type} (#{name}). Please update notion_ruby_mapping."
         end
       else
         klass = {
@@ -123,7 +108,10 @@ module NotionRubyMapping
           url: UrlProperty,
           verification: VerificationProperty,
         }[type.to_sym]
-        raise StandardError, "Irregular property type: #{type}" unless klass
+        unless klass
+          raise StandardError,
+                "Unsupported property type: #{type} (#{name}). Please update notion_ruby_mapping."
+        end
 
         answer = klass.new name, property_id: input_json["id"], json: input_json[type], base_type: base_type,
                                  property_cache: property_cache
@@ -152,11 +140,6 @@ module NotionRubyMapping
       %w[database data_source].include? @base_type
     end
 
-    # @return [TrueClass, FalseClass] true if it has Property contents
-    def contents?
-      !instance_of? Property
-    end
-
     # @param [String] key query parameter
     # @param [Object] value query value
     # @return [NotionRubyMapping::Query] generated Query object
@@ -180,9 +163,9 @@ module NotionRubyMapping
     # @param [Hash] json
     def update_from_json(json)
       @will_update = false
-      return unless contents?
+      return unless json.key?(type)
 
-      @json = json[type] if json[type] && json[type] != "property_item"
+      @json = json[type]
     end
 
     # @return [Symbol] property type
@@ -192,14 +175,9 @@ module NotionRubyMapping
 
     ## Database property only methods
 
-    # @param [Symbol, nil] method
-    def assert_database_property(method)
-      raise StandardError, "#{method} can execute only Database property." unless database?
-    end
-
     # @param [Symbol, nil] method
     def assert_database_or_data_source_property(method)
-      raise StandardError, "#{method} can execute only Database property." if page?
+      raise StandardError, "#{method} can execute only Database or DataSource property." unless database_or_data_source?
     end
 
     # @return [Hash]
@@ -209,6 +187,7 @@ module NotionRubyMapping
     end
 
     ## DataSource property only methods
+    # @param [Symbol, nil] method
     def assert_data_source_property(method)
       raise StandardError, "#{method} can execute only DataSource property." unless data_source?
     end
@@ -229,7 +208,7 @@ module NotionRubyMapping
 
     # @param [Symbol, nil] method
     def assert_page_property(method)
-      raise StandardError, "#{method} can execute only Page property." if database? || data_source?
+      raise StandardError, "#{method} can execute only Page property." unless page?
     end
 
     # @return [NotionRubyMapping::Property, Array<UserObject>, nil]

data/lib/notion_ruby_mapping/properties/relation_property.rb

@@ -1,15 +1,16 @@
 # frozen_string_literal: true
 
 module NotionRubyMapping
-  # MultiSelect property
+  # Relation property
   class RelationProperty < MultiProperty
     TYPE = "relation"
+    RELATION_PROPERTY_TYPES = %w[dual_property single_property].freeze
 
     ### Public announced methods
 
     ## Common methods
 
-    # @return [Hash, Array, nil]
+    # @return [Array<Hash>, Hash, nil] relation value or relation schema
     # @see https://www.notion.so/hkob/RelationProperty-f608ab41a1f0476b98456620346fba03#6c14207b2d1340d2bbc08d17eee2cb22
     def relation
       @json
@@ -35,6 +36,7 @@ module NotionRubyMapping
     def relation=(page_ids_or_jsons)
       assert_page_property __method__
       @will_update = true
+      page_ids_or_jsons = [] if page_ids_or_jsons.nil?
       page_ids_or_jsons = [page_ids_or_jsons] unless page_ids_or_jsons.is_a? Array
 
       @json = page_ids_or_jsons.map do |page_id_or_json|
@@ -47,7 +49,7 @@ module NotionRubyMapping
     # @return [String] relation data_source_id
     # @see https://www.notion.so/hkob/RelationProperty-f608ab41a1f0476b98456620346fba03#eb40f1a2ad5c4e368d343870a7e529f9
     def relation_data_source_id
-      assert_data_source_property __method__
+      assert_database_or_data_source_property __method__
       @json["data_source_id"]
     end
 
@@ -56,6 +58,8 @@ module NotionRubyMapping
     # @see https://www.notion.so/hkob/RelationProperty-f608ab41a1f0476b98456620346fba03#7f5029fb7f6e4c009f22888b233e6f64
     def replace_relation_data_source(data_source_id: nil, type: "dual_property")
       assert_database_or_data_source_property __method__
+      raise ArgumentError, "type must be dual_property or single_property" unless RELATION_PROPERTY_TYPES.include? type
+
       @will_update = true
       @json["data_source_id"] = data_source_id if data_source_id
       @json["type"] = type
@@ -97,10 +101,6 @@ module NotionRubyMapping
       ans
     end
 
-    def data_source_id
-      @json["data_source_id"]
-    end
-
     # @return [TrueClass, FalseClass] true if dual_property
     def dual_property?
       assert_database_or_data_source_property __method__

data/lib/notion_ruby_mapping/properties/rich_text_property.rb

@@ -9,28 +9,6 @@ module NotionRubyMapping
 
     ## Common methods
 
-    # @param [Hash] json
-    def update_from_json(json)
-      @will_update = false
-      if database_or_data_source?
-        @json = json["rich_text"] || {}
-      else
-        @text_objects = RichTextArray.new "rich_text", json: json["rich_text"]
-      end
-    end
-
     ## Page property only methods
-
-    # @return [Hash] created json
-    def property_values_json
-      assert_page_property __method__
-      text_json = @text_objects.map(&:property_values_json)
-      {
-        @name => {
-          "type" => "rich_text",
-          "rich_text" => text_json.empty? ? (@json || []) : text_json,
-        },
-      }
-    end
   end
 end

data/lib/notion_ruby_mapping/properties/select_property.rb

@@ -11,7 +11,7 @@ module NotionRubyMapping
 
     ## Common methods
 
-    # @return [Hash]
+    # @return [Hash] raw select object for page property, or select schema object for database/data_source property
     # @see https://www.notion.so/hkob/SelectProperty-6d6a0defa70d4b26af0fdbdcfbf99f28#7ad3734ac42c43068f1e04633bab400b
     def select
       @json
@@ -19,7 +19,7 @@ module NotionRubyMapping
 
     ## Page property only methods
 
-    # @return [String]
+    # @return [String, nil]
     # @see https://www.notion.so/hkob/SelectProperty-6d6a0defa70d4b26af0fdbdcfbf99f28#27a05e52715a4acd9156b5f146653e51
     def select_name
       assert_page_property __method__
@@ -30,27 +30,27 @@ module NotionRubyMapping
 
     # @param [String] name
     # @param [String] color
-    # @return [Array] added array
+    # @return [Array<Hash>] updated select options
     # @see https://www.notion.so/hkob/SelectProperty-6d6a0defa70d4b26af0fdbdcfbf99f28#3e1c7dbda7fb455f94ee93d9653b7880
     def add_select_option(name:, color:)
       edit_select_options << {"name" => name, "color" => color}
     end
 
-    # @return [Array] copyed multi select options
+    # @return [Array<Hash>] editable select options
     def edit_select_options
       assert_database_or_data_source_property __method__
       @will_update = true
       @json["options"] ||= []
     end
 
-    # @return [Array]
+    # @return [Array<Hash>]
     # @see https://www.notion.so/hkob/SelectProperty-6d6a0defa70d4b26af0fdbdcfbf99f28#790a297f2c1b4ba5a4d86074d4c70a89
     def select_options
       assert_database_or_data_source_property __method__
       @json["options"] || []
     end
 
-    # @return [String]
+    # @return [Array<String>]
     # @see https://www.notion.so/hkob/SelectProperty-6d6a0defa70d4b26af0fdbdcfbf99f28#72da1632793c4a5296f3bc89de2df413
     def select_names
       assert_database_or_data_source_property __method__
@@ -59,12 +59,12 @@ module NotionRubyMapping
 
     ## Page property only methods
 
-    # @param [String] select
+    # @param [String, nil] name
     # @see https://www.notion.so/hkob/SelectProperty-6d6a0defa70d4b26af0fdbdcfbf99f28#3bd195bf5c0a498ebf850409f7deb67a
-    def select=(select)
+    def select=(name)
       assert_page_property __method__
       @will_update = true
-      @json = {"name" => select}
+      @json = {"name" => name}
     end
 
     ### Not public announced methods
@@ -72,8 +72,8 @@ module NotionRubyMapping
     ## Common methods
 
     # @param [String, Symbol] name Property name
-    # @param [Hash] json
-    # @param [String] select String value (optional)
+    # @param [Hash, nil] json
+    # @param [String, nil] select select option name (optional)
     def initialize(name, will_update: false, base_type: "page", json: nil, select: nil, property_id: nil,
                    property_cache: nil)
       super name, will_update: will_update, base_type: base_type, property_id: property_id,

data/lib/notion_ruby_mapping/properties/status_property.rb

@@ -25,8 +25,6 @@ module NotionRubyMapping
       @json["name"]
     end
 
-    ## Page property only methods
-
     # @param [String] status
     # @see https://www.notion.so/hkob/StatusProperty-c8b2c83019bc42edbc1527386c7ef453#b3fba1b6322140f28308de3ba70a8b7b
     def status=(status)
@@ -35,6 +33,35 @@ module NotionRubyMapping
       @json = {"name" => status}
     end
 
+    ## Database or DataSource property only methods
+    # @param [String] name
+    # @param [String] color
+    # @return [Array<Hash>] updated status options
+    def add_status_option(name:, color:, group: nil)
+      hash = {"name" => name, "color" => color}
+      hash["group"] = group if group
+      edit_status_options << hash
+    end
+
+    # @return [Array<Hash>] editable status options
+    def edit_status_options
+      assert_database_or_data_source_property __method__
+      @will_update = true
+      @json["edit_options"] ||= []
+    end
+
+    # @return [Array<Hash>] status options
+    def status_options
+      assert_database_or_data_source_property __method__
+      @json["options"] || []
+    end
+
+    # @return [Array<String>] status option names
+    def status_names
+      assert_database_or_data_source_property __method__
+      status_options.map { |s| s["name"] }
+    end
+
     ### Not public announced methods
 
     ## Common methods
@@ -54,5 +81,26 @@ module NotionRubyMapping
       assert_page_property __method__
       {@name => {"status" => @json, "type" => "status"}}
     end
+
+    ## Database property only methods
+
+    # @return [Hash]
+    def update_property_schema_json
+      assert_database_or_data_source_property __method__
+      ans = super
+      return ans if ans != {} || !@will_update
+
+      ans[@name] ||= {}
+      ans[@name]["status"] ||= {}
+      ans[@name]["status"]["options"] = @json["edit_options"]
+      ans
+    end
+
+    ## Database property only methods
+
+    # @return [Hash]
+    def property_schema_json_sub
+      @json["edit_options"] ? {"options" => @json["edit_options"]} : {}
+    end
   end
 end

data/lib/notion_ruby_mapping/properties/text_property.rb

@@ -5,6 +5,7 @@ require "forwardable"
 module NotionRubyMapping
   # Text property
   class TextProperty < Property
+    TYPE = "text"
     extend Forwardable
     include Enumerable
     include EqualsDoesNotEqual
@@ -36,10 +37,67 @@ module NotionRubyMapping
       @text_objects = if database_or_data_source?
                         json || {}
                       else
-                        RichTextArray.new "title", json: json, text_objects: text_objects
+                        RichTextArray.new self.class::TYPE, json: json, text_objects: text_objects
                       end
     end
 
+    def self.rich_text_array_from_json(json)
+      if json["object"] == "list"
+        rich_text_objects = List.new(json: json, type: "property", value: self).select { true }
+        RichTextArray.rich_text_array self::TYPE, rich_text_objects
+      else
+        RichTextArray.new self::TYPE, json: json[self::TYPE]
+      end
+    end
+
+    # @return [Hash] created json
+    def property_values_json
+      assert_page_property __method__
+      text_json = @text_objects.map(&:property_values_json)
+      {
+        @name => {
+          "type" => self.class::TYPE,
+          self.class::TYPE => text_json.empty? ? (@json || []) : text_json,
+        },
+      }
+    end
+
+    # Replaces all rich text objects with a single plain text object.
+    #
+    # This method does not preserve annotations, links, mentions, or equations.
+    #
+    # @param [String] text
+    # @raise [ArgumentError] if text is nil
+    def plain_text=(text)
+      assert_page_property __method__
+      raise ArgumentError if text.nil?
+
+      @text_objects = RichTextArray.new(
+        self.class::TYPE,
+        text_objects: text,
+      )
+      @will_update = true
+    end
+
+    # @param [Hash] json
+    def update_from_json(json)
+      @will_update = false
+      if database_or_data_source?
+        @json = json[self.class::TYPE] || {}
+      else
+        @text_objects = self.class.rich_text_array_from_json json
+      end
+    end
+
+    # Removes all rich text objects.
+    #
+    # This method makes the property value an empty rich text array.
+    def clear
+      assert_page_property __method__
+      @text_objects.clear
+      @will_update = true
+    end
+
     # @return [FalseClass]
     def clear_will_update
       super

data/lib/notion_ruby_mapping/properties/title_property.rb

@@ -9,44 +9,6 @@ module NotionRubyMapping
 
     ## Common methods
 
-    def self.rich_text_array_from_json(json)
-      if json["object"] == "list"
-        rich_text_objects = List.new(json: json, type: "property", value: self).select { true }
-        RichTextArray.rich_text_array "title", rich_text_objects
-      else
-        RichTextArray.new "title", json: json["title"]
-      end
-    end
-
-    # @param [Hash] json
-    def update_from_json(json)
-      @will_update = false
-      if database_or_data_source?
-        @json = json || {}
-      else
-        @text_objects = TitleProperty.rich_text_array_from_json json
-      end
-    end
-
     ## Page property only methods
-
-    # @return [FalseClass]
-    def clear_will_update
-      super
-      @text_objects.clear_will_update
-      false
-    end
-
-    # @return [Hash] created json
-    def property_values_json
-      assert_page_property __method__
-      text_json = map(&:property_values_json)
-      {
-        @name => {
-          "type" => "title",
-          "title" => text_json.empty? ? @json : text_json,
-        },
-      }
-    end
   end
 end

data/lib/notion_ruby_mapping/properties/unique_id_property.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module NotionRubyMapping
-  # Number property
+  # Unique ID property
   class UniqueIdProperty < Property
     include EqualsDoesNotEqual
     include GreaterThanLessThan
@@ -17,8 +17,26 @@ module NotionRubyMapping
       @json
     end
 
+    # @return [String, nil]
+    def prefix
+      @json && @json["prefix"]
+    end
+
+    # @return [Integer, nil]
+    def number
+      @json && @json["number"]
+    end
+
     ## Database property only methods
 
+    # @param [String, nil] prefix
+    # @return [String, nil]
+    def prefix=(prefix)
+      assert_database_or_data_source_property __method__
+      @will_update = true
+      @json["prefix"] = prefix
+    end
+
     ## Page property only methods
 
     ### Not public announced methods
@@ -26,7 +44,7 @@ module NotionRubyMapping
     ## Common methods
 
     # @param [String] name Property name
-    # @param [Float, Integer, Hash] json Number value or format Hash
+    # @param [Hash, nil] json unique_id Hash
     def initialize(name, will_update: false, base_type: "page", json: nil, property_id: nil, property_cache: nil)
       super name, will_update: will_update, base_type: base_type, property_id: property_id, property_cache: property_cache
       @json = json
@@ -34,7 +52,7 @@ module NotionRubyMapping
     end
 
     # @param [Hash] json
-    # @return [NotionRubyMapping::NumberProperty]
+    # @return [NotionRubyMapping::UniqueIdProperty]
     def update_from_json(json)
       @will_update = false
       @json = json["unique_id"]
@@ -43,6 +61,17 @@ module NotionRubyMapping
 
     ## Database property only methods
 
+    # @return [Hash]
+    def update_property_schema_json
+      assert_database_or_data_source_property __method__
+      ans = super
+      return ans if ans != {} || !@will_update
+
+      ans[@name] ||= {}
+      ans[@name]["unique_id"] = @json
+      ans
+    end
+
     ## Page property only methods
 
     # @return [Hash]
@@ -51,6 +80,13 @@ module NotionRubyMapping
       {@name => {"unique_id" => @json, "type" => "unique_id"}}
     end
 
+    protected
+
     ## Database property only methods
+
+    # @return [Hash]
+    def property_schema_json_sub
+      {"prefix" => prefix}
+    end
   end
 end

data/lib/notion_ruby_mapping/properties/url_property.rb

@@ -13,7 +13,7 @@ module NotionRubyMapping
 
     ## Common methods
 
-    # @return [String, Hash, nil] url (Page), {} (Database)
+    # @return [String, Hash, nil] URL for page properties, empty hash for database/data source properties
     # @see https://www.notion.so/hkob/UrlProperty-8a0094fdf6494151983cb4694f6626cc#8342eef7df3c43eaad10c48d4757b4ae
     def url
       @json
@@ -21,7 +21,7 @@ module NotionRubyMapping
 
     ## Page property only methods
 
-    # @param [String] url
+    # @param [String, nil] url
     # @see https://www.notion.so/hkob/UrlProperty-8a0094fdf6494151983cb4694f6626cc#cfa5463a121b4002b250b38d7d0a0d34
     def url=(url)
       assert_page_property __method__
@@ -37,7 +37,7 @@ module NotionRubyMapping
     def initialize(name, will_update: false, base_type: "page", json: nil, property_id: nil, property_cache: nil)
       super name, will_update: will_update, base_type: base_type, property_id: property_id,
                   property_cache: property_cache
-      @json = json || (database_or_data_source? ? {} : nil)
+      @json = database_or_data_source? ? {} : json
     end
 
     ## Page property only methods

data/lib/notion_ruby_mapping/properties/verification_property.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module NotionRubyMapping
-  # Status property
+  # Verification property
   class VerificationProperty < Property
     TYPE = "verification"
 
@@ -9,21 +9,16 @@ module NotionRubyMapping
 
     ## Common methods
 
-    # @see https://www.notion.so/hkob/StatusProperty-c8b2c83019bc42edbc1527386c7ef453#bdb34c0aeaa74729887da087d0bd8022
     def verification
       @json
     end
 
-    ## Page property only methods
-
-    ## Page property only methods
-
     ### Not public announced methods
 
     ## Common methods
 
     # @param [String, Symbol] name Property name
-    # @param [Boolean, Hash] json
+    # @param [Hash] json
     def initialize(name, will_update: false, base_type: "page", property_id: nil, property_cache: nil, json: {})
       super name, will_update: will_update, base_type: base_type, property_id: property_id,
                   property_cache: property_cache
@@ -32,11 +27,12 @@ module NotionRubyMapping
 
     ## DataSource only methods
 
-    # @param [String, Number] value Query value
-    # @param [String] condition rollup Rollup name
-    # @param [String] another_type rollup_type Rollup type
-    # @return [NotionRubyMapping::Query] generated Query object
-    # @see https://www.notion.so/hkob/CheckboxProperty-ac1edbdb8e264af5ad1432b522b429fd#5f07c4ebc4744986bfc99a43827349fc
+    # Creates a filter query for the verification status.
+    #
+    # @param [String] value Verification status. Expected values are "verified", "expired", and "none".
+    # @param [String, nil] condition Rollup condition name.
+    # @param [String, nil] another_type Rollup target type.
+    # @return [NotionRubyMapping::Query] Generated Query object.
     def filter_status(value, condition: nil, another_type: nil)
       make_filter_query "status", value, condition: condition, another_type: another_type
     end

data/lib/notion_ruby_mapping/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module NotionRubyMapping
-  VERSION = "4.0.1"
+  VERSION = "4.1.0"
   NOTION_VERSION = "2026-03-11"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: notion_ruby_mapping
 version: !ruby/object:Gem::Version
-  version: 4.0.1
+  version: 4.1.0
 platform: ruby
 authors:
 - Hiroyuki KOBAYASHI
@@ -349,7 +349,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Notion Ruby mapping tool
 test_files: []