addressing 2.0.1 → 2.1.0

data/data/subdivision/GT.json

@@ -0,0 +1,71 @@
+{
+	"country_code": "GT",
+	"subdivisions": {
+		"16": {
+			"name": "Alta Verapaz"
+		},
+		"15": {
+			"name": "Baja Verapaz"
+		},
+		"04": {
+			"name": "Chimaltenango"
+		},
+		"20": {
+			"name": "Chiquimula"
+		},
+		"02": {
+			"name": "El Progreso"
+		},
+		"05": {
+			"name": "Escuintla"
+		},
+		"01": {
+			"name": "Guatemala"
+		},
+		"13": {
+			"name": "Huehuetenango"
+		},
+		"18": {
+			"name": "Izabal"
+		},
+		"21": {
+			"name": "Jalapa"
+		},
+		"22": {
+			"name": "Jutiapa"
+		},
+		"17": {
+			"name": "Petén"
+		},
+		"09": {
+			"name": "Quetzaltenango"
+		},
+		"14": {
+			"name": "Quiché"
+		},
+		"11": {
+			"name": "Retalhuleu"
+		},
+		"03": {
+			"name": "Sacatepéquez"
+		},
+		"12": {
+			"name": "San Marcos"
+		},
+		"06": {
+			"name": "Santa Rosa"
+		},
+		"07": {
+			"name": "Sololá"
+		},
+		"10": {
+			"name": "Suchitepéquez"
+		},
+		"08": {
+			"name": "Totonicapán"
+		},
+		"19": {
+			"name": "Zacapa"
+		}
+	}
+}

data/data/subdivision/IT.json

@@ -149,6 +149,10 @@
 			"code": "FR",
 			"name": "Frosinone"
 		},
+		"OT": {
+			"code": "OT",
+			"name": "Gallura Nord-Est Sardegna"
+		},
 		"GE": {
 			"code": "GE",
 			"name": "Genova"
@@ -217,6 +221,10 @@
 			"code": "MT",
 			"name": "Matera"
 		},
+		"VS": {
+			"code": "VS",
+			"name": "Medio Campidano"
+		},
 		"ME": {
 			"code": "ME",
 			"name": "Messina"
@@ -245,6 +253,10 @@
 			"code": "NU",
 			"name": "Nuoro"
 		},
+		"OG": {
+			"code": "OG",
+			"name": "Ogliastra"
+		},
 		"OR": {
 			"code": "OR",
 			"name": "Oristano"
@@ -359,7 +371,7 @@
 		},
 		"SU": {
 			"code": "SU",
-			"name": "Sud Sardegna"
+			"name": "Sulcis Iglesiente"
 		},
 		"TA": {
 			"code": "TA",

data/data/subdivision/NG.json

@@ -83,7 +83,7 @@
 			"name": "Niger"
 		},
 		"OG": {
-			"name": "Ogun State"
+			"name": "Ogun"
 		},
 		"ON": {
 			"name": "Ondo"

data/data/subdivision/RU.json

@@ -240,10 +240,6 @@
 			"name": "Tyva Republits",
 			"local_name": "Республика Тыва"
 		},
-		"UD": {
-			"name": "Udmurtskaja Respublika",
-			"local_name": "Республика Удмуртия"
-		},
 		"KK": {
 			"name": "Khakasiya Republits",
 			"local_name": "Республика Хакасия"
@@ -308,6 +304,10 @@
 			"name": "Tyumenskaya oblast'",
 			"local_name": "Тюменская область"
 		},
+		"UD": {
+			"name": "Udmurtskaja Respublika",
+			"local_name": "Удмуртская Республика"
+		},
 		"ULY": {
 			"name": "Ulyanovskaya oblast'",
 			"local_name": "Ульяновская область"

data/data/subdivision/TH.json

@@ -26,10 +26,6 @@
 			"name": "Khon Kaen",
 			"local_name": "ขอนแก่น"
 		},
-		"38": {
-			"name": "Bueng Kan",
-			"local_name": "จังหวัด บึงกาฬ"
-		},
 		"22": {
 			"name": "Chanthaburi",
 			"local_name": "จันทบุรี"
@@ -51,7 +47,7 @@
 			"local_name": "ชัยภูมิ"
 		},
 		"86": {
-			"name": "Chumpon",
+			"name": "Chumphon",
 			"local_name": "ชุมพร"
 		},
 		"57": {
@@ -110,6 +106,10 @@
 			"name": "Nan",
 			"local_name": "น่าน"
 		},
+		"38": {
+			"name": "Bueng Kan",
+			"local_name": "บึงกาฬ"
+		},
 		"31": {
 			"name": "Buri Ram",
 			"local_name": "บุรีรัมย์"
@@ -143,7 +143,7 @@
 			"local_name": "พังงา"
 		},
 		"93": {
-			"name": "Phattalung",
+			"name": "Phatthalung",
 			"local_name": "พัทลุง"
 		},
 		"66": {
@@ -267,7 +267,7 @@
 			"local_name": "สุโขทัย"
 		},
 		"72": {
-			"name": "Suphanburi",
+			"name": "Suphan Buri",
 			"local_name": "สุพรรณบุรี"
 		},
 		"84": {

data/data/subdivision/TR.json

@@ -8,7 +8,7 @@
 			"name": "Adıyaman"
 		},
 		"03": {
-			"name": "Afyon"
+			"name": "Afyonkarahisar"
 		},
 		"04": {
 			"name": "Ağrı"

data/data/subdivision/VE.json

@@ -32,7 +32,7 @@
 			"name": "Dependencias Federales"
 		},
 		"A": {
-			"name": "Distrito Federal"
+			"name": "Distrito Capital"
 		},
 		"I": {
 			"name": "Falcón"
@@ -40,6 +40,9 @@
 		"J": {
 			"name": "Guárico"
 		},
+		"X": {
+			"name": "La Guaira"
+		},
 		"K": {
 			"name": "Lara"
 		},
@@ -67,9 +70,6 @@
 		"T": {
 			"name": "Trujillo"
 		},
-		"X": {
-			"name": "La Guaira"
-		},
 		"U": {
 			"name": "Yaracuy"
 		},

data/data/subdivision/VN.json

@@ -60,7 +60,7 @@
 		},
 		"79": {
 			"name": "Ho Chi Minh City",
-			"local_name": "Thành phố Hồ Chí Minh"
+			"local_name": "Hồ Chí Minh"
 		},
 		"46": {
 			"name": "Hue City",

data/lib/addressing/address_format.rb

@@ -8,9 +8,17 @@ module Addressing
   #
   # @example Get address format for Brazil
   #   format = Addressing::AddressFormat.get('BR')
-  #   format.used_fields      # => ["given_name", "family_name", ...]
-  #   format.required_fields  # => ["address_line1", "locality", ...]
+  #   format.used_fields        # => ["given_name", "family_name", ...]
+  #   format.required_fields    # => ["address_line1", "locality", ...]
+  #   format.subdivision_fields # => ["administrative_area", "locality"]
   class AddressFormat
+    # The subdivision fields, ordered from the top level down.
+    SUBDIVISION_FIELDS = [
+      AddressField::ADMINISTRATIVE_AREA,
+      AddressField::LOCALITY,
+      AddressField::DEPENDENT_LOCALITY
+    ].freeze
+
     class << self
       # Gets the address format for the provided country code.
       #
@@ -63,13 +71,28 @@ module Addressing
           administrative_area_type: "province",
           locality_type: "city",
           dependent_locality_type: "suburb",
-          postal_code_type: "postal",
-          subdivision_depth: 0
+          postal_code_type: "postal"
         }
       end
     end
 
-    attr_reader :country_code, :locale, :format, :local_format, :required_fields, :uppercase_fields, :default_values, :administrative_area_type, :locality_type, :dependent_locality_type, :postal_code_type, :postal_code_pattern, :postal_code_prefix, :subdivision_depth
+    attr_reader :country_code, :locale, :format, :local_format, :required_fields, :uppercase_fields, :default_values, :administrative_area_type, :locality_type, :dependent_locality_type, :postal_code_type, :postal_code_pattern, :postal_code_prefix
+
+    # The subdivision fields for which there is predefined subdivision data.
+    #
+    # This is more precise than #used_subdivision_fields, which returns all
+    # subdivision fields used by the format regardless of whether data exists.
+    #
+    # @return [Array<String>] e.g. ["administrative_area", "locality"]
+    attr_reader :subdivision_fields
+
+    # The number of subdivision fields with predefined data used by the format.
+    #
+    # @deprecated Use #subdivision_fields instead.
+    # @return [Integer]
+    def subdivision_depth
+      (subdivision_fields & used_subdivision_fields).size
+    end
 
     def initialize(definition = {})
       # Validate the presence of required properties.
@@ -87,13 +110,16 @@ module Addressing
         uppercase_fields: [],
         default_values: {},
         postal_code_pattern: nil,
-        postal_code_prefix: nil,
-        subdivision_depth: 0
+        postal_code_prefix: nil
       }.merge(definition)
 
+      # Backwards compatibility: derive the subdivision fields from a depth.
+      definition[:subdivision_fields] ||= SUBDIVISION_FIELDS.first(definition[:subdivision_depth] || 0)
+
       AddressField.assert_all_exist(definition[:required_fields])
       AddressField.assert_all_exist(definition[:uppercase_fields])
       AddressField.assert_all_exist(definition[:default_values].keys)
+      AddressField.assert_all_exist(definition[:subdivision_fields])
 
       @country_code = definition[:country_code]
       @locale = definition[:locale]
@@ -102,7 +128,7 @@ module Addressing
       @required_fields = definition[:required_fields]
       @uppercase_fields = definition[:uppercase_fields]
       @default_values = definition[:default_values]
-      @subdivision_depth = definition[:subdivision_depth]
+      @subdivision_fields = definition[:subdivision_fields]
 
       if used_fields.include?(AddressField::ADMINISTRATIVE_AREA)
         if definition[:administrative_area_type]
@@ -144,15 +170,11 @@ module Addressing
     end
 
     # Gets the list of used subdivision fields.
+    #
+    # Note that a country might use a subdivision field without having
+    # predefined subdivisions for it, see #subdivision_fields.
     def used_subdivision_fields
-      fields = [
-        AddressField::ADMINISTRATIVE_AREA,
-        AddressField::LOCALITY,
-        AddressField::DEPENDENT_LOCALITY
-      ]
-
-      # Remove fields not used by the format.
-      fields & used_fields
+      SUBDIVISION_FIELDS & used_fields
     end
   end
 

data/lib/addressing/default_formatter.rb

@@ -4,6 +4,7 @@ module Addressing
   class DefaultFormatter
     DEFAULT_LOCALE = "en"
     FORMAT_PLACEHOLDER_PATTERN = /%[a-z1-9_]+/
+    FORMAT_SPLIT_PATTERN = /(#{FORMAT_PLACEHOLDER_PATTERN})/
     LEADING_TRAILING_PUNCTUATION_PATTERN = /\A[ \-,]+|[ \-,]+\z/
     MULTIPLE_SPACES_PATTERN = /\s\s+/
 
@@ -39,7 +40,7 @@ module Addressing
       view = render_view(view)
 
       replacements = view.map { |key, element| ["%#{key}", element] }.to_h
-      output = format_string.gsub(FORMAT_PLACEHOLDER_PATTERN) { |m| replacements[m] }
+      output = insert_values(format_string, replacements)
       output = clean_output(output)
 
       if options[:html]
@@ -99,6 +100,39 @@ module Addressing
       end.join(" ")
     end
 
+    # Inserts the rendered address fields into the format string.
+    #
+    # Empty fields need special handling. When one falls between two values,
+    # keep the separator before it and discard the one after it.
+    def insert_values(format_string, replacements)
+      format_string.split("\n", -1).map do |line|
+        rendered = +""
+        separator = ""
+        skipped = false
+
+        line.split(FORMAT_SPLIT_PATTERN, -1).each do |part|
+          unless replacements.key?(part)
+            # A separator before an empty field usually belongs to
+            # the value that came before it, so keep that one.
+            separator = part unless skipped
+            next
+          end
+
+          if replacements[part].empty?
+            skipped = true
+            next
+          end
+
+          rendered << separator if !rendered.empty? || !skipped
+          rendered << replacements[part]
+          separator = ""
+          skipped = false
+        end
+
+        rendered
+      end.join("\n")
+    end
+
     # Removes empty lines, leading punctuation, excess whitespace.
     def clean_output(output)
       output.split("\n").map { |line| line.gsub(LEADING_TRAILING_PUNCTUATION_PATTERN, "").strip.gsub(MULTIPLE_SPACES_PATTERN, " ") }.reject(&:empty?).join("\n")
@@ -116,22 +150,18 @@ module Addressing
       AddressField.all.map { |_, field| [field, address.send(field)] }.to_h
     end
 
-    # Resolves subdivision values to their display codes.
+    # Replaces the subdivision values with the codes of any predefined ones.
     def resolve_subdivision_values(values, address, address_format)
-      subdivision_fields = address_format.used_subdivision_fields
+      parents = [address.country_code]
 
-      # Replace the subdivision values with the names of any predefined ones.
-      subdivision_fields.each_with_index.inject([{}, []]) do |(original_values, parents), (field, index)|
+      address_format.subdivision_fields.each do |field|
         # This level is empty, so there can be no sublevels.
-        break if values[field].nil?
-
-        parents << ((index > 0) ? original_values[subdivision_fields[index - 1]] : address.country_code)
+        break if values[field].nil? || values[field].empty?
 
         subdivision = Subdivision.get(values[field], parents)
         break if subdivision.nil?
 
-        # Remember the original value so that it can be used for parents.
-        original_values[field] = values[field]
+        parents << values[field]
 
         # Replace the value with the expected code.
         use_local_name = Locale.match_candidates(address.locale, subdivision.locale)
@@ -139,8 +169,6 @@ module Addressing
 
         # The current subdivision has no children, stop.
         break unless subdivision.children?
-
-        [original_values, parents]
       end
     end
 

data/lib/addressing/model.rb

@@ -46,25 +46,24 @@ module Addressing
         end
 
         define_method :verify_subdivisions do |address, address_format, field_overrides|
-          # No predefined subdivisions exist, nothing to validate against.
-          return [] if address_format.subdivision_depth < 1
+          parents = [address_format.country_code]
+          subdivisions = []
 
-          subdivisions, _parents = address_format.used_subdivision_fields.each_with_index.inject([[], []]) do |(subdivisions, parents), (field, index)|
+          address_format.subdivision_fields.each do |field|
+            value = address.send(field)
             # The field is empty or validation is disabled.
-            break [subdivisions, parents] if address.send(field).blank? || field_overrides.hidden_fields.include?(field)
+            break if value.blank? || field_overrides.hidden_fields.include?(field)
 
-            parents << ((index > 0) ? address.send(address_format.used_subdivision_fields[index - 1]) : address_format.country_code)
-            subdivision = Subdivision.get(address.send(field), parents)
+            subdivision = Subdivision.get(value, parents)
             if subdivision.nil?
               errors.add(field, "should be valid")
-              break [subdivisions, parents]
+              break
             end
 
+            parents << value
             subdivisions << subdivision
             # No predefined subdivisions below this level, stop here.
-            break [subdivisions, parents] if subdivision.children.empty?
-
-            [subdivisions, parents]
+            break unless subdivision.children?
           end
 
           subdivisions

data/lib/addressing/subdivision.rb

@@ -58,8 +58,8 @@ module Addressing
       def has_data(parents)
         country_code = parents[0]
 
-        depth = AddressFormat.get(country_code).subdivision_depth
-        return false if depth == 0
+        subdivision_fields = AddressFormat.get(country_code).subdivision_fields
+        return false if subdivision_fields.empty?
 
         if parents.size > 1
           # After the first level it is possible for predefined subdivisions
@@ -74,8 +74,9 @@ module Addressing
             definition = @definitions[parent_group]["subdivisions"][parent_id]
             return !!definition["has_children"]
           else
-            # The parent definition wasn't loaded previously, fallback to guessing based on depth.
-            return parents.size <= depth
+            # The parent definition wasn't loaded previously, fallback to
+            # guessing based on the count of subdivision data fields.
+            return parents.size <= subdivision_fields.size
           end
         end
 
@@ -98,19 +99,30 @@ module Addressing
           filename = File.join(File.expand_path("../../../data/subdivision", __FILE__).to_s, "#{group}.json")
 
           if File.exist?(filename)
-            raw_definition = File.read(filename)
-            @definitions[group] = JSON.parse(raw_definition)
-            @definitions[group] = process_definitions(@definitions[group])
+            @definitions[group] = process_definitions(parse_definitions(File.read(filename)))
           end
         end
 
         @definitions[group]
       end
 
+      # Parses a raw definition file.
+      #
+      # Malformed JSON is treated as if the file didn't exist.
+      def parse_definitions(raw_definition)
+        definitions = JSON.parse(raw_definition)
+        definitions.is_a?(Hash) ? definitions : {}
+      rescue JSON::ParserError
+        {}
+      end
+
       # Processes the loaded definitions.
       #
       # Adds keys and values that were removed from the JSON files for brevity.
       def process_definitions(definitions)
+        # Malformed definitions are treated as if they didn't exist.
+        return {} unless definitions["subdivisions"].is_a?(Hash)
+
         definitions["subdivisions"].each do |id, definition|
           # Add common keys from the root level.
           definition["country_code"] = definitions["country_code"]
@@ -124,6 +136,12 @@ module Addressing
             definition["name"] = id
           end
 
+          # The local_name value is only specified if it doesn't match
+          # the name one.
+          if definitions.key?("locale") && !definition.key?("local_name")
+            definition["local_name"] = definition["name"]
+          end
+
           # The code and local_code values are only specified if they
           # don't match the name and local_name ones.
           if !definition.key?("code") && definition.key?("name")

data/lib/addressing/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Addressing
-  VERSION = "2.0.1"
+  VERSION = "2.1.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: addressing
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.1.0
 platform: ruby
 authors:
 - Robin van der Vleuten
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-27 00:00:00.000000000 Z
+date: 2026-09-18 00:00:00.000000000 Z
 dependencies: []
 description:
 email: robinvdvleuten@gmail.com
@@ -617,6 +617,8 @@ files:
 - data/subdivision/EG.json
 - data/subdivision/ES.json
 - data/subdivision/FM.json
+- data/subdivision/GB.json
+- data/subdivision/GT.json
 - data/subdivision/HK-2705954f46a43ef0ad522412afe6ed6ee8196fe4.json
 - data/subdivision/HK-29ceaf41d01206ba481b188116cbb302b82663cf.json
 - data/subdivision/HK-ff51a84233701e6a1d18f70acf4b3f909e4c6a09.json